/api-platform-filters

name: api-platform-filters
description: "Implement API Platform filters - Parameters API (QueryParameter, v5/4.4/4.3) and the #[ApiFilter] attribute deprecated since 4.4 - for search, date, range, boolean, and custom filtering"
capabilities: [read, search, edit, shell]
tags: [api-platform]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash

Api Platform Filters (Symfony)

Use when

• A collection endpoint needs search, exact match, range, date, boolean, or sort query parameters.
• One query parameter must search across several properties.
• A filter needs custom query logic that the built-in filters do not cover.
• Migrating `#[ApiFilter]` declarations (deprecated since 4.4) to the Parameters API, by hand or with `api:upgrade-filter`.

Default workflow

1. Declare `parameters` with `QueryParameter` on the operation; keep `#[ApiFilter]` only in 3.4 code or code not yet migrated. 2. Choose a filter class per parameter, checking the installed version: `ExactFilter`, `PartialSearchFilter`, `FreeTextQueryFilter`, `OrFilter`, `IriFilter` (4.2+), `ComparisonFilter`, `SortFilter` (4.3+), `StartSearchFilter`, `EndSearchFilter`, `ChainFilter` (4.4+). 3. For a custom filter, implement `FilterInterface` and read the bound value from `$context['parameter']` (`AbstractFilter` and `filterProperty()` are deprecated since 4.4: keep them for 4.3 and 3.4 code). 4. Turn on `strictQueryParameterValidation` so unknown query parameters return 400. 5. Add `#[ORM\Index]` on filtered columns, then request the endpoint with matching and non-matching values.

Guardrails

• Keep filter classes stateless: take request data from `$context`, not the constructor.
• Expose only the properties clients need to filter on.
• Use exact matching for ids and foreign keys: partial `LIKE %value%` cannot use an index.
• In custom filters, validate the value and bind it with `generateParameterName()` and `setParameter()`, never by string concatenation.

Progressive disclosure

• Use this file for execution posture and risk controls.
• Open references when deep implementation details are needed.

Output contract

• The parameters per operation, with filter class and accepted syntax (for example `?price[gte]=1000`).
• Indexes added for the filtered columns.
• Tests for a match, an empty result, and an unknown parameter.

References

• `reference.md`