Filters 

Basic filters 

use MaikSchneider\TcaApi\Filter\ExactFilter;
use MaikSchneider\TcaApi\Filter\PartialFilter;
use MaikSchneider\TcaApi\Filter\WordStartFilter;

'filters' => [
    'title'  => ExactFilter::class,            // ?filters[title]=Foo
    'name'   => PartialFilter::class,          // ?filters[name]=oo  → LIKE %oo%
    'slug'   => WordStartFilter::class,        // ?filters[slug]=Fo  → LIKE Fo%
],

Filtering by related records 

Several tools touch related records; the right one depends on what you filter by and where the reference is stored:

• relationField.uid also works for FK and MM relations, but prefer the FK column filter or MmFilter there — they avoid the extra join to the target table (the path form additionally requires the related record to be visible).
• Relation-path (dotted) filters must use the bracket form ?filters[…] — PHP rewrites dots in top-level parameter names to underscores.

Many-to-many filter 

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):

use MaikSchneider\TcaApi\Filter\MmFilter;

'filters' => [
    // Shorthand: derive MM config from TCA automatically
    'categories' => MmFilter::class,

    // Options form: supply MM table config explicitly
    'tags' => [
        MmFilter::class,
        [
            'mm_table'       => 'tx_myext_article_tag_mm',
            'mm_local_key'   => 'uid_local',
            'mm_foreign_key' => 'uid_foreign',
        ],
    ],
],

Relation-path filters 

A dotted filter key filters the resource by a column reached through one or more relations. The last path segment is a scalar column on the deepest related table; the segments before it are relations to traverse. The declared filter (ExactFilter below) performs the comparison on that column — the dot in the key is detected automatically, so there is no extra filter class to register:

use MaikSchneider\TcaApi\Filter\ExactFilter;

'filters' => [
    'color_id.name'           => ExactFilter::class,  // one FK hop     → the colour's name
    'categories.title'        => ExactFilter::class,  // one MM hop     → a category's title
    'related_items.name'      => ExactFilter::class,  // one inline hop → an inline child's name
    'categories.parent.title' => ExactFilter::class,  // two hops       → a category's parent's title
],

Usage (dotted keys require the bracket form — see the note below):

?filters[color_id.name]=Red
?filters[categories.title]=News
?filters[categories.parent.title]=Root

Any comparison filter can be the leaf. ExactFilter is the default; RangeFilter, WordStartFilter and PartialFilter compare the leaf column directly, and their options are forwarded through the options form:

'filters' => [
    'stock.updated_at' => [RangeFilter::class, ['type' => 'date']],
],

Search filter 

The search filter allows searching across multiple columns simultaneously:

use MaikSchneider\TcaApi\Filter\SearchFilter;

'filters' => [
    'q' => [
        SearchFilter::class,
        [
            'columns' => ['title', 'teaser', 'body'],
            'match'   => 'partial',            // 'partial' (default) or 'word_start'
        ],
    ],
],

Usage: ?filters[q]=typo3 — searches across all configured columns with WHERE (title LIKE '%typo3%' OR teaser LIKE '%typo3%' OR body LIKE '%typo3%').

'filters' => [
    'q' => [
        SearchFilter::class,
        ['columns' => ['title', 'categories.title', 'color_id.name']],
    ],
],

Range filter 

use MaikSchneider\TcaApi\Filter\RangeFilter;

'filters' => [
    'year'  => RangeFilter::class,
],

Usage: ?filters[year][gte]=2020&filters[year][lte]=2024

The bound DBAL parameter type is resolved in this order:

1. The explicit type filter option (escape hatch — see below).

2. The TCA configuration of the column:

   • type: number (integer format) → int
   • type: number, format: decimal → float
   • type: datetime without dbType (UNIX timestamp column) → int
   • type: datetime with dbType (native DATE/DATETIME/TIME) → string
   • type: input, eval: …,int,… → int
3. Autodetection from the request value (integers stay integers, decimal / numeric strings are bound as strings, non-numeric strings such as ISO dates are bound as strings).

Use the type option to override TCA-inferred and autodetected types — for example to keep digit-only strings (zero-padded SKU codes) intact, or to force a specific cast on a column whose TCA type does not map cleanly:

'filters' => [
    'created_at' => [RangeFilter::class, ['type' => 'date']],   // ?filters[created_at][gte]=2024-01-01
    'price'      => [RangeFilter::class, ['type' => 'float']],  // ?filters[price][lte]=99.99
    'sku'        => [RangeFilter::class, ['type' => 'string']], // preserves leading zeros
],

Supported type values: int, float, string, date, datetime (date and datetime are aliases of string).

Joining an additional table 

Use $qb->join() to add a JOIN inside apply(). Reference the main table via its alias t:

use MaikSchneider\TcaApi\Filter\FilterContext;
use MaikSchneider\TcaApi\Filter\FilterInterface;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;

final class TagFilter implements FilterInterface
{
    public function apply(QueryBuilder $qb, FilterContext $context): void
    {
        $qb->join(
                't',
                'tx_myext_domain_model_tag',
                'tag',
                $qb->expr()->eq('t.tag_id', $qb->quoteIdentifier('tag.uid')),
            )
            ->andWhere($qb->expr()->eq(
                'tag.name',
                $qb->createNamedParameter($context->value),
            ));
    }
}

The first argument of join() must be 't' — the alias under which DataRepository registered the resource table. Column references on the joined table (tag.name above) need no alias prefix.

FilterContext is a typed readonly value object:

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

Register it the same way as built-in filters:

'filters' => [
    'myColumn' => MyCustomFilter::class,
    // or with options — accessed via $context->option('key')
    'other'    => [MyCustomFilter::class, ['key' => 'value']],
],