Search builder

Aneb metoda pro nastavení vyhledávače a filtrů v kolekcích.

Pomocí search builderu můžete definovat způsob, jakým se mají vyhledávat či filtrovat záznamy v kolekci a datagridu. V kterémkoli vašem recipe lze použít metodu search, která tato nastavení umožňuje upravit.

Výchozí konfigurace

Výchozí konfiguraci udává rodičovská třída CollectionRecipe a její konfigurace je totožná s tímto kódem:

app/Recipe/UserRecipe.php

class UserRecipe extends CollectionRecipe
{
    // Nastavení vyhledávače
    public function search(SearchBuilder $builder, CollectionRequest $request): SearchBuilder
    {    
        return $builder->keepDefaults();
    }
}

Parametry metody

Parametr	Popis
SearchBuilder	Objekt, díky kterému lze definovat vyhledávač a filtry (podrobnosti v odstavci SearchBuilder).
CollectionRequest	Objekt, který obsahuje veškeré informace o aktuálním requestu prováděným nad kolekcí. Dostupné metody: $request->getHttpRequest() $request->isFormRendering() $request->getRequestData() $request->getSearchText() $request->getCustomData() $request->getRowId() $request->getRowValues()

SearchBuilder

Search builder obsahuje množství metod. V zásadě ale budete používat jen několik z nich:

Metoda	Popis metody	Parametr	Popis parametru
addSearchable(...)	Přidá sloupec do vyhledávače.	Searchable $searchable	Konkrétní sloupec k přidání.
keepInitials()	Ponechá výchozí sloupce ve vyhledávači. ['id', 'createdAt', 'updatedAt']
getQueryBuilder()	Vrátí QueryBuilder, který je možné upravit dle potřeby.
addSearchablesToSchema(...)	Přidá názvy sloupců do placeholderu ve vyhledávači. Hodí se zejména při použití QueryBuilderu.	string[] $columnNames

Podrobná konfigurace

V následujícím příkladu si ukážeme, jak lze upravit vyhledávač tak, aby bylo možné vyhledávat záznamy podle emailu a podle názvu role z joinované tabulky role. Pro demonstraci možností je použit i formátovací callback a operátor LIKE, tento callback a operátor je však možné vynechat - toto nastavení je totiž výchozí.

app/Recipe/UserRecipe.php

public function search(SearchBuilder $builder, CollectionRequest $request): SearchBuilder
{
    return $builder
        ->keepDefaults()
        
        // Umožní vyhledávat podle emailu
        ->addSearchable(new Searchable(
            column: 'email',
            operator: 'LIKE',
            formatter: fn($value) => "%{$value}%"
        ))
        
        // Umožní vyhledávat podle názvu role z joinované tabulky
        ->addSearchable(new Searchable(
            relation: 'roles' // Název property v entitě User (aktuální entita)
            column: 'name', // Název property v entitě Roles (joinovaná entita)
        ))
    ;
}

Popis třídy Searchable

Tato třída slouží k definici sloupce, který má být vyhledáván. Má následující parametry:

Parametr	Popis	Typ	Výchozí hodnota
column	Název sloupce, ve kterém se bude vyhledávat.	string
operator	SQL operátor, který se použije pro vyhledávání př: LIKE.	string	'LIKE'
formatter	Callback, který se použije pro formátování hodnoty před vyhledáváním.	callable	null
relation	Název property v aktuální entitě skrze kterou je možné provést join.	string	null

Využití QueryBuilderu

Pokud bude potřeba rozšířit vyhledávání či filtrování záznamů o složitější podmínky, je možné využít QueryBuilder. V následujícím příkladu demonstrován naprosto totožný příklad jako výše, ale bez použití Searchable.

app/Recipe/UserRecipe.php

public function search(SearchBuilder $builder, CollectionRequest $request): SearchBuilder
{
    $builder
        ->keepDefaults()
        
        ->getQueryBuilder()
        ->leftJoin('entity.roles', 'role')
        ->orWhere('entity.email LIKE :searchText OR role.name LIKE :searchText')
        ->setParameter('searchText', "%{$request->getSearchText()}%");
    
    // Zaregistruje sloupce do placeholderu pro vyhledávání
    return $builder->addSearchablesToSchema(['email', 'role.name']);
}