Download the PHP package maikschneider/tca-api without Composer

State: Beta (0.2.0) — feedback and contributions very welcome. See GitHub Discussions to help validate the architecture, security model, and design decisions before they stabilize.

Motivation

TYPO3 offers several existing approaches for serving content as structured data. TCA_API was built to fill a gap where other API extensions fall short: exposing multiple resources uniformly, with minimal boilerplate and strong query efficiency.

See the Motivation chapter in the documentation for the full comparison.

Features

• Full CRUD — List, show, create, update and delete operations
• Hydra JSON-LD — Responses follow the Hydra specification (application/ld+json)
• Configuration-driven — Expose tables by registering a PHP configuration array; no custom controllers needed
• Serialization groups — Use groups to control which columns appear per operation
• Filtering — Exact, partial, word-start, range, full-text search, and many-to-many filter strategies via query parameters; configurable defaults and private (non-overrideable) filters; extensible via FilterInterface
• Sorting — Configurable allowed sort columns with defaults
• Pagination — Offset-based pagination with Hydra PartialCollectionView links
• Validation — Required, maxLength, minLength, and regex validators with structured 422 error responses
• File uploads — multipart/form-data file uploads on write endpoints with per-column FAL storage, size limits, and filename masks
• Access control — Per-operation roles: PUBLIC, FE_USER, FE_GROUP, BE_USER, BE_ADMIN, OWNER (record-level ownership), or custom callables
• Write privilege model — Actor-aware write context with configurable execution strategy, per-table access control, system-table deny list, and structured audit logging
• Relation handling — Plain IRI strings or fully embedded related records (configurable depth); create new related records inline on POST/PUT/PATCH
• Userinfo endpoint — Expose the authenticated FE user's own record at a configurable URL
• OpenAPI + Swagger UI — Auto-generated OpenAPI 3.1.0 spec and interactive Swagger UI served directly from the API prefix
• API Platform compatible — Responses follow the Hydra JSON-LD spec and work with API Platform and its ecosystem
• PSR-14 events — Hook into the request lifecycle with Before/AfterOperation and Before/AfterWrite events
• TYPO3 DataHandler — Write operations use TYPO3's DataHandler for safe, consistent data manipulation
• Response caching — Tag-based HTTP response caching for list and show operations with automatic invalidation via the TYPO3 DataHandler hook; configurable TTL and per-request bypass
• Multi-language — URL base segments (/de/api/...) and an optional X-Locale header resolve the TYPO3 SiteLanguage; queries constrain on sys_language_uid, translations overlay default-language rows honouring the site's fallbackType, sys_language_uid = -1 records stay visible, and cache keys are language-scoped
• Extensible handler pipeline — Register custom operation handlers or override built-in ones from any extension
• TCA-style overrides — Override or extend any resource config shipped by a third-party package via Configuration/TcaApi/Overrides/ — mirrors TYPO3's $GLOBALS['TCA'] + TCA/Overrides/ pattern

Requirements

Demo

A demo project showcasing various TCA_API configurations is available at maikschneider/typo3-petstore. It serves as the reference for different resource setups (currently in early stages).

Installation

Site set

The extension ships a TYPO3 site set (maikschneider/tca-api). Add it to your site's config/sites/<site>/config.yaml:

This exposes the following site settings, configurable per site in the TYPO3 backend under Site Management → Sites → Settings:

Quick start

1. Create the resource configuration

Place a PHP file in Configuration/TcaApi/ inside any active TYPO3 extension. No manual registration is needed — the extension auto-discovers all *.php files from every active package's Configuration/TcaApi/ directory at boot time and caches the result.

Zero-config (read-only): the three required keys are enough. operations defaults to ['list', 'show'] and both are PUBLIC by default — no security block needed:

To enable write operations, add them explicitly:

Explicit mode (opt in by adding groups to any column — only columns with groups are then exposed):

2. Use the API

All resources are served under the /_api/ prefix:

Overriding third-party resource configs

Any active extension can modify a resource configuration defined by another extension — without forking it. This mirrors TYPO3's $GLOBALS['TCA'] + TCA/Overrides/ pattern.

Place a PHP file in Configuration/TcaApi/Overrides/ of any active extension. The file receives $GLOBALS['TCA_API'] populated with all base configs and can manipulate it freely:

Override files within a package run in alphabetical filename order. Across packages they run in TYPO3 package load order. Last write wins.

OpenAPI spec & Swagger UI

The extension generates a live OpenAPI 3.1.0 JSON spec from the registered resources and exposes two additional endpoints:

Access to both endpoints is controlled by the tca_api.openApiExposed and tca_api.swaggerUiEnabled site settings respectively. Both default to PUBLIC.

API Platform

TCA_API responses are compatible with API Platform and its ecosystem. A bundled React-based admin UI is available via the maikschneider/api-platform-admin site set — add it to your site's dependencies to activate it. This UI is intended for testing during extension development and may be removed in a future version.

Configuration reference

General

Column visibility

TCA_API has two visibility modes. The mode is auto-detected per resource:

Default mode — active when no column has groups set. All non-system TCA columns (i.e. not hidden, deleted, tstamp, crdate, language/workspace fields) are automatically exposed for read and write.

Explicit mode — active as soon as any column declares groups. Only columns with a matching groups entry are exposed; all others are hidden.

Serialization groups

Use groups instead of readable/writable to control visibility per operation:

Valid group names: list, show, create, update.

Columns reference

Each entry in columns maps to a database column. All keys are optional:

Field type support

The serializer automatically handles all TYPO3 TCA field types. Relational types are resolved via dedicated serializers; scalar types that store encoded data are decoded before output; sensitive types are excluded.

An explicit processor on a column definition always overrides the automatic handling described above.

Column callbacks

A callback is a lightweight alternative to a processor for post-processing a single column. Unlike a processor — which receives only the raw column value — a callback runs after every column and relation has been resolved, receives the fully serialized row plus the raw DB row, and its return value replaces the column's value:

The signature is (array $serializedRow, array $rawRow): mixed. The class is built via GeneralUtility::makeInstance(), so constructor DI works. Because callbacks run after relation resolving — and before virtual properties — they can read embedded relations, processor output, and sibling columns from $serializedRow, and a virtual property can in turn build on a column's callback result. Callbacks honour the column's visibility (groups) and sparse-fieldset (?fields[]=…) gates. The same callback key is also available on virtual properties.

Filters

Each filterable column maps to a filter class. Use the shorthand (class name only) or the options form (two-element array with class + config):

Built-in filter classes

For MmFilter, if the options array is omitted the extension derives the MM config from TCA automatically (requires a valid MM key on the field).

Default values and private filters

Two options available on any filter definition control server-side defaults and enforcement:

A private filter without a default has no effect (no value to enforce).

Filter query syntax

Plain top-level parameters are the primary style and are advertised by the hydra:search block:

The bracket notation is also accepted (required for RangeFilter sub-keys and legacy clients):

When both styles are present for the same column, the bracket form wins. Only columns declared as filters in the resource configuration are matched; other top-level parameters are ignored.

Search filter example

Sorting

Security

Assign an access role per operation. list and show default to PUBLIC; write operations default to DISABLED and must be explicitly configured:

Defaults

Write operations are disabled by default. You must explicitly configure security for create, update, and delete:

Available roles

You can also use a callable for fully custom logic:

Ownership

The ownership section enables declarative record-level security for write operations. It pairs with AccessRole::OWNER in the security config.

What this does:

• On create — the fe_user_id column is automatically set to the authenticated FE user's UID server-side. The client cannot supply this value; it is stripped from the request body regardless of the column's groups config.
• On update/delete — the record's fe_user_id is compared to the current FE user's UID. If they don't match the request returns 403.

Separate tracking vs. auth columns

Use setOnCreate when you want an additional tracking column alongside the auth column:

On create, both column and setOnCreate receive the FE user UID. column must be populated for OWNER auth to work on subsequent update/delete; setOnCreate provides an immutable "created by" audit trail in a separate DB column.

BE_ADMIN bypass

Backend admins bypass ownership checks by default. Set beAdminBypass: false to enforce ownership for admins too:

Ownership config reference

Behaviour notes

• AccessRole::OWNER without ownership.column configured → 403 (fail-secure)
• Unauthenticated request + OWNER → 403 (no FE user found)
• setOnCreate without a logged-in FE user → column is not set (no injection if user is null)
• Ownership columns are always stripped from client input regardless of groups config
• OWNER is only meaningful on update and delete; using it on list/show will always deny (no single record to compare against)

Caching

Enable tag-based HTTP response caching for list and show operations per resource:

How it works

• On a cache miss: the response body is stored with per-record tags ({table}_{uid}). Two headers are added: X-TCA-API-Cache: MISS and X-Cache-Tags: articles_1,articles_2.
• On a cache hit: the stored body is returned immediately with X-TCA-API-Cache: HIT. No handler or serializer runs.
• Bypass: when any parameter listed in parametersToIgnore is present in the request (top-level or nested under filters[…]), the cache is skipped entirely for that request.

Cache invalidation

Invalidation fires automatically via a DataHandler clearCachePostProc hook. When a record is saved or deleted through the TYPO3 backend, all cached responses tagged for the affected table are flushed.

Note: Write operations performed through the API itself (create, update, delete) do not trigger this hook. Cached list/show responses will remain valid until the next DataHandler operation touches the same table or the TTL expires. If your application writes records via the API and reads them back immediately, configure a short lifetime or disable caching for that resource.

Cache backend

By default the tca_api cache uses Typo3DatabaseBackend (stored in cf_tca_api / cf_tca_api_tags database tables). For production use, configure a faster backend in config/system/additional.php:

Multi-site note

Cache keys are scoped by resource name and query parameters but not by TYPO3 site. In multi-site setups where two sites use the same resource name (articles) with different storagePid or different records, their cache entries will collide. Use distinct resourceName values per site or disable caching until this is addressed.

Caching config reference

Write privilege model

Write operations (create, update, delete) pass through a write privilege model that controls execution strategy, enforces table-level access control, and logs every mutation with the actor's identity.

Write modes

Each resource has a configurable write mode that determines how writes are executed:

Configure per resource in the general section:

To opt into system admin mode for an internal resource:

⚠ Warning: system_admin mode bypasses TYPO3 access control. Only enable for internal APIs where the calling application is fully trusted.

Actor resolution

The write context resolves the acting user automatically from the request:

1. Frontend user — if frontend.user is present with a valid UID → actorType = 'fe_user'
2. Backend user — if $GLOBALS['BE_USER'] is authenticated → actorType = 'be_user'
3. No user — falls back to actorType = 'system' with system admin mode forced

In acting_user mode, the DataHandler's internal username encodes the real actor for traceability:

Table access control

A built-in table access control layer prevents writes to security-sensitive system tables. This applies regardless of write mode.

Denied tables (built-in)

The following tables are always blocked from API writes:

Custom allow/deny lists

Extend the table access control via Services.yaml:

Precedence: deny list always wins over allow list. A table in both lists is denied.

Audit logging

Every write operation is logged via PSR-3 with structured context data:

Denied writes are logged at WARNING level:

Logs are written to TYPO3's logging framework and can be routed to any PSR-3 compatible handler.

Validation

Configure validators per column:

Validation failures return 422 Unprocessable Entity:

File uploads

Columns with an upload key accept files via multipart/form-data on POST, PUT, and PATCH endpoints. Files are stored in a FAL storage folder and attached as sys_file_reference records.

Configuration

Add an upload key to any type=file TCA column:

Allowed file extensions are not set here — they come from the TCA column's allowed config (e.g. 'allowed' => 'jpg,jpeg,png').

Upload config reference

Sending requests

Validation errors

Upload violations return 422 Unprocessable Entity:

Relations

Relations are resolved automatically from the TCA schema. By default, related records are serialized as plain IRI strings:

This format is compatible with API Platform Admin and other Hydra clients that resolve IRIs on demand.

Embedding related records

Add 'embed' => true to a column to inline the full related record instead of an IRI string:

In default mode, embed alone is enough — it does not trigger explicit mode:

Response with embedded data:

Control recursion depth with 'embed' => ['depth' => 2]. The default depth is 1.

The related resource must be registered in the ApiRegistry for embedding to work.

Supported relation types

Creating related records on write

On POST, PUT, and PATCH you can create new related records inline by passing an assoc array instead of a UID. Three forms are accepted per relation field:

These forms work across the supported TCA relation types, with one important limitation for group fields noted below:

For type=group, inline creation of new related records is only supported when allowed contains exactly one table. Multi-table group relations still support linking existing records by UID, but not creating new related records inline. Atomicity: all records (parent + new children) are created in a single DataHandler call, so cross-references resolve correctly and no partial writes occur.

Ownership: if the related table has an ownership config, the ownership column is automatically injected and cannot be overridden by the client.

Security gate: new sub-records can only be created for tables that have their own entry in ApiRegistry. Objects for unregistered foreign tables are silently skipped; existing UID references still work.

Inline relations (type=inline + foreign_field)

Inline children carry a back-pointer column to the parent (foreign_field). The extension sets this column automatically via DataHandler's writeForeignField mechanism — you do not need to include the parent UID in the child object:

On PATCH, new inline children are appended; existing children are left untouched.

Virtual properties

Virtual properties are computed fields appended to the serialized output. They appear after all real columns (and after column callbacks) and can be driven by a callable, a column processor, or a file/image column reference.

A callback is not mutually exclusive with a processor or file reference: when both are present the processor/file produces the base value and the callback runs last as a final transform. A virtual-property callback always runs — after all columns, column callbacks, and its own base value — so it can read any column or earlier virtual property from $serializedRow.

Callable

The callable receives (array $serializedRow, array $rawRow) and returns any serializable value. $serializedRow reflects columns already serialized in this request (including their callbacks); $rawRow is the raw DB record. When a processor or file column is also set, the callback receives that resolved base value under the property's key in $serializedRow and may transform it.

Column processor

The processor implements ColumnProcessorInterface::process(mixed $value, array $config, array $context). Without a column key the value passed is null.

Referencing an existing column

Add a column key to source the virtual property's value from an existing DB column:

The processor receives the column's raw DB value instead of null. For file/image columns the file references are fetched automatically and the result of the virtual property's own file processor is returned — this lets you expose the same image at different sizes per operation:

The virtual property uses its own image config — the referenced column's original config is ignored.

Image processor config

The image key is an array with the following options. All are optional:

Output modes:

Without cropVariant (or cropVariant omitted) — all variants returned:

With cropVariant set — single variant inlined:

Visibility gate

Virtual properties respect the same serialization groups as regular columns. When any column has a groups key (explicit mode), virtual properties without groups are excluded:

Userinfo endpoint

A userinfo endpoint exposes the currently authenticated FE user's own record without requiring a UID in the URL. Set 'type' => 'userinfo' in the general section:

Behaviour:

• Only GET is allowed — write operations are not supported on userinfo endpoints.
• Returns 403 if no FE user is authenticated.
• All column features work as normal: embed, virtualProperties, column processors (see Virtual properties).
• The security and operations keys are ignored — access is always tied to FE user authentication.

Events

The extension dispatches PSR-14 events throughout the request lifecycle:

Example listener registration in Configuration/Services.yaml:

Custom operation handlers

The dispatcher routes each request through a handler pipeline — a prioritised list of objects that implement OperationHandlerInterface. Built-in handlers cover list, show, create, update, delete, and userinfo. Third-party extensions can add new operation types or replace built-in behaviour by registering their own handlers.

Interface

Request attributes

Before the handler loop, the dispatcher sets the following attributes on the PSR-7 request:

Writing a custom handler

Registering handlers

Register handlers in your extension's ext_localconf.php. The dispatcher iterates handlers highest priority first and dispatches to the first match, so setting a higher priority than the built-in 10 overrides a built-in handler for a given operation.

The HandlerRegistry uses TYPO3's DI container via GeneralUtility::makeInstance(), so constructor dependencies are injected automatically. The #[Autoconfigure(public: true)] attribute on the class is required for the container to expose the service.

Custom filters

Every filter strategy is a class that implements FilterInterface. The extension discovers all implementations automatically via Symfony DI — no Services.yaml registration is needed.

Interface

FilterContext is a typed readonly value object. Its properties are:

Use $context->option('key', $default) to read from options with a fallback default.

Using the custom filter

Declare it in the resource config using the class name directly:

To pass extra config to the filter, use the two-element array form:

That's all. The class is auto-tagged and auto-wired — no ext_localconf.php or Services.yaml changes required.

Development

This extension uses DDEV for local development, see CONTRIBUTING.md for setup instructions.