Download the PHP package taranovegor/searcher-bundle without Composer

taranovegor/searcher-bundle

Filter, sort and paginate search component for Symfony applications, decoupled from any single persistence backend.

A SearchDefinition declares what a search is allowed to do — which fields are filterable and with which operators, which are sortable, how pagination is bounded. Everything a client sends that the definition did not declare is dropped, so the query string can never reach further into your schema than you explicitly allowed.

Requirements

• PHP >= 8.4
• Symfony 6.4 / 7.x / 8.x
• doctrine/orm ^2.0 || ^3.0 — only if you use the Doctrine adapter (Taranovegor\SearcherBundle\Doctrine\*); the bundle registers it automatically when Doctrine ORM is installed

Install

Quick start

Define what a search is allowed to do:

Bind a controller argument with #[MapSearch] and run the search:

Query string conventions

Filters

Operators: eq, neq, gt, gte, lt, lte, in, notIn, like (like matches the value as a literal substring — %/_ in it are escaped).

A filter for an undeclared field is ignored. A condition using an operator the field was not declared with is ignored (and logged at notice level). A value failing one of the field's constraints rejects the whole request — the HTTP resolver turns that into a 422 response.

Sorting and pagination

A missing or invalid limit falls back to the definition's defaultLimit. Clients can never request an unbounded result set; unbounded queries are a server-side capability (PaginationDetails::unlimited()).

Definition features

Renaming: API field vs. property

Clients use the API name; queries use the property. For the Doctrine adapter the property must be a scalar field of the root entity — filtering through a relation needs a filter handler.

Input transformers

Normalize a client value before validation and execution:

Filter handlers

Custom query logic — joins, computed expressions — for one filter:

The context exposes join(), leftJoin(), andWhere(), addOrderBy(), expr(), setParameter() and uniqueParameterName(). Take bound-parameter names from uniqueParameterName() so handlers cannot collide with each other or with standard filters; alias joins after the field being filtered.

Deduplicating joined to-many filters

When a filter handler joins a to-many relation, the SQL result fans out to one row per match. That inflates the reported total and breaks page windows: LIMIT/OFFSET cut raw SQL rows before Doctrine's hydrator collapses duplicates, so a page can come back short. Opt in to deduplication per definition:

The searcher then applies SELECT DISTINCT and counts COUNT(DISTINCT <identifier>). It is not the default because SELECT DISTINCT requires every ORDER BY expression to be part of the selected columns, which conflicts with handlers ordering by a joined, non-selected expression.

Server-side criteria

Force criteria on top of whatever the client sent, without mutating the DTO:

Extra filters are merged with the client's; server sorting (once set) replaces client sorting entirely; a pagination override replaces the client's pagination.

SearchResult::map() converts entities to response DTOs while keeping the pagination metadata:

Custom request conventions

SearchDtoValueResolver implements the filter[...]/sort/limit convention above. To support a different one (e.g. flat ?status=x&cities[]=1 parameters), extend AbstractSearchDtoResolver and override extractFilterParams(); validation, transformers and handlers are unaffected. Note that string values still go through the operator:value / ; parsing — override scope is where filter values come from, not their syntax.

Development

License

MIT, see LICENSE.