Nullable, relačné a JSON filtre

Tri konštruktory odpovedajú na otázky, ktoré samotná hodnota nevyjadrí: „nemá hodnotu“, „súvisí s“ a „má tento tag“. Každý podporuje is a negáciu not.

Nullable stĺpce — nullable()

Nullable stĺpec potrebuje nullable(), nie operators(). „Riadky bez projektu“ a „riadky s projektom“ sa samotnou hodnotou vyjadriť nedajú — prázdne filter[project]= sa nelíši od chýbajúceho filtra — preto nullable() rezervuje sentinel (predvolene none) a číta aj jeho negáciu:

use RoundlyConsulting\QueryBuilder\Enums\FilterValueShape;

->allowedFilters(
    AllowedFilter::nullable('project', 'project_id', FilterValueShape::Uuid),
)

// ?filter[project]=none            → project_id IS NULL
// ?filter[project]=not:none        → project_id IS NOT NULL
// ?filter[project]=<uuid>          → project_id = <uuid>
// ?filter[project]=not:<uuid>      → project_id != <uuid>, or project_id IS NULL
// ?filter[project]=none,<uuid>     → project_id IS NULL, or project_id = <uuid>
// ?filter[project]=not:none,<uuid> → project_id IS NOT NULL and != <uuid>

Signatúra: nullable(string $name, ?string $internalName = null, FilterValueShape $shape = FilterValueShape::Text, array $operators = [RequestedOperator::Not], string $sentinel = FilterSentinel::NONE). Negácia skutočnej hodnoty zahŕňa aj nenastavené riadky — „nie tento projekt“ pokrýva aj riadky bez projektu.

Sentinel je predvolená hodnota, nie rezervácia. Ak stĺpec legitímne ukladá reťazec none, odovzdajte vlastný:

AllowedFilter::nullable('assignee', 'assignee_id', FilterValueShape::Id, sentinel: 'unassigned'),

// ?filter[assignee]=unassigned → assignee_id IS NULL

Relácie — relation()

relation() porovnáva cez reláciu: whereHas pri zhode, whereDoesntHave pri negácii — nikdy negované whereHas, ktoré ponechá presne tie riadky, ktoré má vylúčiť (riadok s dvoma štítkami podmienku splní cez ten druhý). Druhý argument je relácia, tretí plne kvalifikovaný stĺpec v nej:

use RoundlyConsulting\QueryBuilder\Enums\FilterValueShape;
use RoundlyConsulting\QueryBuilder\Support\FilterSentinel;

->allowedFilters(
    AllowedFilter::relation('label', 'labels', 'labels.id', FilterValueShape::Uuid),
    AllowedFilter::relation('department', 'departments', 'departments.id', FilterValueShape::Id, sentinel: FilterSentinel::NONE),
)

// ?filter[label]=<id>               → whereHas('labels', labels.id IN (<id>))
// ?filter[label]=not:<id>           → whereDoesntHave('labels', labels.id IN (<id>))
// ?filter[department]=none          → no related departments at all
// ?filter[department]=not:none      → at least one related department
// ?filter[department]=none,<id>     → no department, or related to <id>
// ?filter[department]=not:none,<id> → has a department, and not <id>

Signatúra: relation(string $name, string $relation, string $column, FilterValueShape $shape = FilterValueShape::Text, array $operators = [RequestedOperator::Not], ?string $sentinel = null). Sentinel je predvolene vypnutý — odovzdajte ho tam, kde je „bez akejkoľvek väzby“ otázka, ktorú zoznam kladie.

JSON polia — jsonContains()

jsonContains() hľadá členstvo v JSON poli, napríklad v stĺpci tags, cez natívnu JSON podporu databázového drivera (whereJsonContains). exact() by porovnal celý dokument a partial() by našiel release aj vo vnútri pre-release:

->allowedFilters(
    AllowedFilter::jsonContains('tag', 'tags'),
)

// ?filter[tag]=release          → tags contains "release"
// ?filter[tag]=release,docs     → tagged release OR docs
// ?filter[tag]=not:release      → not tagged release (rows with NULL tags included)
// ?filter[tag]=not:release,docs → tagged neither

Signatúra: jsonContains(string $name, ?string $internalName = null, array $operators = [RequestedOperator::Not]). Viac hodnôt sa spája cez OR („ktorékoľvek z týchto“), ich negácia cez AND („žiadne z týchto“).

Podporované operátory

Tieto tri filtre odpovedajú presne na dve otázky — „je jedným z týchto“ a „nie je žiadnym z týchto“ — preto prijímajú len RequestedOperator::Is a RequestedOperator::Not, pričom is sa dá pomenovať vždy. Deklarovanie čohokoľvek iného (gte, contains, …) vyhodí UnsupportedOperator už pri vytvorení filtra: ide o chybu vývojára zachytenú pri deklarácii, nie o chybu requestu.