Laravel Api Toolkit Laravel Package

Getting Started

• Install with composer require sinemacula/laravel-api-toolkit, then publish the config if you need to change defaults: php artisan vendor:publish --tag=api-toolkit-config.
• Look first at the package's config/api-toolkit.php (defaults for filters, sorting, pagination, includes) and the src/ tree — Filters, Sorting, Resources, and the response/exception handlers are the four areas you'll touch day-to-day.
• The quickest first use case is an index endpoint: extend the package's resource/controller base or apply the filterable/sortable traits to your Eloquent model, whitelist a couple of filterable columns, and hit GET /api/users?filter[name]=jane&sort=-created_at. That gives you a working query-string API in a single controller method.
• Read the README/docs for the request-parameter contract (filter, sort, include, fields, paginate) before writing custom filters — most integration work is mapping your models onto that contract.

Implementation Patterns

• Thin controllers, fat resources. Keep controllers to a single index/show call and push field selection, relationship loading, and response shaping into resource classes. This is the package's core opinion and fighting it causes duplication.
• Whitelist everything. Define allowed filters/sorts/includes per endpoint (or per resource) rather than accepting arbitrary columns. Treat the whitelist as your public API contract and review it in PRs alongside route changes.
• Custom filters for domain logic. Extend the base filter class and implement apply() for things like date ranges, LIKE searches, or enum mapping. Keep each filter single-purpose and composable; the toolkit chains them for you.
• Scope-aware filtering. When a filter needs boolean logic (orWhere, nested where groups), wrap it in a closure ($this->where(function ($q) { ... })) so it stays grouped inside the caller's existing constraints.
• Includes = eager loading. Use the include parameter with the resource's allowed relationships and verify the generated queries; add withCount/constrained eager loads in the resource rather than in the controller.
• Pagination defaults. Set page size and max page size in config, not per-controller, so every endpoint behaves consistently. Use the package's paginated response shape so clients get stable meta/links.
• Integration tips. Register the exception handler so validation failures on filter params return the toolkit's JSON error envelope rather than an HTML error page; keep API route files separate from web routes so middleware/rate limits apply correctly.

Gotchas and Tips

• Security fix in v1.16.5 — upgrade. This release groups filter criteria so a filter's $or condition can no longer escape the caller's scope. Prior versions could produce WHERE tenant_id = ? AND a = ? OR b = ?, leaking rows across tenant/soft-delete/authorization scopes. Upgrade immediately if you expose filters to untrusted input, and audit custom filters that call orWhere directly — wrap them in a grouping closure so the behaviour is explicit rather than relying on the package fix.
• orWhere is the sharpest tool in the box. Any custom filter using it should be tested with a scope active (tenant, soft deletes, published-only) to confirm the OR is contained.
• Config caching. After publishing/editing the config, run php artisan config:clear in local dev — stale cached config is the usual cause of "my allowed filters are ignored."
• Whitelist misses fail silently-ish. Unknown filter keys are typically dropped rather than erroring, which makes typos look like "no results." Log or assert on rejected parameters during development.
• Sorting is an injection surface. Never interpolate a raw sort value into orderBy; only pass column names that survived the whitelist, and map public names to real columns.
• Includes cause N+1 regressions. Every new allowed include is a potential performance cliff — pair them with eager-load constraints and add a test that asserts query count.
• Extension points to prefer: custom filter/sort classes, resource fields/toArray overrides, and the response/exception handlers. Avoid overriding the request parsing itself; that's where upgrades (like this one) land.
• Test the query, not just the JSON. DB::listen or assertDatabaseCount style assertions catch scope escapes and N+1s that response-shape tests miss.