Download the PHP package teoprayoga/laravel-teorion without Composer

Laravel Teorion

Request-driven query filter package for Laravel — a formalized, secure replacement for ad-hoc query scope traits, with whitelist enforcement, isolated scope parameters, and single-call ViewModel integration.

Features

• 🎯 Declarative QueryFilter classes — one per resource, central whitelist for filters/scopes/withs/sorts
• 🔒 Whitelist enforcement — no accidental scope/relation exposure to clients
• 🔐 Isolated scope params — scopes[0][params][role_id]=3 keeps params scoped without colliding with global request
• 🔌 Built-in filter types — Exact, Like, MultiLike, Boolean, Null, Enum, In, Date, DateRange, Between, Range, GreaterThan, LessThan, Has, JsonContains, Callback, Scope
• 🔁 Backward compatible — supports legacy scopes[]=name format alongside the new isolated-params format
• 📑 Dual sort format — Spatie-style ?sort=-col,col2 AND legacy ?order_by=...&order_direction=...
• 🗑️ Auto soft delete handling — ?with_trashed=1, ?only_trashed=1 work automatically on SoftDeletes models
• 📊 Aggregation support — withCount, withSum, withAvg, withMax, withMin via withAggregates[]
• 📜 Cursor pagination — switch to cursor-based paging via ?pagination=cursor for large datasets / infinite scroll
• 🔍 Query audit & fingerprint — deterministic SHA-256 fingerprint + QueryAudited event for observability, cache key derivation, and N+1 detection
• 🛠 Fluent filter API — .alias(), .default(), .required() chainable
• 🧰 Macro system — register custom global filter types via FilterMacroRegistry
• 📖 Scribe integration — auto-generate API docs from #[UsesQueryFilter] attribute
• ✅ Validation rule generator — HasQueryFilterRules trait auto-generates FormRequest rules

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13

Installation

(Service provider auto-discovers via Laravel package discovery.)

Quick Start

1. Generate a QueryFilter class

Creates app/QueryFilters/PostQueryFilter.php.

2. Declare your filters

3. Add the Filterable trait to your model

Three ways to bind a QueryFilter (pick one):

A. Convention (zero boilerplate) — model Post auto-resolves to App\QueryFilters\PostQueryFilter:

B. Property override — explicit, IDE-navigable:

C. Method override — for dynamic resolution:

Customize the convention namespace in config/teorion.php:

4. Use in your ViewModel/Controller

Request Format

Available Filter Types

Fluent API

Macros (Custom Filter Types)

Scribe Integration

Register the strategy in config/scribe.php:

Validation Rule Generator

Configuration

config/teorion.php (published via php artisan vendor:publish --tag=teorion-config):

• strict_mode=true → throws DisallowedScopeException / DisallowedWithException / ScopeMethodNotFoundException on unlisted requests
• strict_mode=false → silently skips disallowed values (production-safe default)

Cursor Pagination

For large datasets or infinite-scroll UIs, switch from offset to cursor pagination:

The response is a CursorPaginator exposing next_cursor / prev_cursor tokens. Pass via ?cursor=<token> to navigate.

Cursor pagination requires a deterministic orderBy clause — set one via $defaultSort in your QueryFilter (e.g., protected array $defaultSort = ['-id'];).

Query Audit & Fingerprint

Enable structured audit for every filterAndPaginate() and findFiltered() call:

Listen for the event:

The fingerprint is a deterministic SHA-256 hash of {filter_class, model_class, table, connection, normalized_parameters}. Parameters are recursively ksort-normalized so order doesn't change the hash. Useful for:

• Cache key derivation — same intent → same hash → same cache entry
• N+1 detection — duplicate hashes within one request indicate suspicious repetition
• Query analytics — group slow queries by fingerprint to find optimization targets

Customize excluded parameters (defaults exclude page/cursor/CSRF tokens):

Fingerprint Algorithm Choice

The default is sha256 — available without extensions, deterministic across PHP versions, fast enough (<1µs for typical request payloads). Hash itself is rarely the bottleneck — json_encode and recursive ksort dominate.

Three built-in algorithms (v2.4+):

Switch via config or env:

Switching invalidates existing fingerprints — derive cache keys with the algorithm prefix to make rotation safe: "query:{$result->algorithm}:{$result->hash}".

Custom algorithms (e.g., blake3 via ext-blake3) can be registered in your AppServiceProvider:

Sampling

For production scale (10k+ req/min), full-rate audit can flood the event bus. Use audit.sample_rate (0.0–1.0):

Sampling is deterministic per fingerprint — same query intent always produces the same audit decision (always-on or always-off). This is intentional: random sampling would break fingerprint-based cache dedup (same query might or might not be audited). Hash-based sampling keeps decisions consistent.

Audit Boundaries

The audit hook is wired to these teorion terminal methods:

For audit on raw Builder chains, swap filter() → filterAudited():

Listener Recipes

The package emits events; you decide persistence and side effects. Five patterns:

1. Persist to database — your own audit log table:

2. Slack alert on slow queries (>500ms):

3. Redis dedup cache (memoize identical queries):

4. N+1 detection within request:

5. Sentry breadcrumb (low-overhead observability):

Testing

License

MIT