api-platform-filters

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