Filters 

Negating a filter 

The negate option flips a filter to its negative form. It is a server-side decision read from the resource config — a client cannot invert a filter it was given:

'filters' => [
    // ?filters[color_id]=1     → WHERE color_id != 1
    // ?filters[color_id][]=1&filters[color_id][]=2 → WHERE color_id NOT IN (1, 2)
    'not_color' => [ExactFilter::class, ['negate' => true]],

    // records that carry none of the requested categories
    'without_categories' => [MmFilter::class, ['negate' => true]],
],

For LIKE filters the negation of "matches any of the values" is "matches none of them", so a list produces NOT LIKE p1 AND NOT LIKE p2. On a relation path the negation applies to the record as a whole (t.uid NOT IN (subquery)): an article whose other category still matches is excluded, which is what "articles without category News" means.

Direct negated comparisons (!=, NOT IN, NOT LIKE) exclude NULL values under SQL's null semantics. A nullable column therefore need not produce the complement of the positive filter. Relation-path negation instead tests whether any related record matches, as described above.

Comma-separated values 

Some clients cannot produce bracket arrays. Set separator to accept a list in a single scalar parameter instead:

'filters' => [
    'color_id' => [ExactFilter::class, ['separator' => ',']],  // ?filters[color_id]=1,2
],

Values are trimmed and empty entries dropped. Without the option a comma is an ordinary character in the value.

Bounding the list length 

A list is capped at 100 values to keep a crafted request from building an unbounded IN list. Exceeding the cap returns 400 Bad Request naming the filter and the limit, rather than truncating silently. Override it per filter with maxValues (0 disables the cap):

'filters' => [
    'color_id' => [ExactFilter::class, ['maxValues' => 10]],
],

Duplicate values are collapsed before the cap is checked.

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,

    // Require a record to carry *every* requested category
    // (?filters[topics][]=5&filters[topics][]=9), not just one of them
    'topics' => [MmFilter::class, ['match' => 'all']],

    // 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']],
],