Ein eigener Filter

Die eingebauten Filter decken die MEISTEN Fälle ab – für eine Volltextsuche über MEHRERE Felder mit EINEM einzigen Parameter braucht es einen EIGENEN Filter.

Wann ein eigener Filter nötig ist

EIN Parameter soll GLEICHZEITIG mehrere Felder durchsuchen (z. B. ?q=relaunch sucht in name UND description).
Die Filterlogik hängt von MEHR ab als einem einfachen Datenbank-Vergleich (z. B. eine Ähnlichkeitssuche).
Berechnete/virtuelle Felder aus Kapitel 25 sollen ebenfalls filterbar sein (die eingebauten Filter arbeiten NUR auf echten Datenbankspalten).

Die Filter-Klasse anlegen

api/src/Filter/MultiFieldSearchFilter.php

<?php

declare(strict_types=1);

namespace App\Filter;

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

final class MultiFieldSearchFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        mixed $value,
        QueryBuilder $queryBuilder,
        \ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = [],
    ): void {
        if ('q' !== $property || !\is_string($value)) {
            return;
        }

        $alias = $queryBuilder->getRootAliases()[0];
        $parameter = $queryNameGenerator->generateParameterName('q');

        $queryBuilder
            ->andWhere("{$alias}.name LIKE :{$parameter} OR {$alias}.description LIKE :{$parameter}")
            ->setParameter($parameter, '%' . $value . '%');
    }

    public function getDescription(string $resourceClass): array
    {
        return [
            'q' => [
                'property' => null,
                'type' => 'string',
                'required' => false,
                'description' => 'Durchsucht name UND description gleichzeitig.',
            ],
        ];
    }
}

filterProperty() wird für JEDEN Query-Parameter aufgerufen, der zur Resource passt – die Prüfung 'q' !== $property stellt sicher, dass der Filter NUR auf den EIGENEN Parameter q reagiert. getDescription() liefert die Metadaten für Swagger UI, GENAU wie bei den eingebauten Filtern.

Den Filter registrieren

use App\Filter\MultiFieldSearchFilter;

#[ApiFilter(MultiFieldSearchFilter::class)]

KEIN properties-Array nötig – der Filter definiert seinen EIGENEN Parameternamen SELBST über getDescription().

Den eigenen Filter testen

curl -k 'https://localhost/api/projects?q=redesign'

Findet Projekte, bei denen "redesign" ENTWEDER im Namen ODER in der Beschreibung vorkommt – EIN Parameter statt zwei separater SearchFilter-Anfragen.

Tipp: Das AbstractFilter-Grundgerüst ist BEWUSST ähnlich zu einem QueryBuilder aus der Symfony-Schulung (Kapitel 21) aufgebaut – WER dort bereits eigene Repository-Methoden mit QueryBuilder geschrieben hat, findet sich hier SOFORT zurecht.