name	api-platform:make-filter
description	Génère des filtres API Platform (search, date, range, order, boolean, exists, custom)
argument-hint	<nom-resource>
model	sonnet
allowed-tools	["AskUserQuestion","Bash","Read","Write","Edit","Grep","Glob"]
version	1.0.0
license	MIT

API Platform Make Filter

Génère des filtres pour une resource API Platform : filtres Doctrine intégrés (SearchFilter, DateFilter, RangeFilter, etc.) ou filtres personnalisés.

Variables

{ResourceName} - Nom de la resource en PascalCase
{properties} - Propriétés à filtrer
{filterType} - Type de filtre (search, date, range, order, boolean, exists, custom)

Outputs

Modification de src/Entity/{ResourceName}.php (ajout des attributs de filtre)
src/Filter/{FilterName}Filter.php (si filtre custom)

Instructions à Exécuter

IMPORTANT : Exécute ce workflow étape par étape :

1. Identifier la resource cible

Si $ARGUMENTS est fourni, utiliser comme nom de la resource

Sinon, utiliser AskUserQuestion :

Question: "Sur quelle resource ajouter des filtres ?"
Header: "Resource"

Vérifier que le fichier src/Entity/{ResourceName}.php existe avec Glob
Lire le fichier avec Read pour comprendre les propriétés disponibles

2. Analyser les propriétés de la resource

Parser les propriétés de la classe (nom, type PHP, type Doctrine)
Identifier les propriétés candidates pour chaque type de filtre :
- string → SearchFilter (partial, exact, start, end, word_start)
- \DateTimeInterface → DateFilter (before, after, strictly_before, strictly_after)
- int, float → RangeFilter (between, gt, gte, lt, lte)
- bool → BooleanFilter
- nullable → ExistsFilter
- relations → SearchFilter sur les propriétés liées

3. Choisir les filtres à ajouter

Utiliser AskUserQuestion (multiSelect: true) :

Question: "Quels types de filtres ajouter ?"
Header: "Filtres"
Options:
  - "SearchFilter" : "Recherche textuelle (partial, exact, start, end, word_start)"
  - "OrderFilter" : "Tri sur les propriétés (ASC/DESC)"
  - "DateFilter / RangeFilter / BooleanFilter / ExistsFilter" : "Filtres typés selon les propriétés"
  - "Filtre personnalisé" : "Classe de filtre custom avec logique métier"

4. Configurer chaque filtre

Pour SearchFilter :

Demander la stratégie pour chaque propriété string :
- partial — Recherche contenant (LIKE %value%)
- exact — Correspondance exacte
- start — Commence par (LIKE value%)
- end — Finit par (LIKE %value)
- word_start — Mot commençant par
- ipartial — Recherche partielle insensible à la casse

Pour OrderFilter :

Lister les propriétés triables
Définir l'ordre par défaut (ASC/DESC)

Pour DateFilter :

Appliquer automatiquement sur les propriétés DateTime

Pour RangeFilter :

Appliquer automatiquement sur les propriétés numériques

5. Générer les attributs de filtre

Ajouter les attributs sur la classe de la resource :

use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
use ApiPlatform\Doctrine\Orm\Filter\ExistsFilter;
use ApiPlatform\Metadata\ApiFilter;

#[ApiFilter(SearchFilter::class, properties: [
    'name' => 'partial',
    'email' => 'exact',
])]
#[ApiFilter(OrderFilter::class, properties: ['id', 'name', 'createdAt'])]
#[ApiFilter(DateFilter::class, properties: ['createdAt', 'updatedAt'])]
#[ApiFilter(RangeFilter::class, properties: ['price', 'quantity'])]
#[ApiFilter(BooleanFilter::class, properties: ['active'])]
#[ApiFilter(ExistsFilter::class, properties: ['deletedAt'])]

6. Générer un filtre personnalisé (si demandé)

Créer src/Filter/{FilterName}Filter.php :

<?php

declare(strict_types=1);

namespace {namespace}\Filter;

use ApiPlatform\Doctrine\Orm\Filter\AbstractFilter;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use Doctrine\ORM\QueryBuilder;

final class {FilterName}Filter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        mixed $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = [],
    ): void {
        if ('customProperty' !== $property) {
            return;
        }

        $parameterName = $queryNameGenerator->generateParameterName($property);
        $queryBuilder
            ->andWhere(sprintf('o.%s = :%s', $property, $parameterName))
            ->setParameter($parameterName, $value);
    }

    public function getDescription(string $resourceClass): array
    {
        return [
            'customProperty' => [
                'property' => 'customProperty',
                'type' => 'string',
                'required' => false,
                'description' => 'Description du filtre personnalisé',
                'openapi' => [
                    'description' => 'Description pour OpenAPI',
                ],
            ],
        ];
    }
}

7. Afficher le résumé

Filtres ajoutés à {ResourceName}

Filtres configurés :
- SearchFilter : name (partial), email (exact)
- OrderFilter : id, name, createdAt
- DateFilter : createdAt, updatedAt

Exemples de requêtes :
- GET /api/{resources}?name=foo         (recherche partielle)
- GET /api/{resources}?order[name]=asc  (tri)
- GET /api/{resources}?createdAt[after]=2024-01-01 (date)

Documentation automatique :
- Les filtres apparaissent dans OpenAPI/Swagger
- Les filtres sont documentés dans les réponses Hydra

Prochaines étapes :
- Tester les filtres : /api-platform:make-test {ResourceName}
- Ajouter des filtres personnalisés : /api-platform:make-filter {ResourceName}

Filtres disponibles

Filtres Doctrine ORM intégrés

Filtre	Usage	Paramètres
SearchFilter	Recherche textuelle	exact, partial, start, end, word_start, ipartial
OrderFilter	Tri	ASC, DESC
DateFilter	Dates	before, after, strictly_before, strictly_after
RangeFilter	Intervalles numériques	between, gt, gte, lt, lte
BooleanFilter	Booléens	true, false, 1, 0
ExistsFilter	Nullabilité	true, false
NumericFilter	Valeurs numériques exactes	valeur exacte

QueryParameter (API Platform 3.3+)

Alternative moderne aux filtres via #[QueryParameter]
Plus flexible, supporte les expressions de sécurité
Utilisable avec ou sans Doctrine

Notes

Les filtres Doctrine ne fonctionnent qu'avec le state provider Doctrine
Pour les DTOs avec providers personnalisés, implémenter le filtrage dans le provider
Penser à indexer les colonnes filtrées en base de données
Les filtres sont automatiquement documentés dans OpenAPI