Open source
Query Builder for Laravel
composer require roundly-consulting/query-builder-for-laravelPrehľad
Natívny query builder pre zoznamové API endpointy v Laraveli. Deklarujete, ktoré filtre a triedenia endpoint povoľuje, a balík z query stringu — filter[…], sort, page, per_page — použije len tie a všetko ostatné odmietne s HTTP 400. Výsledkom je stále Eloquent builder, takže ďalej reťazíte with(), get() či paginate(). Licencia MIT, bez runtime závislostí okrem Laravelu, Symfony a dvoch malých sprievodných balíkov Roundly.
Čo získate
Predvolene cez allow-list
Spustia sa len deklarované filtre a triedenia; všetko ostatné vráti HTTP 400 alebo sa v režime ignore potichu zahodí.
Bohatá sada filtrov
Presná zhoda, boolean, čiastočná zhoda, prefix/sufix, porovnanie, scope, callback, trashed, členstvo v JSON poli aj vlastné filtre.
Operátory volené klientom
not:, contains: či gte: z množiny, ktorú deklarujete; nedeklarovaný token ostáva doslovnou hodnotou.
Nullable a relačné filtre
Sentinel none, not:none, negácie cez whereDoesntHave a tvary hodnôt, ktoré bránia chybám 500 na PostgreSQL.
Validované stránkovanie
HasPageSize validuje per_page (422) a pevne ho obmedzí; nakonfigurovaný názov stránky sa použije automaticky.
Bezpečné už návrhom
Viazané hodnoty, escapované zástupné znaky v LIKE, limity requestu a chybové hlášky s obmedzenou dĺžkou.
Dokumentácia
Inštalácia
Inštalácia cez Composer, voliteľné publikovanie konfigurácie a prekladov a kontrola aktívneho wire kontraktu cez artisan about.
Konfigurácia
Každý konfiguračný kľúč a jeho predvolená hodnota — názvy parametrov, limity veľkosti stránky, režimy neznámych parametrov a limity requestu.
Zostavenie dopytu
Obaľte model alebo pripravený builder cez QueryBuilder::for(), deklarujte allow-list a pokračujte ako s bežným Eloquent builderom.
Filtre
Všetky vstavané konštruktory filtrov — presná zhoda, boolean, čiastočná zhoda, prefix/sufix, scope, callback, trashed a vlastné — plus normalizácia.
Operátorové filtre
Pevné porovnania na serveri cez operator() a operátory volené klientom, napríklad not:, contains: či gte:, cez operators().
Nullable, relačné a JSON filtre
Filtrujte nullable stĺpce so sentinelom none, to-many relácie s negáciou cez whereDoesntHave a JSON polia podľa členstva.
Tvary hodnôt
Deklarujte FilterValueShape na typovaných stĺpcoch, aby chybné uuid či id vrátilo prázdny výsledok namiesto chyby 500 na PostgreSQL.
Validácia hodnôt filtrov
Obaľte validačné pravidlá do FilterValue, aby sa prefix operátora a sentinely odstránili ešte pred spustením pravidiel.
Triedenie
Povoľte polia na triedenie, mapujte verejné názvy na stĺpce, trieďte podľa viacerých stĺpcov a nastavte predvolené poradie.
Stránkovanie
Validujte a pevne obmedzte per_page traitom HasPageSize pre FormRequest; nakonfigurovaný názov stránky sa použije automaticky.
Formát požiadavky
Zmrazená syntax query stringu pre filtre, operátory, triedenie a stránkovanie a stavový kód, ktorý vráti každá chyba.
Neznáme parametre a chyby
Nepovolené filtre a triedenia vrátia HTTP 400 s preložiteľnou hláškou s obmedzenou dĺžkou — alebo sa v režime ignore zahodia.
Vlastné filtre a triedenia
Implementujte kontrakt Filter alebo Sort pre vlastnú logiku a v callbackoch parsujte formát operátorov cez RequestedOperator::split().
Bezpečnostný model
Ako balík drží vstup z requestu mimo SQL: allow-listy, viazané hodnoty, escapované zástupné znaky, limity requestu a obmedzený výstup chýb.
Testovanie
Builder v unit testoch riaďte cez Request::create() a na endpointoch overujte odpovede 400 a 422.
Požiadavky
PHP 8.4+, Laravel 12 alebo 13 a dva sprievodné balíky, ktoré sa nainštalujú automaticky — bez migrácií a ďalších PHP rozšírení.
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 kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
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.