---
title: "Filtre — Query Builder for Laravel | Roundly"
description: "Všetky vstavané konštruktory filtrov — presná zhoda, boolean, čiastočná zhoda, prefix/sufix, scope, callback, trashed a vlastné — plus normalizácia."
url: https://roundly-consulting.com/sk/open-source/navody/query-builder-for-laravel/filtre
language: sk
---

[Všetky balíky](https://roundly-consulting.com/sk/open-source.md)

[Query Builder for Laravel](https://roundly-consulting.com/sk/open-source/navody/query-builder-for-laravel.md)

# Filtre

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

| Konštruktor | Request | Efekt |
| --- | --- | --- |
| `AllowedFilter::exact('status')` | `filter[status]=published` | where('status', 'published'); zoznam oddelený čiarkami sa zmení na whereIn. |
| `AllowedFilter::boolean('active')` | `filter[active]=true` | Presná zhoda na booleovskom stĺpci: true/false/1/0 (v ľubovoľnej veľkosti písmen) sa porovnajú ako skutočné booleany; iná hodnota nenájde nič. |
| `AllowedFilter::partial('title')` | `filter[title]=hello` | Zhoda „obsahuje“ (%hello%) — na PostgreSQL ILIKE, inde LIKE — s escapovanými zástupnými znakmi; veľkosť písmen rieši databázový engine. |
| `AllowedFilter::beginsWith('code')` | `filter[code]=SKU` | Ukotvená zhoda prefixu (SKU%), escapovaná, s rovnakým zohľadnením veľkosti písmen ako partial. |
| `AllowedFilter::endsWith('code')` | `filter[code]=-01` | Ukotvená zhoda sufixu (%-01), escapovaná, s rovnakým zohľadnením veľkosti písmen ako partial. |
| `AllowedFilter::search('search', ['name', 'email'])` | `filter[search]=ann` | Jedno vyhľadávacie pole naprieč viacerými stĺpcami: riadky, v ktorých ktorýkoľvek z nich obsahuje frázu, ako jedno zoskupené OR. Čiarka je súčasťou frázy. Pozrite Vyhľadávanie vo viacerých stĺpcoch. |
| `AllowedFilter::operator('min_views', FilterOperator::GreaterThanOrEqual, 'views')` | `filter[min_views]=10` | Pevné porovnanie na serveri: where('views', '>=', 10). |
| `AllowedFilter::operators('status', [RequestedOperator::Not])` | `filter[status]=not:draft` | Porovnanie vyberá klient z deklarovanej množiny; samotná hodnota stále znamená rovnosť. |
| `AllowedFilter::nullable('project', 'project_id', FilterValueShape::Uuid)` | `filter[project]=none` | Presná zhoda na nullable stĺpci, s none pre „nenastavené“ a not:none pre „nastavené“. |
| `AllowedFilter::relation('label', 'labels', 'labels.id')` | `filter[label]=not:<id>` | Zhoda cez reláciu — whereHas, pri negácii whereDoesntHave. |
| `AllowedFilter::jsonContains('tag', 'tags')` | `filter[tag]=release` | Členstvo v JSON poli; negácia znamená „žiadne z týchto“. |
| `AllowedFilter::scope('published', booleans: true)` | `filter[published]=false` | Zavolá scope modelu scopePublished(); hodnota sa odovzdá ako jeden argument (booleans: true zmení true/false/1/0 na skutočné booleany). |
| `AllowedFilter::scope('between', spread: true)` | `filter[between]=10,100` | Zavolá scope s poľom rozloženým do argumentov (voliteľné). |
| `AllowedFilter::callback('min_views', $cb)` | `filter[min_views]=10` | Zavolá $cb($query, $value, $property); prijme booleans: true rovnako ako scope(). |
| `AllowedFilter::trashed()` | `filter[trashed]=with` | with zahrnie zmazané, only vráti len zmazané, čokoľvek iné predvolené správanie (vyžaduje SoftDeletes). |
| `AllowedFilter::custom('x', $filter)` | `filter[x]=…` | Spustí vašu vlastnú implementáciu Filter; prijme booleans: true rovnako ako scope(). |

## 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:

```php
->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

```php
->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]=@example.com → %@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. Pre jedno vyhľadávacie pole naprieč viacerými stĺpcami, v ktorom je čiarka súčasťou textu, použite search() — pozrite Vyhľadávanie vo viacerých stĺpcoch.

## Veľkosť písmen rieši engine

partial(), beginsWith(), endsWith(), search() 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:

| Engine | Operátor | Veľkosť písmen |
| --- | --- | --- |
| PostgreSQL | `ILIKE` | Podľa ctype locale databázy: pod UTF-8 locale Unicode (ärger nájde Ärger), pod C len ASCII. Diakritika sa stále rozlišuje. |
| MySQL / MariaDB | `LIKE` | Podľa collation stĺpca: predvolené \_ci collation ignorujú veľkosť písmen aj diakritiku (arger nájde Ärger); collation \_bin / \_cs veľkosť písmen rozlišuje. |
| SQLite | `LIKE` | Len písmená ASCII: hello nájde HELLO, ale ärger nenájde Ärger. |

## 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'\]:

```php
// 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:

```php
// 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

```php
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

```php
// 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:

| Request | Hodnota pre filter | Poznámka |
| --- | --- | --- |
| `filter[status]=published` | `'published'` | Jeden reťazec. |
| `filter[status]=published,draft` | `['published', 'draft']` | Zoznam oddelený čiarkami sa zmení na pole. |
| `filter[active]=true` | `'true'` | true/false ostávajú textom — skutočný boolean dostane len filter, ktorý si o to povie (boolean(), FilterValueShape::Boolean, booleans: true). |
| `filter[status][]=a&filter[status][]=b,c` | `['a', 'b', 'c']` | Jedna úroveň vnorenia poľa sa zarovná. |

Prázdna položka nie je hodnota: a,,b aj a,b, sú dve hodnoty, kým filter\[status\]=, filter\[status\]=, a operátor, za ktorým nič nenasleduje (not:, contains:), nenesú žiadnu. Filter, ktorému nezostane žiadna hodnota, nepridá žiadnu podmienku — platí to rovnako pre exact, boolean, partial, beginsWith, endsWith, search, operator, operators, nullable, relation aj jsonContains — takže vymazané vyhľadávacie pole ani zatúlaná čiarka zoznam nevyprázdnia ani neskreslia. scope(), callback() a custom() dostanú hodnotu presne tak, ako prišla.

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.

## Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

[Ďalšie spôsoby podpory vrátane kryptomien](https://roundly-consulting.com/sk/podporte-nas.md)

Odoslaním daru súhlasíte s našimi [podmienkami prijímania darov](https://roundly-consulting.com/sk/podmienky-darov.md).

[Podporte našu open-source prácu (otvorí sa v novej karte)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Pridajte sa k nám na Patreone (otvorí sa v novej karte)](https://www.patreon.com/cw/roundly)

## Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

[Ponuka do 48 hodín](https://roundly-consulting.com/sk/kontakt.md) [Prezrieť všetky balíky](https://roundly-consulting.com/sk/open-source/navody/query-builder-for-laravel.md)