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
- Declare
parameters with QueryParameter on the operation; keep #[ApiFilter] only in 3.4 code or code not yet migrated.
- 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+).
- 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).
- Turn on
strictQueryParameterValidation so unknown query parameters return 400.
- 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
