Filtre

Filtre deklarujete konštruktormi AllowedFilter. Každý číta jeden parameter filter[<name>]; úplný prehľad:

Verejné názvy verzus stĺpce

Každý konštruktor prijme voliteľný interný názov, takže verejný kľúč v requeste môže smerovať na iný stĺpec či scope — vaša schéma sa nedostane do URL a môže sa meniť bez dopadu na klientov:

->allowedFilters(
    AllowedFilter::exact('state', 'status'),     // filter[state]=…  → where('status', …)
    AllowedFilter::partial('q', 'title'),        // filter[q]=…      → title LIKE %…%
    AllowedFilter::scope('live', 'published'),   // filter[live]=…   → published(…)
)

Presná zhoda a textové vyhľadávanie

->allowedFilters(
    'status',                               // shorthand for AllowedFilter::exact('status')
    AllowedFilter::partial('title'),        // filter[title]=hello        → %hello%
    AllowedFilter::beginsWith('sku'),       // filter[sku]=AB             → AB%
    AllowedFilter::endsWith('email'),       // filter[email][email protected] → %@example.com
)

// ?filter[status]=published,draft → whereIn('status', ['published', 'draft'])
// ?filter[title]=a,b              → title LIKE %a% OR title LIKE %b%

exact() porovnáva cez = a zoznam oddelený čiarkami zmení na whereIn. partial(), beginsWith() a endsWith() používajú na PostgreSQL ILIKE, inde LIKE. Znaky % a _ zadané používateľom sa na SQLite, MySQL aj PostgreSQL escapujú a porovnávajú s explicitnou klauzulou ESCAPE, takže hodnota zhodu nikdy nerozšíri. Zoznam oddelený čiarkami sa zmení na zoskupené OR.

Veľkosť písmen rieši engine

partial(), beginsWith(), endsWith() a operátory contains / ncontains / starts ignorujú veľkosť písmen tak, ako to robí databáza — a tri enginy sa mimo čistého ASCII líšia:

Scopy

scope() zavolá scope modelu pomenovaný podľa filtra (v camelCase, takže views_between zavolá viewsBetween). Predvolene sa normalizovaná hodnota odovzdá ako jeden argument — filter[published]=a,b zavolá scope s ['a', 'b']:

// App\Models\Post
public function scopePublished(Builder $query, bool $published): void
{
    $query->where('status', $published ? 'published' : 'draft');
}

public function scopeViewsBetween(Builder $query, int $min, int $max): void
{
    $query->whereBetween('views', [$min, $max]);
}

// Controller
->allowedFilters(
    AllowedFilter::scope('published', booleans: true),   // filter[published]=false      → published(false)
    AllowedFilter::scope('views_between', spread: true), // filter[views_between]=10,100 → viewsBetween(10, 100)
)

Rozloženie do argumentov (spread) je voliteľné. Jediný argument bráni tomu, aby request určoval, koľko argumentov scope dostane — inak by mohol podstrčiť voliteľný parameter scopu, napríklad scopeSearch($q, $term, $column = 'title'). spread: true zapnite len pre vlastný scope, ktorého argumenty zodpovedajú hodnote oddelenej čiarkami alebo poľu.

Booleovské hodnoty

true a false ostávajú textom — hľadanie „false“ v názve je hľadanie — pokiaľ filter nepovie, že jeho hodnota je boolean: AllowedFilter::boolean(), FilterValueShape::Boolean alebo booleans: true pri scope(), callback() či custom(). Tie zmenia každé true/false/1/0 (v ľubovoľnej veľkosti písmen) na skutočný boolean a ostatné hodnoty nechajú bez zmeny. Bez toho scope dostane reťazec a PHP považuje 'false' za pravdivú hodnotu:

// Post::scopePublished(Builder $query, bool $published)
->allowedFilters(
    AllowedFilter::boolean('active'),                        // filter[active]=false
    AllowedFilter::scope('published', booleans: true),       // filter[published]=false → false
)

// ?filter[active]=TRUE        → active = true
// ?filter[active]=0           → active = false
// ?filter[active]=true,false  → either
// ?filter[active]=maybe       → matches nothing (no driver error)

boolean() je skratka pre operators() bez operátorov a s FilterValueShape::Boolean — ak chcete ponúknuť aj not:, použite priamo ten (pozri Tvary hodnôt). Hodnota, ktorá nie je zápisom booleanu, nenájde nič namiesto toho, aby sa dostala k driveru, kde by PostgreSQL odpovedal chybou.

Callbacky

use Illuminate\Database\Eloquent\Builder;

->allowedFilters(
    AllowedFilter::callback('min_views', function (Builder $query, mixed $value, string $property): void {
        $query->where('views', '>=', $value);
    }),
)

Callback dostane dopyt, normalizovanú hodnotu a interný názov. Na jednoduché porovnanie radšej použite AllowedFilter::operator() namiesto ručne písaného callbacku (pozri Operátorové filtre).

Soft delete

// Post uses Illuminate\Database\Eloquent\SoftDeletes
->allowedFilters(AllowedFilter::trashed())

// ?filter[trashed]=with  → include soft-deleted rows
// ?filter[trashed]=only  → only soft-deleted rows
// any other value        → the default: non-trashed rows only

trashed() vyžaduje model so SoftDeletes. Režim only rešpektuje aj vlastný stĺpec pre soft delete. Filter sa predvolene volá trashed; iný názov odovzdajte ako prvý argument.

Normalizácia hodnôt

Hodnoty sa normalizujú raz, ešte pred spustením filtra — zoznam oddelený čiarkami sa zmení na pole a jedna úroveň vnorenia sa zarovná; samotné hodnoty ostávajú reťazcami:

Limity requestu ohraničujú prácu: najviac limits.max_filter_values položiek na hodnotu (predvolene 50) a limits.max_value_length znakov na položku (predvolene 255) — prebytok sa zahodí alebo oreže.