sinemacula / laravel-api-toolkit
Query parsing, schema-driven resources, repositories, services and OpenAPI export for Laravel APIs
Requires
- php: ^8.3
- aws/aws-sdk-php: ^3.342
- illuminate/database: *
- illuminate/http: *
- illuminate/notifications: *
- illuminate/routing: *
- illuminate/support: ^12.9
- illuminate/validation: *
- phpnexus/cwh: ^3.0
- sinemacula/laravel-repositories: ^1.0
- sinemacula/laravel-resource-exporter: ^1.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.85
- laravel/framework: ^12.9
- phpstan/phpdoc-parser: ^2.2
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.0
- squizlabs/php_codesniffer: ^3.13
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-master
- 1.x-dev
- v1.17.0
- v1.16.9
- v1.16.8
- v1.16.7
- v1.16.6
- v1.16.5
- v1.16.4
- v1.16.2
- v1.16.1
- v1.16.0
- v1.15.9
- v1.15.8
- v1.15.7
- v1.15.6
- v1.15.5
- v1.15.4
- v1.15.3
- v1.15.2
- v1.15.1
- v1.15.0
- v1.14.0
- v1.13.0
- v1.12.5
- v1.12.4
- v1.12.3
- v1.12.2
- v1.12.1
- v1.12.0
- v1.11.0
- v1.10.3
- v1.10.2
- v1.10.1
- v1.10.0
- v1.9.5
- v1.9.4
- v1.9.3
- v1.9.2
- v1.9.1
- v1.9.0
- v1.8.0
- v1.7.0
- v1.6.3
- v1.6.0
- v1.5.1
- v1.5.0
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2
- v1.1.10
- v1.1.9
- v1.1.8
- v1.1.7
- v1.1.6
- v1.1.5
- v1.1.4
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.0
- dev-fix/narrowed-enum-rule-export
- dev-chore/remove-stale-v2-playbook
- dev-chore/coding-standards-comment-wrap-conformance
- dev-chore/coding-standards-laravel
- dev-feature/restful-route-linter
- dev-feature/http-primitives-integration
- dev-feature/typed-service-inputs
- dev-feature/service-composition-decoupling
This package is auto-updated.
Last update: 2026-11-22 15:11:20 UTC
README
Building blocks for JSON APIs in Laravel: a request query parser, schema-driven resources with an allowlisted query surface, repositories, a JSON exception handler, a service layer and an OpenAPI 3.1 exporter.
Installation
composer require sinemacula/laravel-api-toolkit
Laravel Boost
The package ships a skill holding its authoring rules, at resources/boost/skills/laravel-api-toolkit/SKILL.md. With
Laravel Boost, php artisan boost:install offers it and php artisan boost:update refreshes the installed copy after a
toolkit upgrade; Boost reads package skills from direct dependencies only. Without Boost, copy
vendor/sinemacula/laravel-api-toolkit/resources/boost/skills/laravel-api-toolkit into the skills directory your
tooling reads, and copy it again after each upgrade.
Configuration
Publish the config file:
php artisan vendor:publish --provider="SineMacula\ApiToolkit\ApiServiceProvider" --tag=api-toolkit-config
config/api-toolkit.php is documented inline. Per-query repository caching is configured separately, in the
sinemacula/laravel-repositories package under repositories.cache.
Each setting read from the environment is named API_TOOLKIT_ followed by its key, upper-cased with dots as
underscores: deferred_writes.on_failure is API_TOOLKIT_DEFERRED_WRITES_ON_FAILURE. A boolean also accepts 1, 0,
on, off, yes and no, and an integer a string of digits.
Every setting is validated once the application boots to serve requests or queue jobs, and when config:cache or
optimize builds the config cache. An invalid value, or a key the toolkit does not read, throws
InvalidConfigurationException naming the key; nothing is defaulted, clamped or ignored. Other console commands fail
only where they read the invalid setting, which for a setting read at boot is every command. Under a cached
configuration the message names the cache file to delete before rebuilding it.
Run php artisan api-toolkit:config:validate in CI or a deploy step to apply the same check from the console. It exits
with a failure and the message boot would throw, so a removed or misnamed setting is caught before it stops the workers.
The Markdown templates for the generated API manual are published with --tag=api-toolkit-docs.
Translations
The toolkit's own client-facing messages are translation lines in the api-toolkit namespace: exceptions.php holds
the error titles and details, keyed by integer error code, and validation.php holds the 422 messages for rejected
query parameters. Publish them with --tag=api-toolkit-lang, which copies them to lang/vendor/api-toolkit (or
resources/lang/vendor/api-toolkit when the application keeps its translations there).
Laravel merges a published file over the package's own, so keep only the lines you change. A full copy freezes the
wording of every other line against later releases. Placeholders such as :key and :operator carry the parameter
names exactly as the client sent them, and do not pass through validation.attributes.
To add a locale, create lang/vendor/api-toolkit/<locale>/validation.php (and exceptions.php) with the lines you
translate. Missing lines fall back to English as long as app.fallback_locale is en.
A message is worded in the locale current when it is raised. ParseApiQuery is global middleware, so a malformed
page, limit, filters or search value is rejected before any route middleware runs, while an undeclared key or
operator is rejected later, in the controller. An application that sets the locale in route middleware, for example
from the authenticated user, sets api-toolkit.parser.register_middleware to false and adds ParseApiQuery to its
routes after its locale middleware.
A Payload enum value is checked with the other rules and fails with Laravel's validation.enum line, so it honours
validation.attributes and the locale like any other field.
Usage
API Query Parser
ApiQueryParser sits behind the ApiQuery facade and is populated by the ParseApiQuery middleware, which the
service provider pushes onto the global middleware stack unless api-toolkit.parser.register_middleware is false.
Parameters are read from the query string only; a request body is never parsed. Every key and value in page, limit,
cursor, fields, aggregates, filters, search, order and trashed must be valid UTF-8, or the request is
rejected with a 422 on that parameter.
Sparse fieldsets - request only the fields you need for a resource type:
GET /users?fields[users]=id,name,email
use SineMacula\ApiToolkit\Facades\ApiQuery; $fields = ApiQuery::getFields('users'); // ['id', 'name', 'email']
A type is the lower-cased RESOURCE_TYPE of a resource that is mapped or lives under resources.paths. Names are
checked against the type they are keyed by, whatever the endpoint: an unknown type or an undeclared name is rejected
with a 422 on fields.{type} naming each. ?fields=name, with no type, is rejected too, and ?fields[users]= returns
the fixed fields only.
Filtering - pass a URL-encoded JSON object of operator tokens:
GET /users?filters={"status":{"$eq":"active"},"created_at":{"$ge":"2024-01-01"}}
A filters value that is not a JSON object is rejected with a validation error.
Built-in operators: $eq, $neq, $gt, $lt, $ge, $le, $in, $between, $contains, $null, $notNull.
Each is accepted only on a column whose declared capability allows it (see
Query capabilities); any other pairing is rejected with a 422 naming the operator, the
column and the operators that column accepts. The shorthand {"name":"Alice"} is $eq and is gated the same way.
Each built-in operator takes a value of one shape:
| Operator | Value | Matches rows |
|---|---|---|
$eq, $neq |
one value | equal, or not equal, to it |
$gt, $ge, $lt, $le |
one value | above or below it |
$in |
a list, empty allowed | equal to any item; an empty list matches none |
$between |
[low, high] |
from low to high inclusive |
$null, $notNull |
true |
missing, or holding, a value |
$contains |
one value or a list | whose JSON array holds it, or every item |
null is never a value: a missing value is matched by {"name":{"$null":true}}, so {"name":null} is refused. Every
value is also checked against the column's type, read from the schema catalogue. An integer column takes an integer, a
digit string or a boolean, a boolean column true, false, 0 or 1, a number column a finite number, a uuid
column a UUID, a date YYYY-MM-DD, and a date-time column a date or YYYY-MM-DDTHH:MM[:SS[.fraction]], with a space
allowed in place of the T and an optional Z or offset such as +02 or +02:00. A date-time with an offset is
converted to the application timezone, so a timestamp a resource emitted can be sent back as it is. A column cast to an
enum takes only its cases' values, or a pure enum's lowercase names. A value outside its shape or its column's type is
rejected with a 422 at its position, naming the form expected. Where the catalogue cannot be read, only the shape is
checked.
$contains matches an element of a JSON array, or a whole scalar document, of the same JSON type, so 1 matches
neither "1" nor true. Its list must not be empty, and its items are not checked against the column's type. A string
is never decoded as JSON; a comma-separated string matches any of its items, each a string. On MySQL an item also
matches an element of a nested array.
The entries of a filter document AND together, at every depth. $and and $or take a non-empty list of filter
documents, each grouped on its own and joined by AND or OR:
{"status":"active","$or":[{"name":"a"},{"email":"b"}]}
{"$or":[{"role":"admin","status":"active"},{"role":"owner"}]}
{"$and":[{"$or":[{"a":1},{"b":2}]},{"$or":[{"c":3},{"d":4}]}]}
{"$or":[{"name":"a"},{"posts":{"user":{"name":"b"}}}]}
A relation declared traversable() takes a filter document for the related resource, checked against that
resource's own declarations, and compiles to whereHas(). $has and $hasnt take a relation name, a list of names,
or relation names keyed to filter documents, and compile to whereHas() and whereDoesntHave(). Every condition in
one relation document must hold for the same related row: {"posts":{"a":1,"b":2}} needs one post matching both,
while {"$and":[{"posts":{"a":1}},{"posts":{"b":2}}]} may match different posts.
The key is the Eloquent relation name, whatever alias the field renders under. The related level is governed by the
resource the relation declares, so Relation::to('author', PublicUserResource::class)->traversable() accepts only what
PublicUserResource filters, even where the related model's resource_map entry filters more. A relation declaring
no resource falls back to that entry, and a MorphTo is governed by the entry of each concrete type, so a key is
rejected unless every type stored in the table permits it. A level no resource governs rejects every key. A MorphTo
with no type stored is never descended, so its nested keys go unchecked, $has matches nothing and $hasnt matches
every row.
A filter that cannot narrow the query is rejected with a 422 keyed by its position, such as filters.$or.1.name,
rather than dropped: a group that is not a non-empty list, an empty group document, a condition with no column, a
column given an empty object, a list, or a key that is not a registered condition, and any entry that adds no
condition, such as an empty $has list.
Named scopes - a resource can let clients invoke its model's local scopes, a scopeUpcoming() or #[Scope]
method, by name:
use SineMacula\ApiToolkit\Schema\Scope; Field::set( Field::scalar('visibility')->filterable(Capability::EXACT), Scope::of('upcoming')->description('Events that have not started yet.'), Scope::of('near')->parameters([ 'lat' => ['required', 'numeric', 'between:-90,90'], 'lng' => ['required', 'numeric', 'between:-180,180'], 'km' => ['required', 'integer', 'between:1,50'], ])->description('Events within km kilometres of the point.'), Scope::of('ownedByCaller', 'mine')->visibleTo(fn (?Request $request): bool => $request?->user() !== null), );
{"visibility":"public","$scope":"upcoming"}
{"$scope":{"near":{"lat":51.5,"lng":-0.12,"km":5},"upcoming":{}}}
{"$or":[{"$scope":"mine"},{"visibility":"public"}]}
{"sessions":{"$scope":"upcoming"}}
$scope takes a name, a list of names, or names keyed to objects of arguments, {} for none. Scopes AND with the
rest of their document, compose inside $and and $or, and in a relation body or under $has resolve against the
related resource's scopes. Each scope counts toward max_nodes. visibleTo() hides a scope from a caller, to whom it
answers as undeclared.
parameters() takes rules keyed as in a form request. The validated arguments reach the method as named arguments, so
the method's parameter names are the contract and key order does not matter. Values arrive as decoded JSON under PHP's
coercive typing, so the rules must admit only what the parameter types accept. An undeclared argument, a failed rule,
a required parameter a rule left unfilled, a null for a parameter refusing it and a ValidationException the scope
throws are each a 422 keyed under the scope, such as filters.$or.1.$scope.near.km. api-toolkit:validate-schemas
checks every declaration against its method.
A scope may only add where clauses, and one adding none matches every row. A scope that returns another builder,
eager loads, removes a global scope (withTrashed() included), or changes the query's columns, table, joins, orders,
groups, limits, unions or lock throws a LogicException. Eloquent drops an order inside the scope's own nested
where() closure, a global scope it registers and an afterQuery() callback unseen, so they are unsupported. Trashed
rows stay with ?trashed.
Declarations and their rule objects are compiled once per worker, so they must not depend on the request and must validate repeatedly. What a scope reads about the caller or the clock is read when it runs, on a queue worker too.
Free-text search - match a term against the fields a resource declares searchable():
GET /users?search=smith
The term is matched against the requested resource's own columns, never through a relation. Each searchable field
declares a match strategy (SearchStrategy::EXACT, PREFIX or SUBSTRING), and the connection's search driver
refuses a strategy it cannot serve from an index. Terms are bounded by api-toolkit.search; a term outside the bounds
is rejected with a 422, not trimmed.
The minimum word length is three characters. Configuration can raise it, and refuses a value below three: below three, MySQL matches nothing once a word is shorter than the n-gram token size, and PostgreSQL answers by reading the whole table. The minimum applies to each word, because a short word is dropped from a MySQL full-text phrase but kept by a PostgreSQL pattern match, so the two engines would return different rows.
Each engine still compares text by its own rules. MySQL folds case and accents through the column's collation, and
matches a multi-word term's words in order whatever whitespace separates them. PostgreSQL folds case but not accents,
and SQLite folds only ASCII case. An EXACT match compares with =, so it ignores case only under a case-insensitive
collation, such as MySQL's default.
Drivers ship for MySQL, PostgreSQL and SQLite, registered under the driver name each connection reports. On MySQL the
proof also checks that the planner can use the index, which the catalogue only reports from 8.0; on older versions
that check is skipped. MariaDB reports its own driver name and has no n-gram parser, so a search on a MariaDB
connection fails until you register a driver for it on the SearchDriverRegistry.
The indexes belong in your own migrations:
- On MySQL, the columns declared
SUBSTRINGare matched together through a singleMATCH, which needs oneFULLTEXTindex over exactly that column list, createdWITH PARSER ngram. A full-text match OR-ed with any other predicate reads the whole table, so the driver refuses aSUBSTRINGdeclaration beside any other strategy on the same resource. - On PostgreSQL,
PREFIXandSUBSTRINGeach need agin_trgm_opsindex on their own column, with thepg_trgmextension installed. Columns may mix strategies. EXACTneeds an ordinary index leading with the column on either engine. On PostgreSQL that B-tree must use the column's own collation.
php artisan api-toolkit:validate-schemas reports a searchable declaration with no index behind it; run it in CI
against a migrated database. Because schema validation is off in production by default, the proof is also taken at
request time, so a missing index refuses the request instead of scanning the table. On PostgreSQL a missing trigram
index is not an error, so without this the search would silently run as a sequential scan.
The request-time proof is cached in the cache store for api-toolkit.search.index_proof_ttl seconds
(API_TOOLKIT_SEARCH_INDEX_PROOF_TTL, default 60), keyed by the connection's schema and the declaration, and shared
by every request, job and worker. The expiry runs from the first read. A migration retires every cached proof through
the migration hook. An index changed outside a migration, or while the hook is off or failed to write, is picked up
when the expiry lapses or after php artisan api-toolkit:invalidate-metadata. 0 keeps each answer for one request
or job. Within one operation the answer is also held in memory, so a long-running job may keep it past the expiry.
The only way to turn the request-time proof off is api-toolkit.search.unverified_connections, which lists the
connections a driver may serve a search on without proving an index. It ships empty. SQLite cannot prove any index,
so a SQLite development connection must be listed before a searchable field is served:
'search' => [ 'unverified_connections' => ['sqlite'], ],
With validate_schemas on (the default outside production), an unlisted connection fails application boot, not just
the search request: every route and every Artisan command, including php artisan migrate on a fresh checkout with
no database file yet. List the connection, or set API_TOOLKIT_RESOURCES_VALIDATE_SCHEMAS=false until you do.
Entries are connection names as config/database.php keys them, not engines. A stock application names each
connection after its engine, so listing mysql waives the connection that usually serves production. A listed
connection may scan the whole table on every request; only list development connections.
?search=smith&order=relevance orders the matches by the best way each row matches the term, best first:
| Rank | The term matches | Reached by |
|---|---|---|
| 1 | the whole value | EXACT, PREFIX, SUBSTRING |
| 2 | the start of the value | PREFIX, SUBSTRING |
| 3 | the start of a space-delimited word | SUBSTRING |
| 4 | anywhere else | SUBSTRING |
A row ranks by its best searchable column, compared with = for EXACT and otherwise like, or ilike on
PostgreSQL, so case folds as it does in matching. A MySQL n-gram match no literal pattern sees ranks last. An
EXACT-only resource adds no order, since every match ranks first. relevance applies at its position in the order
list, so order=relevance,name breaks ties by name before the appended key. It needs search, offset pagination and
the asc direction; anything else is a 422 on order.relevance. A custom driver implements rank() to order its
own matches.
Relevance is a computed sort no index serves, so it reads every matching row. Behind a MySQL full-text or PostgreSQL
trigram lookup that costs one CASE per match; where the planner could otherwise stop after one page, it reads them
all. It is unsupported beside a repository scope that adds distinct, group by or a union.
Sorting - sort by one or more columns, with optional direction:
GET /users?order=last_name,first_name:desc
A direction is asc (the default) or desc, in any case; anything else, including an empty suffix, is rejected with a
422 on order.{column} rather than ignored, as is a column ordered by twice. paginate() appends the model key in
the last direction when the order does not already include it, so rows tied on the requested columns never repeat or go
missing between pages. The appended key needs no sortable() declaration and does not count against max_order_keys. A
grouped read takes its group columns instead; a read grouped by an expression, filtered by having without groups,
distinct on columns, or distinct without selecting the columns it would take gets nothing appended and needs a
unique order of its own. A sortable() field names a column of the model's table, so a select alias a repository scope
adds cannot be ordered by.
A cursor can only seek by a column that holds a value in every row, so a cursor-paginated read rejects random and
any column the cached column catalogue reports as nullable, such as the created_at that timestamps() creates;
declare the column NOT NULL to cursor-page by it. Offset pagination sorts by either. Columns a repository scope
orders by must be NOT NULL for cursor pages too. A read ordered by raw SQL (orderByRaw()), an expression, a subquery
or inOrderOf() is refused cursor pagination with a 422 on pagination. A cursor that does not decode, does not
carry a value for every ordered column (the client changed ?order and kept ?cursor), or carries a value its column
cannot hold is rejected with a 422 on cursor; restart from the first page. A cursor carries each ordered column as
the row stores it, not as the model casts it, so a microsecond timestamp, an enum or a value object seeks from exactly
where its page ended. A model whose table has no column for its key is offset-paged without the appended key, and
refused cursor pagination with a 422 on pagination unless the read is grouped and ordered.
Filters and sorts compare by each column's collation, and each engine places NULLs its own way; the toolkit normalises
neither. With default settings, MySQL matches {"name":"alice"} to Alice and sorts anna, Ben, cara;
PostgreSQL matches case exactly and sorts by the database locale (anna, Ben, cara under en_US.UTF-8); SQLite
matches and sorts byte by byte (Ben, anna, cara). An ascending sort puts NULLs first on MySQL and SQLite and last
on PostgreSQL, and a descending sort the reverse.
Sorting by aggregates and relations - an aggregate or a to-one relation declared sortable() can order a read.
No index serves an order by a correlated subquery, so the declaration takes the reason the order may run unindexed:
Count::of('posts')->sortable('Leaderboard; the active filter bounds the set'), Sum::of('orders', 'total', 'spend')->sortable('Admin list of a few thousand accounts'), Relation::to('customer', CustomerResource::class)->sortable('Back-office order list'),
GET /users?order=aggregates.posts_count:desc GET /orders?order=customer.name
An aggregate is ordered by aggregates.{key}, the path its value renders under, whether or not the request selects
it. A relation is ordered by {relation}.{column}: the Eloquent relation name and a sortable() column of the
resource the relation renders, one hop deep. Only a BelongsTo, or a HasOne, MorphOne or HasOneThrough declared
with latestOfMany() or ofMany(), may be sortable, so the order always reads the row the response renders; schema
validation reports any other. A sortable relation renders a resource, takes no constrain() and no row guard, and
caller guards on the relation, the column or the aggregate hide the key as they hide the field.
The order reads the stored value before transformers, runs the aggregate's constraint, the related model's global scopes
and the request's trashed state, and counts once against max_order_keys. A relation key orders a row with no related
row, or one a withDefault() relation fills in, as NULL, and an aggregate key orders an empty sum, average, minimum
or maximum as NULL and an empty count as 0; the engine places NULL first ascending on MySQL and SQLite and last on
PostgreSQL. These keys cannot order a cursor-paginated read, which is refused with a 422 on order.{key}.
Page-size ceiling - a ?limit above api-toolkit.parser.max_limit (default 100) is rejected with a 422 naming
the ceiling and the requested size, not reduced to the ceiling. Set the ceiling to 0 to disable it:
GET /users?limit=200 // 422, the ceiling is 100 GET /users?limit=25 // honoured as-is
A resource whose rows are expensive can lower the ceiling for itself. Its pages default to the lower of
parser.defaults.limit and its ceiling, and the exported limit parameter and query surface docs state both:
public static function maxLimit(): ?int { return 25; }
It can only lower the configured ceiling: a value above it changes nothing, it applies alone while the configured
ceiling is 0, and a value below 1 throws a LogicException. paginate() and withApiCriteria() refuse a limit
over it with the same 422, for the resource the repository resolves, including one named with usingResource().
Relation aggregates - request declared aggregates per resource type by their keys. Requesting any aggregate replaces
every default of that type, as ?fields replaces $default. A type's aggregates apply wherever it renders, at the root
or embedded, and render under its aggregates field when its field selection includes it:
GET /users?fields[users]=name,aggregates&aggregates[users]=posts_count,orders_sum_total,last_order_at
ApiQuery::getAggregates('users'); // ['posts_count', 'orders_sum_total', 'last_order_at']
An aggregate key the type does not declare is rejected with a 422 on aggregates.{type}, and ?aggregates[users]=
selects none. A resource embedded through a MorphTo relation or a PolymorphicResource loads no aggregates.
{
"_type": "users",
"name": "Ada",
"aggregates": {"posts_count": 3, "orders_sum_total": 120.5, "last_order_at": "2026-01-01T10:00:00.000000Z"}
}
Pagination - ?pagination=cursor (or any ?cursor token) selects cursor pagination, and offset pagination is used
otherwise. An empty pagination reads as absent; any other value is rejected with a 422. A non-empty offset page
shorter than limit, or an empty first page, derives its total without a count. Any other page counts at most the rows
through the last page query_cost.max_offset allows: past that, meta.total is those rows, meta.total_capped is
true and Total-Count is absent, so read further with cursor pagination. That bounds the rows the count admits, not
the rows it examines; set max_offset to 0 for exact, unbounded totals. A capped page is a
CappedLengthAwarePaginator, which a container binding of LengthAwarePaginator does not replace. A simplePaginate()
result renders the cursor envelope. Offset pages do not support an ungrouped aggregate projection such as
selectRaw('max(id) as id'), which is one row rather than a pageable set, nor a distinct or union over a join without
an explicit projection, which MySQL refuses to count.
Soft deletes - ?trashed=with or ?trashed=only, read as a TrashedState from ApiQuery::getTrashed(). The
criteria layer applies it only where the model uses SoftDeletes and the resource opts in by overriding
allowsTrashed(); anywhere else the request is refused with a 422 on trashed, as is any value other than with or
only, so a client never mistakes live records for the ones it asked for. On a read through the criteria, a relation
follows the state where its own resource opts in and otherwise stays live, wherever it is included, aggregated or
filtered on ($has and $hasnt too). A read that applies no criteria, such as implicit route-model binding, only
checks the value.
Row visibility - override restrictRows() on a resource to limit the rows a request may see through it:
public static function restrictRows(Builder $query, Request $request): void { $query->whereIn($query->qualifyColumn('workspace_id'), $request->user()?->workspaceIds() ?? []); }
The rule applies to the root query and its total, a single record (an invisible one is a 404), every include through the
criteria or loadMissing, every relation filter ($has means "has a visible row") and every relation aggregate,
rendered or ordered by. A related row follows the resource its parent declares over the relation, else the one mapped to
its model. Qualify each column and add only wheres; anything else throws. Write it to fail closed: an empty whereIn()
matches nothing for a request without a user, while where($column, null) matches every row whose column is null. Not
covered: route-model binding and queries the application builds, relations or aggregates loaded before rendering,
repository scopes and persistent criteria, writes, and compute fields or accessors that query. With validate_schemas
on, a model whose $with or $withCount default reaches a restricted resource is refused. Use a global scope for an
invariant of the model everywhere, a relation method for a fixed predicate of one relation, constrain() to shape an
include, a policy to authorise an action, and restrictRows() for what a caller may see through the API.
Schema-Driven ApiResource
Extend ApiResource and declare a schema() method using the Field and Relation helpers and the relation aggregate
helpers. The compiled schema drives field resolution, guards and eager-load planning.
use App\Models\User; use SineMacula\ApiToolkit\Attributes\ForModel; use SineMacula\ApiToolkit\Enums\Capability; use SineMacula\ApiToolkit\Enums\SearchStrategy; use SineMacula\ApiToolkit\Http\Resources\ApiResource; use SineMacula\ApiToolkit\Schema\Count; use SineMacula\ApiToolkit\Schema\Exists; use SineMacula\ApiToolkit\Schema\Field; use SineMacula\ApiToolkit\Schema\Max; use SineMacula\ApiToolkit\Schema\Relation; use SineMacula\ApiToolkit\Schema\Sum; #[ForModel(User::class)] class UserResource extends ApiResource { const RESOURCE_TYPE = 'user'; protected static array $default = ['id', 'name', 'email', 'created_at']; public static function schema(): array { return Field::set( Field::scalar('id'), Field::scalar('name')->filterable(Capability::EXACT)->sortable()->searchable(SearchStrategy::SUBSTRING), Field::scalar('email')->filterable(Capability::EXACT)->searchable(SearchStrategy::SUBSTRING), Field::timestamp('created_at')->sortable(), Field::compute('full_name', 'getFullName'), Field::can('restore'), Relation::to('organization', OrganizationResource::class)->traversable(), Count::of('memberships')->default(), Sum::of('orders', 'total'), Max::of('orders', 'created_at', 'last_order_at'), Exists::of('messages', 'has_unread_messages')->constrain(fn ($query) => $query->whereNull('read_at')), ); } public function getFullName(): string { return "{$this->first_name} {$this->last_name}"; } }
Date fields - Field::timestamp() renders an ISO 8601 date-time and Field::date() a calendar date, from a cast
date or a date string an uncast column holds. A non-null value that is neither throws, rather than rendering as null.
Relation aggregates - six helpers load an aggregate over a relation in the same query, through Laravel's
withAggregate(). Each has one key, which names it in the declaration, the ?aggregates request, the response and the
exported schema. The key defaults to Laravel's own attribute name and as() or the last argument of of() replaces it:
| Helper | Default key | Value |
|---|---|---|
Count::of('posts') |
posts_count |
integer, 0 without related rows |
Exists::of('posts') |
posts_exists |
boolean, false without related rows |
Sum::of('orders', 'total') |
orders_sum_total |
number or null |
Average::of('orders', 'total') |
orders_avg_total |
number or null |
Min::of('variants', 'price') |
variants_min_price |
the column's value or null |
Max::of('orders', 'created_at') |
orders_max_created_at |
the column's value or null |
constrain() narrows the related rows, default() includes the aggregate when the request names none, and guard(),
visibleTo(), transform() and openapi() work as on fields. Sum, average, minimum and maximum are null over zero
related rows. A sum or average is a JSON number on every engine, so a decimal column sums with float precision. A
minimum or maximum is read the way the related model reads that column, so a timestamp renders as
2026-01-01T10:00:00.000000Z, a decimal:2 cast as an exact string such as "12.50" and a cast enum as its value. A
key that reads as an integer, such as 12, fails to compile. api-toolkit:validate-schemas rejects an aggregate over a
sensitive or missing column, a sum or average over a non-numeric column, a minimum or maximum the related model would
read back through an accessor or a non-scalar cast, a MorphTo relation, and an aggregate_<key> attribute the owner
model already uses as a column, cast or setter.
Only fields marked filterable() or sortable() can be queried, and ?search= matches only fields marked
searchable(). Relations marked traversable() can be targeted by nested filters. A column declared filterable with
two capabilities fails to compile, as does a field named _type or _truncated, or one named aggregates beside a
declared aggregate, since the response writes those keys itself. $default lists the fields returned when the client
sends no ?fields, and the static $fixed the fields added to every selection, after those in
resources.fixed_fields. Schema validation rejects a default or fixed field the resource does not declare. A tabular
export has a column for each selected field, in the order selected: the requested fields, every field for :all, or the
defaults. Relations are left out and fixed fields are not added.
Guards - guard(fn ($resource, $request) => ...) is a row guard and visibleTo(fn ($request) => ...) a caller
guard; either hides the field, aggregate or relation when it returns exactly false. A query cannot honour a row guard
without revealing what it hides, so a row-guarded field that is filterable(), sortable(), searchable() or
traversable() fails to compile. A caller guard reads only the request, so its field stays queryable by the callers it
admits; any other caller is refused with the same 422 as an undeclared key, and the OpenAPI export marks the key
conditional. A search matches the same columns for every caller, so a caller-guarded field may not be searchable().
A column everyone may query but only some may see is declared queryable on an unguarded field as well. A tabular export
refuses a selected row-guarded field with PerItemGuardedFieldException and drops a caller-guarded column it hides.
Schema lifetime - schema() runs once per resource class per worker, and its result is shared by every request
the worker serves, under Octane and on queue workers alike. It must not read or capture the request, the user, the
tenant, the query parser, the clock or runtime config, and the closures it declares must not retain them. Read
per-request values when a closure runs instead: row guards, accessors and compute closures receive the resource and
the request, caller guards the request, constraints the query, and transformers the resource and the value.
Declared column reads - needs() names the base-table columns a field reads. Declare it on any field whose value
does not come straight from the column of the same name, such as one over an Eloquent accessor or custom cast, or an
accessor closure:
// The model's fullName(): Attribute reads first_name and last_name Field::scalar('full_name')->needs('first_name', 'last_name'), Field::accessor('initials', fn ($resource) => $resource->first_name[0] . $resource->last_name[0]) ->needs('first_name', 'last_name'),
Ability flags - Field::can('restore') renders whether the current user passes a policy ability on each record, as
the boolean can_restore. The key is can_ and the snake-cased ability, so Field::can('forceDelete') is
can_force_delete; pass an alias as the second argument for an ability with dots or hyphens, or one whose key would
collide with another's. The flag renders only when the field set includes it, so a page runs the policy only when asked.
The request's user answers, a guest request answers as a guest, and a resource resolved without a request answers for
the authenticated user. Load the relations the policy reads with extras(). Without needs() the flag leaves the
select unnarrowed; with it, the list must cover every column the policy and any before() hook read. The flag is
computed, so it cannot be filtered, sorted or searched.
Query capabilities - filterable() takes the access path the column has, and the capability decides which
operators the column answers. Any other operator is refused with a 422:
| Capability | Declare it for | Operators the column answers |
|---|---|---|
Capability::EXACT |
a keyed column read by equality - an id, a foreign key, an email | $eq, $in, $null, $notNull |
Capability::ENUM |
a small closed set, so the complement of one value stays bounded | $eq, $in, $neq, $null, $notNull |
Capability::RANGE |
an ordered column - a number, a date, a timestamp | $eq, $in, $gt, $ge, $lt, $le, $between, $null, $notNull |
Capability::DOCUMENT |
a JSON column behind a containment index | $contains |
Capability::OPAQUE |
a column with no access path the resource will vouch for | $eq |
These are the shipped defaults. An operator your application registers names the capabilities that admit it (see Filter-Operator Registry).
Model binding and discovery - #[ForModel(...)] binds a resource to its model, and may be repeated to bind one
resource to several models. With api-toolkit.resources.paths left null (the default), resources are discovered at
boot from app_path('Http/Resources') and each module's app_path('*/Http/Resources'). Set paths to an array to
choose the roots, or to an empty array to disable discovery. An explicit api-toolkit.resources.resource_map entry
always wins over a discovered binding: use it to pick the canonical resource when a model has more than one, or to
bind a resource outside the scanned paths. When two discovered resources claim the same model and no explicit entry
resolves it, the first in sorted file order wins and a warning is logged; with validate_schemas enabled the boot
fails instead. Every resource under the paths is recorded, bound or not, so its type can be selected and schema
validation covers it; a relation that renders a resource outside both the map and the paths is a schema defect.
Without a compiled map the scan runs on every boot, which is fine for development. In production run
php artisan optimize (or php artisan api-toolkit:resources:cache) on every deploy. It compiles the map to
bootstrap/cache/api-toolkit-resources.php; php artisan optimize:clear (or php artisan api-toolkit:resources:clear)
removes it. While the file exists it is served as-is, so rebuild or clear it after adding, moving or re-binding a
resource, or after changing paths. These four commands boot without merging discovered resources, so a stale map
never blocks its own rebuild. With validate_schemas enabled the file is ignored and the scan runs on every boot.
Discovery never uses the cache store, so with validate_schemas disabled, boot and route:cache work without a
reachable store; schema validation reads its metadata through the store.
Polymorphic aliases - with api-toolkit.resources.enable_dynamic_morph_mapping on (the default), each
resource's RESOURCE_TYPE is registered as its model's morph alias. The aliases merge with your own
Relation::morphMap(), and yours always win: an alias you register, or a model you have already mapped, is left
alone whatever the boot order. An alias claimed by more than one model is registered for none of them. A morph map is
never required, so a model without a resource (a vendor model, say) keeps morphing to its class name; call
Relation::requireMorphMap() in your own service provider to make mapping strict. A later
Relation::morphMap([...], merge: false) replaces the whole map, derived aliases included. Polymorphic rows store the
alias, so renaming a RESOURCE_TYPE, or binding a second model to a resource (which withholds its alias), orphans
rows already stored under the old alias.
Generating a resource - php artisan api-toolkit:make:resource OrderResource writes
app/Http/Resources/OrderResource.php, bound by #[ForModel] to the model guessed from the class name
(App\Models\Order). Pass --model= to name another model, including one outside your application, --type= to
choose the RESOURCE_TYPE (the snake-cased model name by default), and --force to overwrite an existing file. The
command reads no database. The draft exposes only the model key, as its one field and its default, so nothing else is
returned and nothing is filterable, sortable or searchable: declare each further field and its query surface by hand.
The command refuses a type another mapped resource already returns, and a model another discovered resource already
binds without an explicit resource_map entry. It warns when discovery will not see the file (outside paths, or a
compiled map in place), and notes the morph alias a model not yet mapped will gain. Run php artisan stub:publish to
customise stubs/api-toolkit.resource.stub.
Eager-load planning - the resource builds with() and withAggregate() maps from the resolved field set:
$with = UserResource::eagerLoadMapFor(UserResource::resolveFields());
Relation constraints and limits - constrain() receives the relation itself, as a Laravel with() closure does, so
where(), local scopes, latest() and pivot clauses such as wherePivot() all apply. A constraint may filter and
order the relation but never bound it: a limit(), take() or skip() inside it that changes the relation's bound
throws a LogicException, as does a chaperone() inside it while columns are narrowed; declare that on the relation
method. Bound a to-many relation with limit() instead:
Relation::to('posts', PostResource::class)->limit(5)->constrain(fn ($query) => $query->latest()),
Each parent renders at most limit related records. The relation loads in one windowed query, ordered last by the
related key so the window is deterministic. A relation declaring no limit takes api-toolkit.resources.relation_limit
(API_TOOLKIT_RESOURCES_RELATION_LIMIT, default 25; 0 or null leaves it unbounded). A record whose relation was
cut lists the relation's response key in _truncated, and the exported schema documents the bound as maxItems.
HasMany, MorphMany, BelongsToMany and HasManyThrough are bounded in SQL unless their query has unions; any other
loaded collection, including one your own code loaded, is cut when it renders. A relation bounded in SQL keeps up to
limit + 1 rows on the model after the repository returns, the extra row being how a cut is detected; one with unions
keeps every row and is cut only in the response. A collection your application loaded below the bound never carries
_truncated, so its absence proves nothing about a relation you limited yourself.
A constraint shapes the rendered rows only: filters, $has, $hasnt and aggregates never run it. A row predicate
belongs in a relation method, which Eloquent applies everywhere:
public function publishedPosts(): HasMany { return $this->hasMany(Post::class)->where('published', true); } Relation::to('publishedPosts', PostResource::class)->alias('posts')->traversable(),
A relation loads once per path, so the schema compiler rejects a constrained relation any field makes traversable(),
fields over one relation where any is constrained or they render different resources, and a relation name holding a
dot. Fields over one relation may differ in fields(), and an accessor-only field may share any relation.
Pivot columns - pivot() renders columns of a many-to-many relation's pivot table on each child reached through
that relation, under a pivot key:
Relation::to('members', UserResource::class)->pivot('role', 'joined_at'),
The relation selects the columns itself, so the model's relation method needs no withPivot(). The key is always
pivot, whatever the relation's as() name, and each column is read through the pivot class's casts; a column the
loaded pivot does not carry is omitted. A relation your application loaded itself renders only what it carries. The
exported schema adds the typed pivot object to the relation's items and leaves the child's component untouched. When
clients create, update or delete the pivot rows, model the pivot as a resource of its own instead, such as a
memberships relation to a TeamMembership model that belongs to its user.
Field-set control at instantiation:
new UserResource($user, loadMissing: true); // eager-loads missing relations new UserResource($user, included: ['id', 'email']); // explicit field set new UserResource($user, excluded: ['email']); // field set minus exclusions (new UserResource($user))->withAll(); // all schema fields
Schema validation - api-toolkit.resources.validate_schemas validates every registered schema at boot. It is on
by default outside production (API_TOOLKIT_RESOURCES_VALIDATE_SCHEMAS=false turns it off) and off in production. The
api-toolkit:validate-schemas Artisan command runs the same validation regardless of the flag, so it can gate CI.
Validation checks that:
- every
filterable()andsortable()declaration names a column that exists. A computed field, or an accessor reading a different path, is caught from the schema alone; the rest is checked against the table's column listing. - every
needs()column exists on the table. - an ordered index leads with every
sortable()column, unless the field carriesindexed()orunindexed(). - an index on the connection serves every
searchable()declaration in the shape its strategy needs. - no declaration names a column configured as sensitive.
- every
limit()sits on a to-many relation rendered through a child resource, and every field over one relation shares one limit. - every
pivot()sits on aBelongsToManyorMorphToManyrelation rendered through a child resource with nopivotfield, and names columns its pivot table carries.
Every resource a filter reaches through a traversable() relation is validated too, once per related model, whether or
not the resource map lists it.
At boot, checks that read the connection are skipped where it cannot be read, such as a boot with no database or before migrations have run.
The command is stricter, because it gates deployment. It fails when the resource map is empty, and when any check
could not read the connection: each declaration it could not verify is listed under why its table's catalogue was
unreadable, whether the connection cannot be resolved, the catalogue cannot be read, or the table is not migrated.
Pass --allow-empty to accept an empty map, or --allow-unverified to accept declarations it could not verify;
neither flag lets a defect pass. A searchable declaration on a connection listed under
api-toolkit.search.unverified_connections is not reported, since that listing already waives its index proof. Boot
skips schema validation while this command runs, so the command reports everything itself.
Filters and sorts never read the index catalogue while they are served; only validation checks their index backing. Two
schema reads do sit on the request path, both cached in the shared store: search reads its index proof, and one read of
the table's column definitions serves column narrowing (api-toolkit.resources.narrow_columns), filter value checks, a
paginated read's search for the key column and a cursor-paginated sort's refusal of a nullable key.
Column narrowing - with api-toolkit.resources.narrow_columns on (the default), the base-table select is narrowed
to the columns the resolved fields read, plus the primary key, the soft-delete column, the parent keys of eager-loaded
relations and the order columns. A field reads the columns it declares through needs(), each of which must exist on
the table. A plain field without needs() is taken to read the column of its own key, and an unguarded, untransformed
Field::timestamp() or Field::date() the column it formats, but only when the table carries that column and the model
reads it without an accessor, a public instance property of the same name or a cast that could consult other attributes;
Eloquent's built-in cast types, enums that do not name their own caster, and the casts under
Illuminate\Database\Eloquent\Casts qualify. Any other field, such as one over an accessor or custom cast, or a
computed, row-guarded or transformed field, leaves the select unnarrowed until it declares needs().
A relation field rendered by a child resource or a string accessor reads only its parent-side key, so it narrows with
its parent. Each relation a repository read embeds selects the columns its child resource renders, plus its key, its
soft-delete column and the keys it and the relations beneath it match on; a child field it cannot prove leaves that
relation unnarrowed, as at the root. A relation stays unnarrowed when anything else may read its models: a field above
it that leaves its own level unnarrowed, such as a compute without needs() or a scalar over a model accessor, a raw or
accessor rendering of it, or an extras() path through it. A MorphTo, an unrecognised relation class and any graph
holding a chaperone() relation are never narrowed, and a select a constraint or repository chose is kept. A
withDefault() callback, model accessor or cast that reads an attribute the child does not render reads it as missing.
An incomplete needs() returns wrong data rather than failing. Call
Model::preventAccessingMissingAttributes(! app()->isProduction()) in a service provider to catch it outside
production: it throws on a read of an unselected attribute that is plain or carries a built-in or enum cast, though
not on one with an accessor or a class cast, nor on a raw $attributes[...] read inside a cast. Disable narrowing if
code reads attributes outside the rendered fields.
Repositories
Extend ApiRepository for a repository wired to the query parser, eager-load planning and pagination:
use SineMacula\ApiToolkit\Repositories\ApiRepository; class UserRepository extends ApiRepository { public function model(): string { return User::class; } }
withApiCriteria() applies the request's filters, sorts, eager loads and limit, and narrows the select to the
requested fields. It returns a copy and leaves the repository it was called on untouched, so run the read through the
returned value:
$users = $repository->withApiCriteria()->paginate();
Where the composition is conditional, keep the handle:
$scoped = $repository->withApiCriteria(); if ($caller->isExternal()) { $scoped = $scoped->scopeById($id); } $users = $scoped->paginate();
Working on the filtered set - withApiFilters() applies only the request's filters, search and trashed, under
the same allowlist and filter cost budget. order, limit, fields and aggregates are not applied, and only the
query parser checks them, so a bulk action sent the list screen's query string acts on every matching row. Persistent
criteria, repository scopes, global scopes and a model's $with still apply, and the last of withApiCriteria() and
withApiFilters() called on a handle wins. A terminal operation consumes the composition, so start each from its own
call:
$orders->withApiFilters()->update(['archived_at' => now()]); foreach ($orders->withApiFilters()->lazyById() as $order) { $order->notifyCustomer(); } $totals = $orders->withApiFilters()->query()->toBase() ->selectRaw('status, count(*) as total') ->groupBy('status') ->pluck('total', 'status');
Through paginate(), limit is still the page size; render pages through withApiCriteria().
Outside a request - criteria apply only under a parsed query: the one ParseApiQuery parsed, or a snapshot given
to ApiQuery::using(). Applied under none, as in a queued job, a console command or a route without the middleware,
they throw a LogicException rather than read the unfiltered table, and so do criteria composed under one query and
applied under another. Code with no client query runs under ApiQuery::using(new ApiQuerySnapshot([]), ...).
ApiQuery::snapshot() captures the fields, aggregates, filters, search, order and trashed the request
carried, as sent. It never carries page, limit, cursor or pagination, so a replayed read is not cut to one
page. A snapshot serialises with a job, and its parameters store as JSON for new ApiQuerySnapshot($row->query).
ApiQuery::using() validates the snapshot as it would a request, runs the callback under it and restores the previous
query:
ArchiveInvoices::make(new ArchiveInvoicesInput(ApiQuery::snapshot())) ->withContext(ServiceContext::fromRequest($request, EloquentActor::for($request->user()))) ->dispatch(); // ArchiveInvoices::handle() return ApiQuery::using($this->input->query, function (): int { $archived = 0; foreach ($this->invoices->withApiFilters()->lazyById() as $invoice) { $invoice->archive(); $archived++; } return $archived; });
- Read and render inside the callback. A
LazyCollectionkeeps its filters afterusing()returns, but a resource rendered later reads the restored query, and a resource resolves its fields once, so build it where it renders. - Work that changes which rows match iterates with
withApiFilters()->lazyById(), which ignores the client's order. Keyset iteration after a client order skips rows, and so does offsetlazy()as the set changes. allowsTrashed()and field guards see the worker's console request, which is not reconstructed, so a carriedtrashedthe worker's gate refuses, or a carried key a caller guard hides, fails the job.
Joins - every column the criteria, scopeById() and scopeByIds() emit is qualified with its table: the model's at
the root, the related model's inside a relation filter. A repository scope may therefore join. Scopes run after the
criteria, so a joining scope selects the base columns only where the criteria selected none
($query->getQuery()->columns ??= ['users.*']): joined columns would otherwise overwrite attributes, and select()
would discard the narrowed projection and any requested aggregates. Alias the joined table, never the base table:
Eloquent's relation filters and whereKey() name the base table, so from('users as u') is unsupported.
scopeById() and scopeByIds() match the model's key unless given a column.
Allowlist - only schema fields declared filterable(), sortable(), or traversable() are accepted, and any
other key is rejected with a validation error. There is no opt-out: a resource that declares nothing is queryable by
nothing. Each filter is checked as a (column, operator) pair against the declared capability, before any operator
handler runs or any SQL is issued.
Sensitive columns - the columns in api-toolkit.resources.sensitive_columns may never be declared filterable(),
sortable(), or searchable(), and schema validation rejects a resource that does. The default list covers the
stock Laravel and Fortify auth columns.
Index backing - schema validation checks that an index leads with each sortable() column. The column must be
the leading key; being second in a composite index does not count. Where the connection reports index kinds, only an
ordered kind counts, so a full-text or trigram index does not make a column sortable. The leading key must also hold
the column's own order, so a MySQL prefix index (name(20)), or a PostgreSQL index keyed with a pattern operator
class (text_pattern_ops) or a non-default collation, does not count for sorting. A MySQL prefix key still backs an
exact or prefix search, and a PostgreSQL pattern-class key still backs an exact search, but a PostgreSQL key with a
different collation backs neither. A connection that cannot be inspected skips the check rather than failing it.
Because pages end on the model key, a composite (column, key) index serves the whole order; the leading-column rule
is unchanged.
Two overrides cover what the catalogue cannot show:
indexed('users_lower_name_index')names the index behind the column, such as an expression or partial index. The name must exist on the table; what it covers is not checked.unindexed('the table is bounded at a few hundred rows')records a deliberate exemption. The reason is required.
A sortable aggregate or relation is never index-backed, so its sortable() carries the exemption's reason itself.
Random ordering - ?order=random is disabled by default. Enable it with
api-toolkit.repositories.allow_random_order (API_TOOLKIT_REPOSITORIES_ALLOW_RANDOM_ORDER=true); while disabled,
random is treated as an ordinary sort key and rejected like any undeclared column. relevance is always the
search relevance order, so a sortable() column named relevance cannot be ordered by; schema validation reports it.
Query cost caps - api-toolkit.query_cost bounds the filter document's size and nesting, the keys and value-list
items it dispatches, the sort keys and relation aggregates requested across every resource type, and how deep a request
pages. A request over a cap is rejected before any SQL is issued, with a 422 naming the parameter, the position within
it, the cap, the limit and the value supplied. Set a cap to 0 to disable it.
Writes - persist($model, $attributes) creates or updates the model from an array or collection of attributes.
Each key is written through Eloquent's setAttribute(), so casts, both mutator styles and JSON paths such as
options->theme apply. A key naming a relation is written through it: a BelongsTo from a model, its key or null,
a MorphTo from a model or null, and a BelongsToMany or MorphToMany from models or their keys, synced once the
model is saved. A key naming any other relation throws an InvalidArgumentException before any key is assigned, and
a key that is neither a column nor a mutator fails at save with the database's QueryException. A set mutator named
like a relation takes precedence over it. $fillable and $guarded are not applied, so pass only validated input.
The save and the syncs run in one transaction on the model's connection, so a sync that fails rolls the save back and
leaves the model instance stale; discard it. A save that a saving, creating or updating listener cancels syncs
nothing and returns false.
Cacheable trait - per-query caching for any ApiRepository subclass:
use SineMacula\Repositories\Concerns\Cacheable; class UserRepository extends ApiRepository { use Cacheable; protected int $cacheTtl = 3600; protected ?string $cacheStoreName = null; // uses app default protected bool $cacheReferenceTable = false; // whole-table reference mode }
A read is keyed by the SQL it runs: the root query with its global scopes applied, and each eager-loaded relation's
query with its constrain() closure and the related model's global scopes. ?trashed, tenant scopes and constraints
that read the authenticated user are therefore cached per value. A read with a MorphTo include, a relation class other
than the framework's own, an afterQuery() callback other than chaperone()'s, a callable withDefault() or eager
loads nested more than 16 levels deep runs uncached. Scopes and constraints run once more per read to build the key, so
they must be deterministic and free of side effects. paginate() is never cached. Writes, persist() included,
invalidate the table. Eager-loaded rows are cached with their parent, so a write to a related table leaves them stale
until the TTL. Call withoutCache() to bypass the cache for one read, or flushCache() to invalidate immediately.
With $cacheReferenceTable = true, the table is loaded once per global-scope variant and memoised in-process, and
get() and find() are served from that snapshot. A read with criteria, repository scopes or a column list other than
* runs a real query, and a write clears every variant. Use it only for small lookup tables that rarely change.
Deferrable trait - buffer inserts in memory and flush them as bulk INSERT statements at the lifecycle boundary
(RequestHandled, CommandFinished, JobAttempted, or JobTimedOut):
use SineMacula\ApiToolkit\Repositories\Concerns\Deferrable; class AuditRepository extends ApiRepository { use Deferrable; } $auditRepository->defer(['user_id' => 1, 'action' => 'login']);
Every queue job attempt flushes, including one that fails, times out or is released for a retry, so a retried job keeps the rows of its earlier attempts.
Each row goes to its model's connection, resolved when the row is deferred, so a later change of the default connection
does not redirect it. Timestamps follow the model: none when it has timestamps disabled, otherwise its own
CREATED_AT and UPDATED_AT columns in its date format, and a timestamp you pass is kept. Rows are inserted in
consecutive runs of one column set, so a row may leave out optional columns and they keep their database default.
Each connection flushes its tables in the order they joined the buffer, and a table keeps its place while it holds rows,
so defer a parent before the rows that reference it. An INSERT carries at most deferred_writes.chunk_size rows and
never more than 32766 bound values, so a wide table is written in smaller chunks.
Reaching deferred_writes.pool_limit flushes automatically, but never on a connection with an open transaction: those
rows wait for the next deferral outside a transaction or for the boundary flush, so rolling the transaction back does
not undo them. A flush that does run inside an open transaction joins it: flushWrites() called there, or a boundary
flush while an outer transaction is still open, such as a sync-queued job dispatched inside one. Each chunk then runs in
its own savepoint, or each table with deferred_writes.transactional, so a failure rolls back only that chunk or table
and the transaction stays usable. A deadlock or a lost connection ends the transaction instead, whatever on_failure
says: the flush rethrows the error as is, so DB::transaction() retries a deadlock, and drops every row buffered for
that connection. The retried closure defers its own rows again; rows deferred before the transaction opened are lost
with it.
api-toolkit.deferred_writes.on_failure picks what happens when a flush fails:
collect(default) - failed records are kept for the next flush. They do not count towardpool_limit, so they are retried when their connection next flushes automatically, or at the boundary, rather than on every deferral.throw- raises aWritePoolFlushException, for callers that flush explicitly.log- failed records are dropped. Use it only for disposable writes such as telemetry.
When a boundary flush fails under collect or throw, a WritePoolFlushException is reported through the exception
handler and a WritePoolFlushFailed event is dispatched. Under log the failure is logged as a warning instead, and
the event is still dispatched.
WritePool is a scoped singleton, so after a deferred write app(WritePool::class)->lastAutoFlushResult() returns the
outcome of the most recent automatic flush (null if none has run). Under collect and log this is the only
in-process signal that an auto-flush failed.
Concurrency
A versioned model lets a write refuse to overwrite a state its client never read. Implement Versioned with the
HasVersion trait and add the column:
use SineMacula\ApiToolkit\Concerns\HasVersion; use SineMacula\ApiToolkit\Contracts\Versioned; class Order extends Model implements Versioned { use HasVersion; } // Migration $table->unsignedBigInteger('version')->default(1);
Every insert stores 1 and every update stores the stored version plus one, quiet saves included; a clean save writes
nothing. const VERSION = 'revision' names another column. Saving a changed model loaded without its version throws a
LogicException. persist() advances the version once when only many-to-many relations change. A model can implement
Versioned itself to version by another column, but updated_at holds whole seconds, so two writes in one second share
a version.
A single-item ToolkitResource of a versioned model answers with a weak ETag, kept on narrowed ?fields reads;
collections and nested resources carry none. A write reads its row with findForUpdate() inside the transaction that
writes it, passing the request's If-Match:
// handle() of a service $order = $this->orders->findForUpdate($this->input->id, IfMatch::fromContext($this->context())); $this->orders->persist($order, $this->input->attributes);
findForUpdate() reads the row afresh under lockForUpdate(). A missing or scoped-out row is a 404 before the
precondition is checked, and an If-Match naming neither the current tag nor * throws PreconditionFailedException
(412, code 10114), which rolls the transaction back. A malformed If-Match matches nothing. It throws a
LogicException outside a transaction on the model's connection, or on a handle carrying withApiCriteria() or
withApiFilters(). ServiceContext::fromRequest() captures the field, so a queued run compares on the worker, where a
412 fails the job without a retry. A request without the field writes unconditionally: add RequireIfMatch to a route
group to answer a PUT, PATCH or DELETE without it with a 428 (code 10115), while other methods pass.
Tags compare weakly on both sides, where RFC 9110 compares If-Match strongly: the toolkit's tags are weak, and proxies
such as nginx weaken a strong tag they compress. A 412 carries no tag, so the client re-reads before retrying. The
toolkit never answers 304, and cache.headers:etag on these routes hashes the body, so it can answer 304 for a
changed ?include.
These writes do not advance the version: Model::query()->update(), upsert(), increment() and decrement(), a soft
delete(), DB::table(), Relation::touch(), and attach(), detach() or child saves outside persist(). Follow
them with markVersionChanged() and a save. On SQLite lockForUpdate() compiles to nothing, and the database write
lock turns a race into a busy error.
The export documents the ETag on the show, store and update responses of a versioned resource, a required If-Match
on the PUT, PATCH and DELETE operations behind RequireIfMatch, and an optional one where such an operation
documents a 412.
Filter-Operator Registry
The OperatorRegistry singleton maps tokens to FilterOperator handlers and the capabilities that admit each. Register
custom operators in a service provider's boot() method:
use SineMacula\ApiToolkit\Enums\Capability; use SineMacula\ApiToolkit\Repositories\Criteria\OperatorRegistry; class AppServiceProvider extends ServiceProvider { public function boot(OperatorRegistry $registry): void { $registry->register('$starts', new StartsWithOperator, Capability::RANGE); // Replace a registered operator's handler $registry->override('$contains', new StrictContainsOperator); } }
An operator is a class implementing SineMacula\ApiToolkit\Contracts\FilterOperator, or a closure with the same
signature, apply(Builder $query, string $column, mixed $value): void. A token is $ followed by a letter, then
letters, digits or underscores, and may not be $and, $or, $has, $hasnt or $scope. register() throws
InvalidArgumentException for any other token, or one already taken. $column arrives qualified by its table, such as
users.name; use it as given, or take Str::afterLast($column, '.') where the public name is needed.
A token is answered only on columns declaring one of the capabilities it was registered with, so $starts above is
refused with a 422 on an EXACT or OPAQUE column. The shipped tokens are registered with the defaults in
Query capabilities. override() replaces the handler of a registered token and keeps its
capabilities, so a replacement $contains still serves only DOCUMENT columns; it throws InvalidArgumentException
for an unregistered token. To change a token's capabilities, shipped or not, remove() it and register() it again.
The bare shorthand {"name":"Alice"} runs the registered $eq handler, so overriding $eq changes both spellings,
and removing it refuses both. A column whose capability admits no registered token refuses every filter on it.
An operator adds AND-joined predicates for one column; the applier owns the grouping, so an operator never chooses the
connective, and clauses an operator joins with OR are grouped on their own. One that refuses its operand throws a
ValidationException, and one that adds no clause is rejected with a 422. Operators are predicate-only: a scope
removed inside one leaks to the outer query.
An operator whose value has a fixed shape can implement SineMacula\ApiToolkit\Contracts\DeclaresValueShape and
return a FilterValueShape from valueShape(). Its value is then checked against that shape and the column's type,
and resolved as the built-in operators' values are, before apply() runs. A closure, or an operator without the
contract, receives the value as sent.
An operator that expands one value into a predicate per item should also implement
SineMacula\ApiToolkit\Contracts\ExpandsValueList and return the item count from countValueItems(). That count is
checked against the max_in_items cap, so a delimited string is bounded the same as an array. An operator without
the contract counts as one item per non-list value.
An unregistered token is rejected with a 422, under a column or on its own. The operators each column answers in the exported document and the generated docs are the registered tokens its capability admits, custom ones included.
Exception Handling
Register the exception handler in bootstrap/app.php. This is required: it registers both the JSON rendering and the
reporting filter, and without it handled exceptions reach every reporter:
use SineMacula\ApiToolkit\Exceptions\ApiExceptionHandler; ->withExceptions(function (Exceptions $exceptions): void { ApiExceptionHandler::handles($exceptions); })
Exceptions are mapped to ApiException subclasses and rendered as JSON error responses with the matching HTTP status.
api-toolkit.exceptions.render_strategy controls when JSON is rendered:
'auto'(default) - JSON unless the request does not expect JSON and debug mode is on.'always_json'- always JSON.'json_when_expected'- JSON only when the request expects it (Laravel'sexpectsJson(), e.g.Accept: application/json).
Every ApiException implements Symfony's HttpExceptionInterface, so one left to Laravel's renderer keeps its status
and headers, such as a maintenance 503 with its Retry-After.
Every error the toolkit renders shares one envelope:
{
"error": {
"status": 422,
"code": 10106,
"title": "Invalid Input",
"detail": "The information supplied was invalid",
"meta": {"email": ["The email field must be a valid email address."]}
}
}
detail is always present, empty when the code has no detail translation, and title is left out when none resolves.
meta is the exception's own meta, always an object, and is left out when empty. With
api-toolkit.exceptions.include_debug_info on (null follows app.debug), an error with an underlying exception adds
that exception's message, class, file, line and trace under error.debug, beside the meta rather than inside it.
detail is the code's catalogue text unless the exception is raised with its own, which the application translates:
throw new ConflictException(detail: __('invitations.already_invited'));
A policy denial's message and code are client-facing. Response::deny('Your trial has ended.', 'TRIAL_EXPIRED') renders
403 with that detail and meta.reason TRIAL_EXPIRED; an int code is carried as an int and a backed enum as its
value. A denial without a message keeps the catalogue detail, a denyWithStatus() denial keeps a known status, and one
rendered as a server error carries neither. denyAsNotFound() answers exactly as a missing record, while
denyAsNotFound('...') gives up that concealment for its message. abort() text is never the detail: throw an
ApiException with detail: instead.
A ValidationException raised with a standard client-error status other than 422, such as ->status(429), renders
with that status as HTTP_ERROR (10113), its field errors in meta. Any other status renders 422, and an
api-toolkit.exceptions.map target for ValidationException keeps its own status.
An ApiException declares the shape of its meta by implementing DefinesErrorMeta, and the exported document types
error.meta for its code with it. A subclass inherits the declaration with the code:
use SineMacula\ApiToolkit\Exceptions\ApiException; use SineMacula\ApiToolkit\OpenApi\Contracts\DefinesErrorMeta; final class SlotTakenException extends ApiException implements DefinesErrorMeta { public const ErrorCodeInterface CODE = AppErrorCode::SLOT_TAKEN; public const HttpStatus HTTP_STATUS = HttpStatus::CONFLICT; public static function metaSchema(): array { return [ 'type' => 'object', 'properties' => ['next_free' => ['type' => 'string', 'format' => 'date-time']], 'required' => ['next_free'], 'additionalProperties' => false, ]; } }
On a precognitive request a ValidationException renders as Laravel's {message, errors} body, which Precognition
clients read, rather than the error envelope.
Malformed UTF-8 in an error body, such as a client's key echoed in a validation message, is rendered as U+FFFD.
api-toolkit.exceptions.map renders an exception as an ApiException of your own:
use Illuminate\Http\Exceptions\ThrottleRequestsException; 'map' => [ ThrottleRequestsException::class => QuotaExceededException::class, ],
A key naming a built-in replaces it, any other is matched just before the first built-in mapping whose key it extends,
else after every built-in, and the first match wins. So ThrottleRequestsException wins over the built-in
TooManyRequestsHttpException it extends, and RuntimeException or Throwable catches only what no built-in maps.
The response keeps the headers of the exception it replaces.
Laravel converts these exceptions before the handler sees them, so a key naming one would never match and is rejected. Map the exception it becomes:
ModelNotFoundException,RecordNotFoundException,RecordsNotFoundExceptionandBackedEnumCaseNotFoundExceptionbecomeNotFoundHttpException.RequestExceptionInterface, such asSuspiciousOperationException, becomesBadRequestHttpException.AuthorizationExceptionbecomesAccessDeniedHttpException, or anHttpExceptionwith its status when it has one.OriginMismatchExceptionand Laravel'sTokenMismatchExceptionbecome anHttpExceptionwith403and419.
An HttpException carrying only a status, from abort() or a denial such as denyAsNotFound(), renders as the key
its status stands for, so a hidden record answers exactly as a missing one: 400 as BadRequestHttpException, 401 as
AuthenticationException, 403 as AccessDeniedHttpException, 404 as NotFoundHttpException, 405 as
MethodNotAllowedHttpException, 413 as PostTooLargeException, 429 as TooManyRequestsHttpException and 503 as
ServiceUnavailableHttpException. 419 renders as a token mismatch, any other status as a generic HTTP error, and an
unrecognised status such as 499 as a generic 500. A key naming HttpException or HttpExceptionInterface itself
takes precedence over all of these.
A target must be an instantiable ApiException with a CODE, a 4xx or 5xx status, and ApiException's own constructor
and getStatusCode(). The map is validated with every other setting, and an invalid one throws
InvalidConfigurationException. An invalid map or rendering setting found while rendering is reported, and Laravel
renders the exception itself. The map does not change reporting: silence a mapped exception with
$exceptions->dontReport().
Reporting - an ApiException is a handled response and is never reported or logged, whatever reporters are
registered and in whatever order. This matches Laravel's treatment of its own HTTP exceptions; use the response
status for request-level error rates.
- A deliberately thrown 5xx such as
ServiceUnavailableExceptionis handled too, so report its underlying cause where you catch it. - An
UnhandledExceptionthrown by hand is still reported. - Laravel's
Illuminate\Validation\UnauthorizedException(rendered as403) is not reported. - An exception implementing Symfony's
HttpExceptionInterfaceis not reported when its status is a recognised client error (one the handler renders as a4xx) or419, even when it does not extend Symfony'sHttpException. An unrecognised status such as499renders as a generic500and is reported. LockUnavailableException(lock contention, rendered as429) is never reported, with or withouthandles(). The429carries noRetry-AfterorX-RateLimit-*header, since how long the holder keeps the lock is unknown.
Other framework exceptions rendered as client errors, such as ModelNotFoundException (404) or
ValidationException (422), are kept out of reports by Laravel's own don't-report list.
An exception the handler does not map is unhandled. Laravel reports the original exception, with its own class and
trace and subject to its don't-report list, and the toolkit renders a generic 500 body, so with debug info disabled
its internals never reach the client.
The filter applies wherever Laravel reports, including queued jobs and console commands. It does not change retries,
failed-job storage or console output. Reporting is decided after any $exceptions->map() has been applied.
Request input is not attached to exception reports. Add the fields you want with your own $exceptions->context()
callback.
Controllers and Authorization
SineMacula\ApiToolkit\Http\Routing\Controller provides the response helpers: respondWithData() wraps an array in
data, and respondWithItem() and respondWithCollection() render a resource or a collection, or the export the
request negotiates. Each takes an optional HttpStatus and headers, which an export carries too.
AuthorizedController extends it with resource authorization. Declare the model with #[AuthorizesResource]:
use SineMacula\ApiToolkit\Http\Routing\Attributes\AuthorizesResource; use SineMacula\ApiToolkit\Http\Routing\AuthorizedController; #[AuthorizesResource(Order::class)] final class OrderController extends AuthorizedController {}
Each resource action is gated by a can: middleware for its policy ability:
| Action | Ability | Checked against |
|---|---|---|
index |
viewAny |
the model class |
store |
create |
the model class |
show |
view |
the bound model |
update |
update |
the bound model |
destroy |
delete |
the bound model |
restore |
restore |
the bound model |
forceDestroy |
forceDelete |
the bound model |
The bound model is read from the route parameter named after the model's snake-cased basename, so LedgerEntry reads
{ledger_entry}, as Route::apiResource('ledger-entries', ...) names it. parameter names another, used verbatim. A
parameter the route does not bind passes the gate no model, so the model's policy is never consulted. except lists
actions to leave ungated.
apiResource() does not route restore or forceDestroy. Route them with withTrashed(), or implicit binding answers
404 for a trashed row before the gate runs:
Route::post('orders/{order}/restore', [OrderController::class, 'restore'])->withTrashed(); Route::delete('orders/{order}/force', [OrderController::class, 'forceDestroy'])->withTrashed();
Any other routed action declares its own authorization, by default with Laravel's #[Authorize] on the method or the
class. ->can() on the route and a can: in its group count too:
use Illuminate\Routing\Attributes\Controllers\Authorize; #[Authorize('update', 'order')] public function publish(Order $order): JsonResponse
Two markers take an action out of the toolkit's gating:
#[CustomAuthorization]- the action authorizes itself, through$this->authorize(), a form request or a service. The export documents its403. Nothing verifies the check.#[SkipAuthorization]- the action is open to any caller past authentication, and adds no403to the export. A gate the route declares itself still runs.
An action that declares none of these, and is not in except, fails closed: the request is refused before the action
runs with a LogicException, reported and rendered as a 500. So is a resource action whose gate is removed with
withoutMiddleware('can'). The guard checks that a gate is declared, not that it is the right one, and only Laravel's
Authorize middleware counts: mark an action behind authorization middleware of your own #[CustomAuthorization].
The controller authorizes but does not authenticate: a guest reaches the gate, and a policy that does not accept guests
denies it with a 403. Put the routes behind auth to answer 401 first.
Middleware
The service provider registers the following middleware. Each can be disabled in api-toolkit.middleware:
maintenance_mode_swap- JSON503maintenance responses. URIs listed inapi-toolkit.maintenance_mode.exceptstay reachable.Retry-AfterandRefreshfromphp artisan down --retry/--refreshare forwarded; the response is always503, so--statusis ignored. Non-JSON requests that Laravel redirects (--redirect) or renders a template for (--render) are left alone.json_pretty_print- pretty-printed JSON when the request carries?pretty=true.throttle- API-friendly rate-limit responses; uses the Redis variant when the default cache store uses theredisdriver.
json_pretty_print takes 'scope' => 'global' (default, pushed to the global stack) or 'scope' => 'api' (appended
to the api middleware group only). The maintenance middleware replaces Laravel's in its existing position in the
global stack, after HandleCors, so maintenance responses still carry CORS headers (nothing is added if Laravel's has
been removed). throttle is registered as the router's throttle alias.
Rate-limit keys - throttle:{max},{minutes} keys each request by method, host, route and caller. The route is the
matched URI pattern, so /users/1 and /users/2 draw on one /users/{id} budget and walking ids does not escape the
limit. Authenticated requests are keyed by user identifier; guests by client IP ($request->ip()), as Laravel's stock
ThrottleRequests does, so one guest cannot exhaust the limit for every other guest. A named limiter
(throttle:{name}) uses the key its Limit defines.
Behind a proxy, load balancer, CDN or NAT, many callers can share one IP and be throttled together. Configure
Laravel's TrustProxies middleware so $request->ip() resolves the real client IP.
To key guests by something else, such as an API key, set api-toolkit.middleware.throttle.class to your own
middleware that uses ThrottleRequestsTrait and overrides resolveRequestSignature().
Schema Introspection and OpenAPI Export
The schema compiler resolves the filterable and sortable columns, traversable relations and field keys of any
registered resource without instantiating it. The database-schema introspector resolves model columns, their type and
nullability, and relations; ApiCriteria uses it internally and it can be injected:
use SineMacula\ApiToolkit\Contracts\SchemaIntrospectionProvider; public function __construct(private SchemaIntrospectionProvider $introspector) {}
An OpenAPI 3.1 document is generated from the resource map, the application's routes and the registered operators:
php artisan api-toolkit:export-openapi php artisan api-toolkit:export-openapi --output=openapi.json php artisan api-toolkit:export-openapi --audience=internal php artisan api-toolkit:export-openapi --all
Without options the default audience is written to api-toolkit.openapi.output. --audience exports one named
audience. --all exports every configured audience, each to its own file with the audience inserted before the
extension, so openapi.json becomes openapi.public.json and openapi.internal.json. Each file is staged beside its
target and moved into place only once all are staged, so one that cannot be staged replaces none of them. Component
schemas are listed by name, so reordering the resource map leaves a committed document unchanged.
Resources are optional: a route documented only through #[RequestSchema] and #[ResponseSchema] is exported with
an empty resource map. Operations are not. Every target audience is built before anything is written, and if any of
them has no operations (no route reaches it after the framework namespace exclusions and its own filters), the command
names each empty audience, writes nothing, and exits non-zero. Pass --allow-empty to write the documents anyway and
exit successfully:
php artisan api-toolkit:export-openapi --all --allow-empty
Routes handled under a framework or tooling namespace (api-toolkit.openapi.exclude.namespaces) and Route::fallback()
routes are left out. A closure in an application route file is documented, whether or not the routes are cached.
Responses are documented as JSON; the formats the resource exporter negotiates, such as CSV, are not listed.
List the hosts the API is served from under api-toolkit.openapi.servers, so interactive viewers call the API rather
than the docs host and generated clients get a base URL. Each entry is an OpenAPI Server Object with a url, an
optional description and optional variables, exported in order. An audience may set its own servers to replace
the list, or an empty list to export none. With none configured the document has no servers. An invalid entry fails
the export and is named:
'servers' => [ ['url' => 'https://api.example.com', 'description' => 'Production'], ['url' => 'https://api.staging.example.com', 'description' => 'Staging'], ],
A route on a domain, such as {account}.example.com, lists servers of its own: each of the audience's servers with its
host replaced by the domain, or https://<domain> when it has none, over http or https when the route is restricted
to one. Each domain parameter is a server variable rather than a path parameter, listing the values of a whereIn()
constraint or a bound string-backed enum and defaulting to the first, or else defaulting to its own name. A server that
uses a variable named like a domain parameter outside its host fails the export. One controller action routed on several
domains, with nothing else setting the routes apart, is one operation listing the servers of each.
Each resource becomes a component schema, and each documented route an operation carrying the query parameters that
action honours. Every queryable property carries an x-query-surface extension naming the key to send, the filter
capability and the operators it answers, whether an index backs its sort (with the recorded reason where none does), its
search strategy, and conditional on a filter or sort only some callers may use. The relations a filter may descend
through are listed on the schema itself, and its named scopes under x-scopes, each with its description, the JSON
Schema of its arguments and conditional where only some callers may invoke it. All of this is read from the same
compiled schema the request-time checks use, and each column's operators from the tokens the bound registry admits on
its capability, so the document cannot offer a column or an operator the request would reject. A column whose capability
admits no registered token is documented as answering no filter.
An index states its own filters and order. filters carries JSON content typed by the resource's
<Resource>Filters schema, which lists every key a filter may send and allows no other: each filterable column takes
its equality shorthand, where it answers $eq, or an object of the operators its capability admits, each value typed
from the column's enum cast or storage type; each traversable relation takes its governing resource's schema; and
$and, $or, $has, $hasnt and $scope appear where they apply. order is an array sent comma-separated
(style: form, explode: false) whose items list every key with each direction it accepts, relevance ascending only
where a field is searchable and random while random order is enabled. search is listed only where a field is
searchable. A client must send filters as JSON and order comma-separated, as declared; some generated clients need a
custom query serializer for the JSON one.
A filter or order the schemas reject is refused, though the server also accepts other spellings, such as a digit-string
integer or a date for a date-time. One they accept can still be refused: over a query cost cap, on a key the caller is
not admitted to, with a repeated order key, with random, aggregate, relation or nullable keys under cursor pagination,
with relevance and no search term, by a polymorphic relation body or the value of an operator declaring no shape (both
left untyped), with an integer written as 1.0, a string carrying a NUL character, a single-precision value too small
to store, a scope argument refused by a rule or parameter type the schema cannot express, or on a resource bound to
several models that differ in a column's type or a relation.
A resource schema requires only what every response carries: _type, and each fixed field read straight from its
column, with no guard or transformer. Its x-default-fields extension lists the fields returned when a request names
none for that type and no parent relation pins them: the declared $default fields, then the fixed ones.
A field read straight from its column is typed from the value Eloquent returns: by the model's cast when it has one,
else by the column type. Date casts and the model's timestamps are a date-time, a decimal:N cast a string, and any
other date-time or time column the driver's string. A value with no fixed shape is marked x-undocumented: an array,
json, collection or object cast, a cast class other than an enum, AsStringable or AsUri, and an uncast
decimal, binary or JSON column. On PostgreSQL before PHP 8.4, a float column is a string, as the driver returns it.
Declare the field's openapi() schema to document any of these. A declaration naming no type, format, enum or
nullability, such as ->openapi()->example('Ada'), keeps the inferred schema and adds its example and description.
A relation rendered through a child resource is typed from its Eloquent relation: a to-many relation as an array of the
related schema, and a to-one relation as the related schema or null, since it renders null when the related row is
absent. A to-one relation with a default model from withDefault() never does, so it is the related schema alone. A
relation's openapi() declaration replaces the inferred schema and its maxItems, and a transformed relation without
one is left undocumented; either still lists the relation in _truncated when it is cut.
Every operation also lists the errors it can return, derived from the route: an unauthenticated request behind auth
middleware, a denied one behind an authorization check (a can: gate, an #[Authorize] attribute, an
AuthorizedController resource action, or an action marked #[CustomAuthorization]), a missing record when the route
binds a parameter, a validation failure when the operation accepts a request body or the toolkit's query parameters, a
refusal behind a rate limit, a missing If-Match on a PUT, PATCH or DELETE behind RequireIfMatch, and an
unhandled exception always. Each is documented as the exception map renders it: by default a 401, 403, 404, 422,
428, 429 and 500. A list operation also documents the query cost refusal under 422 while any query cost cap is
enabled. The unhandled exception is looked up as a Throwable, so a Throwable key changes it and a narrower catch-all
such as RuntimeException does not. A denial with a status of its own is documented only where the route already lists
the error that status stands for, as a path with parameters does for denyAsNotFound(). Middleware is read as the
router resolves it, so a guard or limit applied through a group counts and one removed with withoutMiddleware() does
not.
Each ApiException subclass named in the @throws tags of the action, or of the handle() (else __invoke()) of any
middleware the route runs, read as the router resolves it, is added under its status too; other throwables in those tags
are ignored. Global middleware is not read, nor is RequireIfMatch, which is documented from its route fact, and a
middleware the container rebinds is read from the class the route names. Class names in @throws resolve as PHP would
in the file declaring the method, so imported, aliased, same-namespace and fully qualified names all work, and a union
such as @throws A|B names both. Each error code is documented once, as the components.examples entry Error<code>
(such as Error10107) carrying the code's catalogue title and detail, and as the components.schemas envelope
Error<code>, which pins error.code and types error.meta as the code's exception declares it, else as an open
object. InvalidInputException declares its field errors and QueryTooExpensiveException the limit it exceeded. Every
error response references the examples of its exceptions, and its schema is the envelope of its code, or a oneOf of
the envelopes where the status carries several codes. The export fails when a documented exception has no CODE, which
the handler cannot render, when its code is not in the error catalogue (add its namespace to
api-toolkit.openapi.exception_namespaces), or when it shares a code with an exception answering another status or
declaring another meta.
Each path parameter is typed from what the router enforces on its segment. A where constraint comes first:
whereUuid() exports a uuid, whereNumber() a non-negative integer, whereIn() or a plain alternation such as
draft|published an enum, and any other pattern its anchored pattern. Without one, the parameter takes the
string-backed enum or Eloquent model the action binds: the enum's component, or the type of the column the model is
looked up by, which is its route key or the field a {post:slug} segment names. The openapi() schema of a resource
field that emits that column unchanged, with no model accessor, takes precedence over the column type. A HasUuids or
HasUlids key is typed without a database, unless the model replaces the trait's isValidUniqueId(). An explicit
Route::bind() binder, an overridden resolveRouteBinding(), a model bound in the container or a key cast to a pure
enum leaves the parameter a string. A constraint outside the syntax PHP and JavaScript read alike is not exported, so
the binding types the parameter, or it stays a string: \d, \w and an unescaped . match more characters in PHP, so
write [0-9] or whereNumber() to export the constraint.
A route with optional parameters exports a path for each URL it matches, every parameter in it required:
reports/{period?} exports /reports and /reports/{period}. As the router matches it, only the trailing run of
optional parameters can be left out, so {locale?}/reports exports /{locale}/reports alone. A shorter path without
parameters documents a missing record only when the route's domain has parameters or a route default fills one it leaves
out. Any shorter path is left to another route exporting it under the same method.
Every enum the document references, through a model cast, a request field validated by Rule::enum() or PureEnum, or
a string-backed enum bound to a route parameter, becomes one named component listing its values under enum: the
backing values of a backed enum, or the lowercase case names of a pure enum. Fields reference the component, except a
field narrowed by only() or except(), which lists its accepted values inline (an empty list when it accepts none).
A request field's presence rules shape its object's schema:
- A
confirmedfield documents its confirmation field (<field>_confirmation, or the oneconfirmed:names), required always when the field is required and throughdependentRequiredwhen it is optional. The confirmation field names the field it repeats inx-confirms, unless it confirms several. required_with,required_with_all,required_withoutandrequired_without_allare expressed withdependentRequired,if/thenandanyOf. They reference only fields declared in the same object or array item: any other name is left out, and a_allrule naming one is dropped.- A field with an
excluderule requires nothing, since the validator may skip it. - A present but empty value, such as
null,""or[], counts as missing to these rules but as sent to the schema.
A route outside the resource pipeline documents its success body with #[ResponseSchema] on the action. Name a
registered resource to reference its component, or a class implementing DefinesSchema to export the JSON Schema its
schema() returns as a component named after the class, or after its #[SchemaName]. The class is defined once and
referenced wherever it is named. collection: true documents a collection of the shape: a length-aware page with its
Total-Count header, a cursor page or an unpaginated list. Name several classes to document a response that may be any
one of them, exported as a oneOf of their references under data (or under each item of a collection). Give each
member an object schema (type exactly object) with a required property holding its own string const, such as a
status. When every member pins the same property to a distinct value, the oneOf carries a discriminator mapping
each value to its member. Resources pin _type, so a union of resources with distinct types is discriminated on it. If
any named class is neither a registered resource nor a DefinesSchema, the body is left undocumented. #[SchemaName]
on a resource, enum or DefinesSchema sets its component name, and two classes deriving one name fail the export. An
enum named as a shape fails the export when a registered resource's field or a documented request rule also uses the
enum.
On a resource controller's index, show, store, update or destroy, declaring the controller's own resource
(as a collection on index, a single item elsewhere) changes nothing: the action keeps its full resource
documentation, including an index's query parameters, both pagination shapes and the Total-Count header. Any other
declared body replaces the resource body. Such an action keeps its status, headers, request body, tag and error
responses, but lists none of the resource's query parameters:
use SineMacula\ApiToolkit\OpenApi\Attributes\ResponseSchema; use SineMacula\ApiToolkit\OpenApi\Contracts\DefinesSchema; final class PendingSignIn implements DefinesSchema { public static function schema(): array { return [ 'type' => 'object', 'properties' => [ 'status' => ['const' => 'pending'], 'choices' => ['type' => 'array', 'items' => ['type' => 'string']], ], 'required' => ['status', 'choices'], ]; } } #[ResponseSchema(UserResource::class)] public function me(): JsonResponse {} #[ResponseSchema(UserResource::class, collection: true)] public function team(): JsonResponse {} #[ResponseSchema([SignedIn::class, PendingSignIn::class])] public function signIn(): JsonResponse {}
Document response headers with #[ResponseHeader], repeated once per header:
- On an action, it adds the header to the success response.
- On a controller class, it adds it to the success response of every action the controller handles; an action's own declaration wins.
- On an
ApiExceptionsubclass, it documents a header the exception may set, added to the error response of every action whose@throwstags, or those of its route middleware, name it, or whose route facts the handler answers with it. A route fact also documents the headers of its built-in target, which the handler forwards whatever the configured target, so a remapped rate limit keepsRetry-AfterandX-RateLimit-*. Subclasses inherit their parents' headers, and exceptions sharing a status contribute every header they declare, the first declaration of a name winning.
The schema defaults to a string and the description is optional. A header the export already emits, such as a
collection's Total-Count, cannot be declared again: the export fails. The toolkit's TooManyRequestsException
documents the Retry-After and X-RateLimit-* headers, and MaintenanceModeException the Retry-After and
Refresh headers:
use SineMacula\ApiToolkit\Exceptions\ApiException; use SineMacula\ApiToolkit\OpenApi\Attributes\ResponseHeader; #[ResponseSchema(SignedIn::class)] #[ResponseHeader('Set-Cookie', 'The refresh token, HttpOnly, Secure, SameSite=Strict.')] public function signIn(): JsonResponse {} #[ResponseHeader('Retry-After', 'The number of seconds to wait before retrying.', ['type' => 'integer'])] final class QuotaExceededException extends ApiException { public const ErrorCodeInterface CODE = AppErrorCode::QUOTA_EXCEEDED; public const HttpStatus HTTP_STATUS = HttpStatus::TOO_MANY_REQUESTS; }
The success status is derived from the action name: 201 for store, 204 with no body for destroy, and 200
otherwise. Declare #[ResponseStatus] on an action that answers otherwise. It accepts success statuses only. 204
and 205 have no body, so declaring a #[ResponseSchema] beside either fails the export. Any other status keeps the
body the action would otherwise document, and a destroy declaring one gains its #[ResponseSchema] body or the
undocumented envelope. Declared headers attach to the declared status:
use SineMacula\ApiToolkit\OpenApi\Attributes\ResponseStatus; use SineMacula\Http\Enums\HttpStatus; #[ResponseStatus(HttpStatus::NO_CONTENT)] public function update(ChangePasswordRequest $request): Response {} #[ResponseSchema(ExportQueued::class)] #[ResponseStatus(HttpStatus::ACCEPTED)] public function export(): JsonResponse {}
api-toolkit:docs:generate writes the generated reference sections into the Markdown docs directory
(api-toolkit.openapi.docs_path) that is assembled into the document's description: the error catalogue, the enum
reference, and the query surface reference, which tables each resource's queryable columns alongside the request
bounds, and names the resource governing each traversable relation. The surface reference is written per audience,
under audiences/<audience>/, so it only reaches documents that already carry the resource's schema, and the
resources their filters reach through a relation that is not a MorphTo:
php artisan api-toolkit:docs:generate
Examples
Every JSON request body and success body carries generated examples. A value comes from the schema node's examples,
const, enum, format and type, within its bounds; nothing is random or guessed from a field name. A request
example sends every field that can be sent, so its presence rules hold, and a confirmation repeats the field it
confirms. A response example holds each resource's required and default fields. A body that may take several shapes,
such as an index's two pagination shapes or a #[ResponseSchema] naming several classes, carries one example per
shape, named by its title or component. A multipart body takes none.
Give a value where the exporter finds none, such as for a field with a regex rule, or where a realistic one reads
better. The structure around it stays generated:
->openapi()->example()on a resource field, exported underexamples.fieldExamples()on a rules source implementingDefinesFieldExamples, keyed by rules key. A value at a container key, such asitems, is used as that whole subtree. A key naming no field, or a prohibited one, fails the export.- An
exampleskeyword anywhere in aDefinesSchema'sschema().
use SineMacula\ApiToolkit\OpenApi\Contracts\DefinesFieldExamples; use SineMacula\ApiToolkit\Services\Contracts\DefinesInputSchema; final class RedeemVoucher implements DefinesFieldExamples, DefinesInputSchema { public static function rules(): array { return [ 'code' => ['required', 'string', 'regex:/^[A-Z]{3}-[0-9]{4}$/'], 'items' => ['required', 'array'], 'items.*.sku' => ['required', 'string'], ]; } public static function fieldExamples(): array { return ['code' => 'ABC-1234', 'items' => [['sku' => 'TEE-M'], ['sku' => 'CAP-L']]]; } }
A #[ResponseSchema] body naming a DefinesSchema shape, alone or in a oneOf, may show hand-written examples
instead. #[ResponseExample] names the success status, the example's name and a JSON file holding the body as sent,
envelope included. The file is relative to <docs_path>/examples/, and an audiences/<name>/examples/ copy replaces it
for that audience. Declared examples replace the generated ones, in declaration order. Every other body is derived, so
an example declared on one fails the export, as does one naming another status or a status without a body, a name
declared twice, and an example file no exported operation names. A oneOf example must match exactly one shape:
use SineMacula\ApiToolkit\OpenApi\Attributes\ResponseExample; #[ResponseSchema([SignedIn::class, MfaChallenge::class])] #[ResponseExample(HttpStatus::OK, 'signed-in', 'auth/signed-in.json')] #[ResponseExample(HttpStatus::OK, 'mfa-challenge', 'auth/mfa-challenge.json')] public function signIn(): JsonResponse {}
Every example the document carries, generated, declared or an error example, is validated against the schema beside it,
offline. A mismatch fails the export, naming the example and where it fails, and so does a required field the exporter
finds no value for. A body needing an undocumented field, such as an uncast column exported without a database, gets no
example, and the export command warns, naming the operation and the field; a wholly undocumented body gets none
silently. A date_format field is a date or date-time only when every format it lists renders that form, and its
example is rendered in its own format.
Operation Ids, Summaries and Descriptions
Set api-toolkit.openapi.operation_ids to true to export an operationId on every operation. The id is the first
of:
- the
idof the action's#[Operation]; - the route name, unless it is empty,
'0', ends in., or containsgenerated::, the markerroute:cachenames unnamed routes with. A name ending in.is the bare prefix of a->name('admin.')group and is never an id; - for a controller, its basename without
Controllerand the action, kebab-cased with acronyms kept whole:APIKeyController@showAllgivesapi-key.show-all, and an invokableAPIKeyControllergivesapi-key; - for a closure, the method and the path segments without braces:
GET /users/{user}/avatargivesget.users.user.avatar.
A route with several methods keeps the id on its first method and appends each later method to it, in the order the
route declares them: a PUT|PATCH route named users.update exports users.update and users.update.patch, so
reordering a match() changes its ids. An id taken from the method and path already starts with its method, and is not
suffixed. The paths of a route with optional parameters share its id: the shortest keeps it and each longer path appends
the optional parameters it adds, ahead of any method, so a GET|POST route named reports.show on reports/{period?}
exports reports.show, reports.show.post, reports.show.period and reports.show.period.post. Ids must be unique
across every audience; two operations claiming one id fail the export, naming both.
#[Operation] declares an action's id, its summary, or both. The summary is exported whether or not ids are on:
use SineMacula\ApiToolkit\OpenApi\Attributes\Operation; #[Operation(summary: 'Update a user')] public function update(UpdateUserRequest $request): JsonResponse {}
An operation's description is read from <docs_path>/operations/<id>.md, and audiences/<name>/operations/<id>.md
replaces it for that audience; an empty file blanks it. A later method without its own file takes the first method's, so
users.update.md describes both methods unless users.update.patch.md exists. Every path of a route with optional
parameters falls back the same way to its shortest path's first method, unless its ids are taken from the method and
path. Filenames are matched byte for byte, so ids differing only in case cannot share a case-insensitive filesystem.
Files and directories whose names start with . are ignored. Every export checks the files of every audience, and fails
on an operation file while ids are off, on one matching no exported operation, and on one under the directory of an
audience that is not configured.
Tags
An operation's tag is the action's #[Tag], else its controller's, else the resource's schema name. Failing those, a
controller route takes the controller basename without Controller, and a closure the first URI segment that is not a
parameter, else default.
The document carries a top-level tags list once api-toolkit.openapi.tags names a tag or a tags/ directory, shared
or an audience's, holds a file. It lists the tags the audience's operations use: those named in
api-toolkit.openapi.tags first, in that order, then the rest in natural, case-insensitive order:
'tags' => ['User', 'Article'],
A tag's description is read from <docs_path>/tags/<Tag>.md, with the same per-audience override. In a filename,
%, /, \, :, *, ?, ", <, >, |, control characters and a leading . are written as %XX, so
Admin/Users reads tags/Admin%2FUsers.md; everything else, spaces included, is kept. A configured tag that no
audience uses fails the export, as does a tag file that matches no tag, under the same rules as operation files.
Metadata Invalidation
Schema metadata (column definitions, index catalogues, relation lookups and the model-to-resource map) is cached in the application's cache store and shared by every process. The Octane and queue boundary flushes reset only each worker's per-operation state, so a schema or mapping change needs the shared entries retired explicitly. Every metadata key is stored under a generation held in the same store; replacing the generation makes every earlier entry unreachable in every process at once. Column definitions that read empty, as they do before their table exists, are never stored.
Under Octane the boundary is the end of every request, task and tick; on a queue worker it is the end of every job
attempt, including one that fails or is released for a retry. It drops the memoised generation, the per-operation
index proofs, the in-memory column definitions and index catalogues, the field and eager-load memos
and the query parser's state. The compiled schemas, search plans, field-to-column maps and cast reflections come from
code alone, so they live for the worker and are rebuilt only when it restarts; reload Octane and queue workers on
every deploy. An application that runs its own reset can call CacheManager::flush(); a second reset is harmless.
Entries are stored as arrays and scalars, never objects, so the cache works under Laravel's default
cache.serializable_classes => false. An entry that does not read back in the expected shape is treated as a miss
and overwritten.
The metadata cache is optional. If a cache store operation throws, the failure is reported as a
MetadataCacheUnavailableException and the store is bypassed for api-toolkit.cache.retry_after seconds
(API_TOOLKIT_CACHE_RETRY_AFTER, default 30); metadata is computed without the cache and the request is still
served. A write the store rejects is reported at most once a window but bypasses nothing, so the store keeps serving
its warm entries; the null driver's rejections are not reported. With retry_after set to 0, every failed call is
retried and reported. The windows are per process, so an Octane or queue worker reports an outage once a window.
Under PHP-FPM nothing outlives a request, so an outage is reported once per request; throttle it with a lottery, since
a rate limit backed by the same unavailable store cannot:
use Illuminate\Support\Lottery; use SineMacula\ApiToolkit\Exceptions\MetadataCacheUnavailableException; $exceptions->throttle(fn (Throwable $e) => $e instanceof MetadataCacheUnavailableException ? Lottery::odds(1, 100) : null);
The bypass limits how many store calls fail, not how long each takes, so give the cache's Redis connection a short
timeout and read_timeout.
Schema entries are keyed by the schema the connection actually reads (its name, database, table prefix, Postgres search path, database user and configured server), so a tenancy switcher that repoints one connection name reads each tenant's schema separately, provided it purges the connection when it switches. Relation lookups and the resource map come from code and are shared across tenants. Where each tenant has its own cache prefix, each has its own generation, so invalidate per tenant.
The generation is replaced automatically when a migration run finishes or loads a stored schema dump. A run with nothing
to migrate and no dump to load, or a --pretend run, leaves the metadata warm. If the cache store cannot be written,
the hook logs a warning instead of failing the migration. Set API_TOOLKIT_LIFECYCLE_MIGRATIONS=false to turn the hook
off.
The hook is not enough on its own: migrations run before the new release takes traffic, so workers still on the old code can refill the new generation with their resource mappings and relation lookups. Run this on every deploy, after the new release is live:
php artisan api-toolkit:invalidate-metadata
It exits with a failure if the cache store rejects the new generation.
The build should run php artisan optimize, which compiles the resource map along with the framework's caches.
Reload PHP workers after a rebuild, since OPcache with validate_timestamps=0 keeps serving the previous file.
Entries under a retired generation are no longer read but stay in the store until it evicts or clears them, so each invalidation leaves at most one stale copy behind.
Services
A service is generic over its input and output. Declare both with @extends Service<TInput, TOutput> and
$this->input is typed as TInput in every hook. The input is readonly, so a subclass with its own constructor
passes it to parent::__construct($input) rather than redeclaring or assigning $input. make() resolves the service
from the container and hands the input to the first constructor parameter whose class, interface or union type accepts
it, whatever its name; a constructor that cannot take it throws a LogicException.
/** * @extends Service<SignInPayload, User> */ final class SignIn extends Service { protected function handle(): mixed { return User::query()->where('email', $this->input->email)->firstOrFail(); } } $user = SignIn::make($payload)->runOrFail();
Payloads in Actions
Type-hint the payload on the action. It is validated and hydrated from the request before the action runs, a failure
renders as a 422, and the exported request body is documented from its rules(). Outside HTTP, build it with
from() and an array.
public function signIn(SignInPayload $payload): UserResource { return new UserResource(SignIn::make($payload)->runOrFail()); } SignInPayload::from(['email' => 'a@example.com', 'password' => 'secret']);
A payload built from the request reads the JSON or form body and the uploaded files, never the query string, so a
required field sent only in the URL is reported missing. Build one from the query string with
from($request->query->all()).
Form, multipart and query string values arrive as strings, so an int, float or bool property is cast from any
value the integer, numeric, boolean, accepted or declined rule accepts. A property its rules let be absent
needs a default; without one, from() throws a LogicException naming it.
toArray() of a payload built by from() returns only the validated fields the input sent, an explicit null
included, so a partial update persists them without resetting the rest. A payload built with new includes its
defaults:
UpdateUserPayload::from(['email' => 'new@example.com'])->toArray(); // ['email' => 'new@example.com']
messages() and attributes() customise the messages and field names, as on a FormRequest. A status.enum entry
rewords an enum failure on status, whether Rule::enum() or the cast refused it:
public static function messages(): array { return ['email.unique' => 'That email is already registered.', 'status.enum' => 'Choose a listed status.']; } public static function attributes(): array { return ['client_name' => 'organisation name']; }
For Precognition, add Laravel's HandlePrecognitiveRequests middleware to the route. A Precognition-Validate-Only
header validates only the fields it names, and a request that passes answers 204 without running the action. A
precognitive 422 is Laravel's {message, errors} body, which Precognition clients read, rather than the error
envelope; this holds for a FormRequest too. Under Precognition-Validate-Only the first input to pass ends the request
before a second is validated, so an action should take one validated input.
Running a Service
runOrFail() returns the output (typed as TOutput) or throws, and is the usual choice in a controller: the failure
reaches the application's exception handler. A failed result with no captured exception throws a
ServiceFailedException, so a failure never comes back as output.
run() never throws for a business failure. It returns a ServiceResult for callers that branch on the outcome:
$result = SignIn::make($payload)->run(); if ($result->failed()) { // $result->exception is the captured failure, or null when none was thrown return response()->json(['message' => 'The credentials are invalid.'], 401); } $user = $result->output();
runOrFail() is run()->throw()->output(). Both use the context given through withContext() and fire the same
lifecycle events.
A queued ServiceCompleted or ServiceFailed listener receives the result's exception and each side-effect error as a
SerializedException, which keeps its message, code, file, line and previous chain and names its class through
originalClass(), since an exception's trace and state, such as a validator, may not serialise.
dispatch() runs authorize() and validate(), then queues the service. A refusal throws from dispatch(), so an
HTTP action answers 403 or 422 and nothing is queued. The worker runs the whole lifecycle again with a QUEUE
context, since state can change before the job runs, so both hooks must be repeatable. At dispatch they see the context
given through withContext(), or an INTERNAL one. dispatch() returns Laravel's PendingDispatch, so onQueue(),
onConnection(), delay() and afterCommit() apply per call.
A failed attempt fires onFailure() and ServiceFailed and fails the job with the captured exception, which the worker
retries per --tries and --backoff. An AuthorizationException, ValidationException or
PreconditionFailedException fails the job at once and is not retried. Once the queue gives up on the job, because its
attempts ran out, a refusal failed it or its last attempt timed out, it calls onFinalFailure() with the exception. A
timed-out attempt fires no other hook, as the worker kills itself mid-run. Laravel deletes the job first, so
onFinalFailure() runs at most once and must be idempotent; run() and runOrFail() never call it. On the sync
connection there is no worker to retry, so the failure is thrown to the dispatching code when it releases the returned
PendingDispatch, at the end of the statement unless it is kept in a variable, or when the transaction commits for a
job queued after commit.
Queued Services
Declare how a service is queued with Laravel's queue attributes and markers:
#[Queue('reports')] #[Timeout(900)] #[Tries(1)] final class ExportLedger extends Service implements ShouldBeEncrypted { // ... }
#[Connection], #[Queue], #[Delay], #[Tries], #[Timeout], #[Backoff], #[MaxExceptions], #[FailOnTimeout],
#[CountCrashesAsExceptions] and ShouldQueueAfterCommit apply, and an undeclared setting keeps the worker's. The
queue and connection come from the per-call onQueue() and onConnection(), then the service's attributes, then
Queue::route() for the service class, a parent, an interface or a trait, then Queue::route(ServiceJob::class), then
the connection's default. Horizon and the failed job store list the job under the service's class.
The job is encrypted when the service implements ShouldBeEncrypted or its input is a Payload with a
#[\SensitiveParameter] parameter, so the secret is never stored in plain text in the queue or the failed job store.
toJob() builds the job without the pre-flight, for Bus::batch(), Bus::chain() and Bus::dispatchAfterResponse().
A refusal fails its job, which cancels a batch that does not allowFailures(), and the batch's later jobs are skipped.
During a batched run, $this->context()->batchId holds the batch id for Bus::findBatch():
Bus::batch([ExportLedger::make($january)->by($actor)->toJob(), ExportLedger::make($february)->by($actor)->toJob()]) ->name('ledger-export') ->withOption('actor', $actor->actorIdentifier()) ->onQueue('reports') ->dispatch();
Laravel decides three things the toolkit leaves as they are:
- A batch pushes its jobs on its own
onQueue()andonConnection(), so set a batched service's queue on the batch. - In a chain, including one inside a batch, each later service keeps its declared or routed queue and connection over the chain's, so a worker must consume that queue.
- A chain serialises its later services into the first job and encrypts only that job, so a sensitive service later in a chain is encrypted in transit only when every job before it is.
Transactions
$transactional (default true) wraps the concerns, prepare() and handle() in a database transaction, and
afterCommit() runs once the outermost transaction has committed. The transaction runs once: a deadlock or other
concurrency error rolls it back and fails the run, firing onFailure() and ServiceFailed.
$transactionAttempts (default 1) lets a top-level run retry a concurrency error, such as a deadlock, a PostgreSQL
serialization failure or a MySQL lock wait timeout. Each retry re-runs the concerns, prepare() and handle() in full,
but the rollback resets only the database: a model saved by the failed attempt still looks saved, so the retry can skip
its write and report success. A service nested in another transaction never retries; it fails with a
DeadlockException. On a transactional service a value below 1 fails the run with a LogicException. A service that
sets it above 1 must:
- Load every model it writes inside the transaction, in
prepare()orhandle(), from keys in the input (Order::query()->lockForUpdate()->findOrFail($this->input->orderId)). Never write a model carried by the input or loaded inauthorize()orvalidate(). - Keep no attempt-local state on the service, its concerns (which may be container singletons) or stateful observers,
or reset it before its first use in each attempt. Concerns run before
prepare(), so resetting inprepare()only covers state first used there or inhandle(). - Do non-database work in
afterCommit(), or register it inside the attempt withDB::afterCommit()or an after-commit job. Laravel discards the callbacks a rolled-back attempt registered, so never guard registration with a flag that outlives the attempt.
final class ShipOrder extends Service { protected int $transactionAttempts = 3; protected function handle(): mixed { $order = Order::query()->lockForUpdate()->findOrFail($this->input->orderId); $order->update(['status' => 'shipped']); DB::afterCommit(fn () => OrderShipped::dispatch($order)); return $order; } }
For any other service, retry the call rather than the transaction: run Service::make(...)->run() again with fresh
input, or dispatch() it and let the worker retry per --tries or the service's #[Tries] and #[Backoff]. Each
worker attempt starts from the dispatch-time input rather than the previous attempt's models, but models nested in an
ArrayInput or Payload are not re-fetched, so pass keys and keep external effects idempotent.
A service run inside a caller's transaction (another service, a DB::transaction() or a job that opens one) commits
only a savepoint, so its lock, afterCommit() and ServiceCompleted wait for the outermost commit, and a rollback
releases the lock and runs neither. A $transactional = false service behaves the same. The result run() returns
there has empty sideEffectErrors(); errors from afterCommit() are reported and carried on the ServiceCompleted
result. A ServiceCompleted or ServiceFailed listener exception is reported, never thrown.
The lock is held for the rest of the caller's transaction, so $lockExpiration must cover it, and a second run with the
same lock key inside it fails with LockUnavailableException. On the database cache store on MySQL or PostgreSQL,
give locks a lock_connection of their own: a lock row written on the caller's connection stays uncommitted, so a
competing run blocks until the caller's transaction ends instead of failing with LockUnavailableException. Queue
follow-up work from afterCommit(), which runs once, after the attempt that commits, and never after a rollback.
dispatch() from handle() pushes at once unless the queue connection sets after_commit or the service implements
ShouldQueueAfterCommit, so the job can run for a write that never commits. Transactions interleaved on two connections
are not supported: the deferred work attaches to the most recent open transaction on any connection.
Reading the Run Context
During a run, $this->context() returns the ServiceContext in use: the one given through withContext(), the
INTERNAL context run() builds when none was given, or the QUEUE context rebuilt on the worker. Every hook,
concerns() and lockId() see the same instance, and the ServiceCompleted and ServiceFailed events report it.
During a run actor() returns the context's actor. Calling context() outside a run throws a LogicException.
At an HTTP edge, ServiceContext::fromRequest() builds an HTTP context, so the service can read request details
without seeing the request:
$order = PlaceOrder::make($payload) ->withContext(ServiceContext::fromRequest($request, EloquentActor::for($request->user()))) ->runOrFail(); // Inside PlaceOrder $ip = $this->context()->metadata[ServiceContext::METADATA_IP];
The client IP is stored under ServiceContext::METADATA_IP and the user agent under
ServiceContext::METADATA_USER_AGENT; both keys are always present and either may be null. Metadata passed as the
third argument is merged over them. The correlation id is read from the X-Request-Id header when it holds 1 to 128
printable ASCII characters with no whitespace, and generated otherwise. Set api-toolkit.services.correlation_header
(API_TOOLKIT_SERVICES_CORRELATION_HEADER) to read another header, or to null to always generate one.
The context is only bound during the run, so capture it for work that runs later:
protected function afterCommit(mixed $output): void { $context = $this->context(); defer(static fn () => logger()->info('Order placed.', ['correlation_id' => $context->correlationId])); }
The context is held on the service instance, so don't run one instance concurrently. Build a fresh instance per call,
as make() does.
Input Summaries
ServiceCompleted and ServiceFailed carry the input's toArray() as inputSummary, unchanged, so anything an
audit log or error tracker writes from it is only as safe as that array.
A Payload builds the summary from its public promoted properties. Mark a constructor parameter with PHP's
#[\SensitiveParameter] to leave it out; the attribute also hides the value from stack traces:
final class SignInPayload extends Payload { public function __construct( public readonly string $email, #[\SensitiveParameter] public readonly string $password, ) {} } SignInPayload::from(['email' => 'a@example.com', 'password' => 'secret'])->toArray(); // ['email' => 'a@example.com']
The key is omitted rather than masked, and the value stays readable on the instance. A payload that overrides
toArray() controls its summary entirely. Any other ServiceInput must keep secrets out of its own toArray(); an
ArrayInput returns its array as given, so leave secrets out of the array it wraps.
Body keys map to properties by their camelCase form: a client_name rule hydrates $clientName, and toArray()
returns it as client_name, matching the body and the request schema. A property named exactly after a rule key takes
precedence, and a property no rule maps keeps its own name. The map is read from the rules() keys once per class, so
those keys must be static:
final class StoreClientPayload extends Payload { public function __construct( public readonly string $clientName, ) {} public static function rules(): array { return ['client_name' => ['required', 'string']]; } } StoreClientPayload::from(['client_name' => 'Acme'])->clientName; // 'Acme' StoreClientPayload::from(['client_name' => 'Acme'])->toArray(); // ['client_name' => 'Acme']
Enum Input
A promoted property typed as an enum is cast from the body. A backed enum is read from its value; validate it with
Laravel's Rule::enum(). A pure enum has no value, so it is read and written by its case name in lowercase, matched
exactly (CONSOLE and Console are refused). Validate it with PureEnum, which accepts only those names, supports
only() and except() like Rule::enum(), and fails with the same validation.enum message:
use SineMacula\ApiToolkit\Validation\Rules\PureEnum; enum Application { case PLATFORM; case CONSOLE; case WORKFORCE; } final class StartSessionPayload extends Payload { public function __construct( public readonly Application $application, ) {} public static function rules(): array { return ['application' => ['required', (new PureEnum(Application::class))->except(Application::WORKFORCE)]]; } } StartSessionPayload::from(['application' => 'console'])->application; // Application::CONSOLE
A backed enum is read only from its canonical form: a string for a string-backed enum, and an integer or its plain
decimal string for an int-backed one. So "3" and "-3" are read, while "03", "+3" and "3.0" are refused even
where Rule::enum() passes them. A value that matches no case fails as a 422 keyed by its body key, even when
rules() leaves the enum rule out. A resource field holding a pure enum case is serialised as the same lowercase
name, so it can be sent back unchanged. An enum whose case names collide once lowercased, such as case Web and
case WEB, throws a LogicException, as does a rule nested under an enum property's key, such as status.name, since
the property is read from the whole value.
A model attribute cast to a pure enum also uses the lowercase name in filters and in repository writes, though
Eloquent stores the declared case name. {"platform": {"$in": ["web", "mobile_app"]}} matches rows storing WEB and
MOBILE_APP, on the root model or through a relation, and any other spelling, MOBILE_APP included, is refused with
a 422.
persist() accepts the lowercase name or the case itself, and throws a ValueError for a string that names no case.
Notification Audit Log
When api-toolkit.notifications.enable_logging is true (the default), every NotificationSending event is logged at
debug and every NotificationSent event at info. Each line records the notification class, the notifiable type, the
notifiable id (when the notifiable is an Eloquent model with a key) and the channel. List classes in
api-toolkit.notifications.excluded_classes to skip them.
Lines go to the application's default log channel, so whether the debug lines are kept depends on that channel's
level. For a dedicated destination, define a channel in config/logging.php:
'channels' => [ 'notifications' => [ 'driver' => 'daily', 'path' => storage_path('logs/notifications.log'), 'level' => 'debug', ], ],
Then point api-toolkit.notifications.log_channel at it:
API_TOOLKIT_NOTIFICATIONS_LOG_CHANNEL=notifications
Requirements
- PHP ^8.3
- Laravel 13.39+
- MySQL 8.4+, where the search layer is used
- PostgreSQL 15+
MariaDB is untested: it reports its own driver name, so search needs a driver registered for it, and a prefix or ignored index can count as backing a sort.
Testing
composer test
composer test:coverage
composer check
composer format
composer smells
Upgrading
See UPGRADE.md for the breaking changes and migration steps from 1.x to 2.x.
Changelog
See CHANGELOG.md.
Contributing
See CONTRIBUTING.md.
Security
Report vulnerabilities privately; see SECURITY.md.
License
Licensed under the Apache License, Version 2.0.