6 - Des filtres sur les API

Parameters and Filtersapi-platform.com

Comme toujours la documentation officielle est le meilleur cours disponible.

Pour comprendre comment fonctionne les filtres, il faut savoir comment ApiPlatform fonctionne en interne. Vulgairement, pour les Api classiques branchées sur une entity, le workflow de lecture est le suivant:

• Identifie l'entity cible

• Crée un QueryBuilder (doctrine) pour aller chercher les données en base

• (si extensions): applique l'extension sur le QueryBuilder pour limiter les résultats (on y reviendra plus tard)

• (si filtres): applique les filtres sur le QueryBuilder pour limiter les résultats

• Applique automatiquement la pagination

• Serialize

• Retourne les données

Toute l'idée de nos filtres ici vont être de surcharger eux aussi le QueryBuilder pour avoir les bons résultats.

Filtre pré-existants

Pour commencer simplement, on va utiliser les filtres déjà créés par ApiPlatform.

Prenons notre Entity Category qui ressemble actuellement à:

// ......

#[ORM\Entity]
#[ORM\Table(name: TableEnum::TABLE_CATEGORY)]
#[ApiResource]
class Category
{
    use UuidTrait;
    use CreatedAtTrait;
    use UpdatedAtTrait;

    #[ORM\Column(length: 255)]
    public ?string $name = null;
    
// ......
}

Comme pour dire que c'est une resource de notre API, on va utiliser les attributs PHP pour rajouter des filtres:

// ......

+ use ApiPlatform\Doctrine\Common\Filter\SearchFilterInterface;
+ use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+ use ApiPlatform\Metadata\ApiFilter;

#[ORM\Entity]
#[ORM\Table(name: TableEnum::TABLE_CATEGORY)]
#[ApiResource]
+ #[ApiFilter(SearchFilter::class, properties: ['name' => SearchFilterInterface::STRATEGY_PARTIAL])]
class Category
{
    use UuidTrait;
    use CreatedAtTrait;
    use UpdatedAtTrait;

    #[ORM\Column(length: 255)]
    public ?string $name = null;
    
// ......
}

Dans cet exemple, on peut voir que j'ai rajouter un filtre de type "recherche". Je l'ai rendu disponible sur la propriété name en monde recherche partielle.

Si je vais voir dans ma doc swagger (/api/docs), mon filtre sera bien présent.

De plus je peux tester directement mon filtre ici, et on voit bien que seul ma catégorie contenant 53 ressort.

Evidemment il existe plein d'autres type de filtres disponible par défaut, comme:

• DateFilter: Pour filter sur les dates

• BooleanFilter::class: Pour filter les booleans

• NumericFilter : pour filter les chiffres

• ....

• ....

Bref, pleins de filtres par défaut très pratiques.

Créer un filtre Doctrine custom

Parfois, les filtres classiques ne suffisent pas, par exemple les Uuids ne sont pas supportés, ce qui va être problématique pour filtrer nos tickets par catégories par exemple.

Voici la base de tous filtres custom Doctrine:

<?php declare(strict_types=1);

namespace App\Doctrine\Orm\Filter;

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

final class DoctrineCustomFilter extends AbstractFilter
{

    protected function filterProperty(string $property, mixed $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
    {
        // TODO: Implement filterProperty() method.
    }

    public function getDescription(string $resourceClass): array
    {
        // TODO: Implement getDescription() method.
    }
}

1. On étend de AbstractFilter qui est la base prévu par l'équipe d'ApiPlatform pour nous faciliter la création de filtres

2. filterProperty: c'est la partie qui nous permet de "jouer" avec le QueryBuilder Doctrine utilisé par ApiPlatform. C'est ce dernier que nous allons modifié pour filtrer la réponse finale

3. getDescription: Ici c'est la partie documentation, utile pour avoir un joli swagger bien à jour et aidé les personnes qui se servent de votre API.

Voir aussi: Filtres customs ApiPlatform - Exemple avec un UuidFilter