Operátorové filtre

Porovnania pokrývajú dva konštruktory. operator() určí porovnanie v kóde; operators() nechá klienta vybrať z množiny, ktorú deklarujete.

Pevné porovnania — operator()

operator() vyberie porovnanie na strane servera z enumu FilterOperator. Formát ostáva filter[<name>]=<value> — operátor sa z requestu nikdy nečíta. Použite ho namiesto ručne písaného porovnávacieho callbacku:

use RoundlyConsulting\QueryBuilder\AllowedFilter;
use RoundlyConsulting\QueryBuilder\Enums\FilterOperator;

->allowedFilters(
    AllowedFilter::operator('min_views', FilterOperator::GreaterThanOrEqual, 'views'),
    AllowedFilter::operator('max_price', FilterOperator::LessThan, 'price'),
)

// ?filter[min_views]=10    → where('views', '>=', 10)
// ?filter[min_views]=10,20 → views >= 10 OR views >= 20

Zoznam oddelený čiarkami sa zmení na zoskupené OR toho istého porovnania. Pre =, > a < je to správne, no zoskupené OR s != vyhovie takmer každému riadku — pre viachodnotové „ani jedno“ použite operators() s not, ktorý hodnoty spája cez AND.

Operátory volené klientom — operators()

operators() je jediný konštruktor, pri ktorom request ovplyvní, ktoré porovnanie sa vykoná — a stále ide o rozhodnutie allow-listu v kóde. Request dodá token pred dvojbodkou (filter[status]=not:draft); samotná hodnota naďalej znamená predvolené správanie filtra, takže existujúce URL fungujú ďalej:

use RoundlyConsulting\QueryBuilder\Enums\RequestedOperator;

->allowedFilters(
    AllowedFilter::operators('status', [RequestedOperator::Not]),
    AllowedFilter::operators('title', [RequestedOperator::NotContains], partialByDefault: true),
    AllowedFilter::operators('views', [RequestedOperator::GreaterThan, RequestedOperator::LessThanOrEqual]),
)

// ?filter[status]=draft              → status = 'draft'
// ?filter[status]=not:draft,archived → status NOT IN ('draft', 'archived'), or status IS NULL
// ?filter[title]=laravel             → title contains "laravel" (partialByDefault)
// ?filter[title]=ncontains:draft     → title does not contain "draft", or title IS NULL
// ?filter[views]=gt:20               → views > 20
// ?filter[views]=lte:10              → views <= 10
// ?filter[status]=1=1 or 1:draft     → the literal text — matches nothing

Signatúra: operators(string $name, array $operators, ?string $internalName = null, bool $partialByDefault = false, FilterValueShape $shape = FilterValueShape::Text). Tokeny:

Pravidlá

• Neznámy token alebo token, ktorý filter nedeklaroval, nie je operátor — celý reťazec sa stane hodnotou. filter[status]=1=1 or 1:draft hľadá presne tento text a nenájde nič.
• Vlastné predvolené správanie filtra — is, alebo contains pri partialByDefault — sa dá vždy pomenovať, takže klient sa môže vrátiť späť. Nič iné nie je implicitné: v poli s partialByDefault hľadá is:done presne tento text.
• Počíta sa len známy token pred prvou dvojbodkou, takže filter[url]=https://example.test stále hľadá samotnú URL.
• Operátor patrí filtru, nie hodnote: načíta sa z prvej položky a platí pre všetky. not:draft,archived znamená ani jedno.
• Obe negácie (not, ncontains) zahŕňajú aj riadky, kde je stĺpec NULL — „nie koncept“ zjavne zahŕňa aj „bez stavu“.
• true a false sú text ako každá iná hodnota. Na booleovskom stĺpci deklarujte shape: FilterValueShape::Boolean a not:true / not:false budú fungovať ako negácie skutočných booleanov (pozri Tvary hodnôt).