Skill api-filter
Ajoute des filtres aux collections API Platform en utilisant l'approche QueryParameter canonique pour la recherche, le tri et le filtrage par plage.
- Étoiles GitHub
- 29
- Fichiers
- 1
- Dernier commit
- 22 oct. 2026
- Licence
- —
- Outils autorisés
- —
Que fait la skill api-filter ?
Ajoute des filtres aux collections API Platform en utilisant l'approche QueryParameter canonique pour la recherche, le tri et le filtrage par plage.
Résumé généré à partir du SKILL.md de la skill.
À propos du skill api-filter
Ce SKILL permet aux développeurs backend d'implémenter la recherche, le tri et le filtrage par plage pour les collections API Platform. Il offre un moyen de déclarer des filtres via l'approche QueryParameter dans le tableau des paramètres d'une opération, ce qui est la méthode requise pour API Platform 4.4 et les versions ultérieures. Cette approche est explicite par opération et fonctionne avec n'importe quel state provider, ce qui en fait un moyen fiable de gérer les requêtes clients pour des sous-ensembles de données spécifiques.
Les développeurs peuvent l'utiliser pour remplacer les attributs obsolètes au niveau de la classe comme #[ApiFilter] ou des filtres spécifiques tels que SearchFilter, BooleanFilter et OrderFilter. Le SKILL prend en charge Doctrine ORM et MongoDB ODM grâce à un ensemble de filtres à usage unique incluant ExactFilter, PartialSearchFilter, DateFilter et SortFilter. Il gère également des besoins spécialisés comme la recherche par IRI avec IriFilter ou la diffusion d'une valeur unique sur plusieurs champs via FreeTextQueryFilter. Pour les utilisateurs de Laravel, il fournit des conseils sur l'utilisation du jeu de filtres Eloquent spécifique et des règles de validation Laravel.
Ce qu'un agent peut faire avec
- 1Migrer les anciens filtres APIConvertissez les attributs #[ApiFilter] obsolètes au niveau de la classe vers l'approche moderne QueryParameter.
- 2Ajouter une recherche en texte libre multi-champsCréez un paramètre de recherche unique qui vérifie une valeur à travers plusieurs propriétés différentes.
- 3Configurer les filtres Laravel EloquentConfigurez le filtrage pour les modèles Laravel en utilisant les classes de filtres Eloquent et les règles de validation spécifiques.
Rédigé à partir du SKILL.md du skill. Chaque cas d'utilisation est vérifié par rapport à une citation de celui-ci.
Comment installer la skill api-filter
Chaque commande copie le dossier de la skill dans le répertoire des skills du client. Redémarrez le client ou démarrez une nouvelle session pour la charger.Installer la skill api-filter dans Plugin
/plugin marketplace add api-platform/skillset /plugin install api-platform@api-platform-skillset
Installer la skill api-filter dans Claude Code
~/.claude/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter ~/.claude/skills/api-filterInstaller la skill api-filter dans Claude Code (project)
.claude/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter .claude/skills/api-filterInstaller la skill api-filter dans Codex
~/.agents/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter ~/.agents/skills/api-filterInstaller la skill api-filter dans Gemini CLI
~/.gemini/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter ~/.gemini/skills/api-filterInstaller la skill api-filter dans Claude.ai
npx degit api-platform/skillset/skills/api-filter api-filter && zip -r api-filter.zip api-filter # claude.ai → Customize → Skills → + → Create skill → Upload a skill → api-filter.zip
Vérifications automatisées
Exécuté le 16 nov. 2026Rapport complet →Pas encore vérifiée. Une skill doit obtenir 80, sans constat grave, avec assez de données pour être vérifiée. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibleapi-platform/skillset/skills/api-filter is public and reachablegithub.com/api-platform/skillset/tree/HEAD/skills/api-filter ↗Réussi
- Licence open source (OSI)No licenseFaille
- Commit ou version publiée au cours de l'année écouléeLast commit 2026-10-22github.com/api-platform/skillset/commits ↗Réussi
- Aucun téléchargement-exécution ni vol d'identifiants dans les scriptsNo scripts in the skill folderRéussi
- Aucune instruction cachée dans SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/api-platform/skillset/blob/HEAD/skills/api-filter ↗Réussi
- Les outils préautorisés sont limitésNo pre-approved tools; the agent asks before using onegithub.com/api-platform/skillset/blob/HEAD/skills/api-filter ↗Réussi
- SKILL.md respecte le format Agent SkillsValid name and description; says when to use it; 252 linesgithub.com/api-platform/skillset/blob/HEAD/skills/api-filter ↗Réussi
SKILL.md
Voir sur GitHubAdding Filters to Collections
Declare filters with QueryParameter in the operation's parameters: array. The
key is the query-string parameter exposed to clients; the filter: is the filter
instance. This is the canonical approach for API Platform 4.4+ — it works with any
state provider and is per-operation explicit.
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;
use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
#[GetCollection(
parameters: [
'status' => new QueryParameter(filter: new ExactFilter()),
],
)]
class Order {}
Client: GET /orders?status=shipped
#[ApiFilter]is legacy. The class-level#[ApiFilter(SearchFilter::class, ...)]attribute and the multi-strategy filters (SearchFilter,BooleanFilter,NumericFilter,OrderFilter,BackedEnumFilter) are deprecated in 4.4 and removed in 6.0. Don't teach or add them in new code. If you encounter them, the migration target is theQueryParameter+ single-purpose filter set below. The mapping is in the table at the bottom.
Canonical filter set
Each filter does one thing. They live in two parallel namespaces — pick the one matching your persistence layer:
| Filter | Purpose | ORM | MongoDB ODM |
|---|---|---|---|
ExactFilter |
equality, multi-value (IN); booleans/ints/enums via nativeType |
ApiPlatform\Doctrine\Orm\Filter\ExactFilter |
ApiPlatform\Doctrine\Odm\Filter\ExactFilter |
PartialSearchFilter |
LIKE %x% substring |
…\Orm\Filter\PartialSearchFilter |
…\Odm\Filter\PartialSearchFilter |
ComparisonFilter |
gt/gte/lt/lte/ne (decorates an equality filter) |
…\Orm\Filter\ComparisonFilter |
…\Odm\Filter\ComparisonFilter |
SortFilter |
ORDER BY |
…\Orm\Filter\SortFilter |
…\Odm\Filter\SortFilter |
DateFilter |
before/after date ranges |
…\Orm\Filter\DateFilter |
…\Odm\Filter\DateFilter |
RangeFilter |
between/gt/lt on numbers |
…\Orm\Filter\RangeFilter |
…\Odm\Filter\RangeFilter |
ExistsFilter |
IS NULL / IS NOT NULL |
…\Orm\Filter\ExistsFilter |
…\Odm\Filter\ExistsFilter |
IriFilter |
relationship lookup by IRI | …\Orm\Filter\IriFilter |
…\Odm\Filter\IriFilter |
OrFilter |
decorator: switches a primary's WHERE to orWhere |
…\Orm\Filter\OrFilter |
…\Odm\Filter\OrFilter |
FreeTextQueryFilter |
decorator: broadcasts one value across N properties | …\Orm\Filter\FreeTextQueryFilter |
…\Odm\Filter\FreeTextQueryFilter |
ComparisonFilterandOrFilterare still marked@experimentalin 4.4 — they are the intended migration target but their API may shift before stabilizing.
Common filters
Exact match
'status' => new QueryParameter(filter: new ExactFilter())
GET /orders?status=shipped. Arrays produce an IN: ?status[]=draft&status[]=sent.
Boolean / integer / enum — ExactFilter + nativeType
There is no BooleanFilter in the canonical set. Use ExactFilter and declare the
native type so values are cast and documented correctly:
use Symfony\Component\TypeInfo\Type\BuiltinType;
use Symfony\Component\TypeInfo\TypeIdentifier;
'active' => new QueryParameter(
filter: new ExactFilter(),
nativeType: new BuiltinType(TypeIdentifier::BOOL),
),
GET /orders?active=true. Use TypeIdentifier::INT for integers; pass an enum's
native type for backed enums.
Partial search (LIKE)
use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
'q' => new QueryParameter(filter: new PartialSearchFilter(), property: 'title')
GET /books?q=harry. property: maps the public param name to the entity field.
Comparison (gt/gte/lt/lte/ne)
use ApiPlatform\Doctrine\Orm\Filter\ComparisonFilter;
'price' => new QueryParameter(filter: new ComparisonFilter(new ExactFilter()))
GET /products?price[gt]=100&price[lte]=500.
Date range
use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
'createdAt' => new QueryParameter(filter: new DateFilter())
GET /orders?createdAt[after]=2024-01-01&createdAt[before]=2024-12-31.
Numeric range
use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
'price' => new QueryParameter(filter: new RangeFilter())
GET /products?price[between]=10..100.
Exists (null check)
use ApiPlatform\Doctrine\Orm\Filter\ExistsFilter;
'deletedAt' => new QueryParameter(filter: new ExistsFilter())
GET /orders?deletedAt[exists]=false.
Relation (IRI)
use ApiPlatform\Doctrine\Orm\Filter\IriFilter;
'author' => new QueryParameter(filter: new IriFilter())
GET /books?author=/authors/1.
Sorting — SortFilter
There is no OrderFilter in the canonical set. Use SortFilter. Two forms:
use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
// Per-property named parameter
'orderName' => new QueryParameter(filter: new SortFilter(), property: 'name'),
// → GET /books?orderName=desc
// Dynamic, OrderFilter-style: one parameter, any allowed property
'order[:property]' => new QueryParameter(filter: new SortFilter()),
// → GET /books?order[name]=asc&order[createdAt]=desc
property: can traverse relations ('department.company.name' sorts across joins).
Control null placement with nullsComparison:
use ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface;
'orderHireDate' => new QueryParameter(
filter: new SortFilter(nullsComparison: OrderFilterInterface::NULLS_ALWAYS_FIRST),
property: 'hireDate',
),
Free-text across multiple fields
FreeTextQueryFilter decorates a primary and broadcasts one value to several
properties; wrap with OrFilter to match any of them:
use ApiPlatform\Doctrine\Orm\Filter\FreeTextQueryFilter;
use ApiPlatform\Doctrine\Orm\Filter\OrFilter;
use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
'autocomplete' => new QueryParameter(
filter: new FreeTextQueryFilter(new OrFilter(new ExactFilter())),
properties: ['name', 'email', 'description'],
),
GET /users?autocomplete=alice.
Validating filter parameters
use Symfony\Component\Validator\Constraints as Assert;
'length' => new QueryParameter(
filter: new ExactFilter(),
constraints: [new Assert\Length(max: 100)],
)
Invalid values yield a 422 before the query runs.
Default ordering
Set a default sort directly on the operation (no parameter needed):
new GetCollection(order: ['createdAt' => 'DESC'])
Legacy → canonical migration map
| Legacy (deprecated 4.4, removed 6.0) | Canonical replacement |
|---|---|
#[ApiFilter(SearchFilter::class, ['x' => 'exact'])] |
'x' => new QueryParameter(filter: new ExactFilter()) |
SearchFilter strategy partial |
PartialSearchFilter |
BooleanFilter |
ExactFilter + nativeType: BOOL |
NumericFilter |
ExactFilter + nativeType: INT |
BackedEnumFilter |
ExactFilter + enum nativeType |
OrderFilter |
SortFilter |
RangeFilter, DateFilter, ExistsFilter |
same class — survives as drop-in, just move to QueryParameter |
Laravel (Eloquent)
The QueryParameter wiring is identical, but Laravel ships its own Eloquent
filter set under ApiPlatform\Laravel\Eloquent\Filter\ — these are not the Doctrine
classes and the names differ. Declare them with class-level #[QueryParameter] /
#[GetCollection(parameters: …)] on the model (or DTO). The key, property,
properties, :property placeholder and constraints options work the same.
| Need | Doctrine (above) | Laravel Eloquent class |
|---|---|---|
| equality | ExactFilter |
EqualsFilter |
LIKE %x% |
PartialSearchFilter |
PartialSearchFilter |
LIKE x% / %x |
StartSearchFilter / EndSearchFilter |
StartSearchFilter / EndSearchFilter |
| boolean | ExactFilter + nativeType |
BooleanFilter |
| date range | DateFilter |
DateFilter (filterContext: ['include_nulls' => true] to keep nulls; default excludes) |
| numeric range | RangeFilter |
RangeFilter |
| sort | SortFilter |
OrderFilter |
| OR | OrFilter |
OrFilter (decorator: new OrFilter(new EqualsFilter())) |
use ApiPlatform\Laravel\Eloquent\Filter\EqualsFilter;
use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\QueryParameter;
#[ApiResource]
#[QueryParameter(key: 'name', filter: EqualsFilter::class)]
#[QueryParameter(key: 'sort[:property]', filter: OrderFilter::class, properties: ['name', 'id'])]
class Book extends Model {}
Constraints are Laravel validation rules (a string/array), not Symfony
constraints: new QueryParameter(key: 'name', filter: PartialSearchFilter::class, constraints: 'min:2').
Custom filters implement ApiPlatform\Laravel\Eloquent\Filter\FilterInterface
(apply(Builder $builder, mixed $values, Parameter $parameter, array $context = []): Builder);
scaffold with php artisan make:filter. There is no ExistsFilter, ComparisonFilter,
IriFilter or FreeTextQueryFilter in the Eloquent set — nativeType on a parameter
is also unused (use BooleanFilter for booleans). #[ApiFilter] is not the Laravel
idiom; models declare #[QueryParameter] directly.
Fichiers de cette skill
1Questions sur la skill api-filter
Comment installer la skill api-filter dans Claude Code ?
Exécutez npx degit api-platform/skillset/skills/api-filter ~/.claude/skills/api-filter. Claude Code charge les skills depuis ~/.claude/skills (tous les projets) ou .claude/skills (un seul projet) et utilise une skill lorsque sa description correspond à la tâche.
Quels clients peuvent utiliser la skill api-filter ?
Tout client qui lit le format Agent Skills : Claude Code, Codex, Gemini CLI et claude.ai (envoi sous forme de ZIP). Les scripts de la skill ne s'exécutent que si le client autorise l'exécution de code.
Comment remplacer l'attribut obsolète #[ApiFilter] ?
Vous devez migrer vers l'approche QueryParameter dans le tableau des paramètres de l'opération, en mappant les anciens filtres vers leurs remplaçants canoniques dédiés à un usage unique.
Comment implémenter un filtrage booléen ou entier avec la nouvelle méthode canonique ?
Au lieu d'utiliser un BooleanFilter dédié, utilisez l'ExactFilter et déclarez le type natif via le TypeInfo de Symfony pour garantir un cast correct.
Ce SKILL prend-il en charge Laravel Eloquent ?
Oui, mais vous devez utiliser les classes de filtrage Eloquent spécifiques fournies par ApiPlatformLaravelEloquent au lieu des classes Doctrine.