Api Toolbox Laravel Package

Getting Started

1. Require the package and publish its config (php artisan vendor:publish), then confirm what is actually active:

   php artisan about --only=api_toolbox
   

   This is the fastest sanity check you have: it prints the installed version, the on/off state of every feature (with experimental ones marked), and the signature key IDs plus their algorithms.
2. If you use an AI coding agent (Claude Code, Cursor, Copilot, etc.), run php artisan boost:install — or php artisan boost:update if you already had it. This drops in an always-loaded guideline plus the api-toolbox-development skill, so the agent knows the package's conventions rather than inventing them.
3. Read the guideline before the source. It is the shortest correct description of the package's opinions: throw problems instead of returning error JSON, which HTTP standard applies to locking / retries / Prefer / PATCH / webhooks / pagination, and how to check which features are enabled. The skill's per-area references are the detail you'll come back to.
4. First real use case: replace a hand-rolled error response with a thrown problem exception, and let the package render it. That single change gets you consistent application/problem+json output across the app — every other feature builds on that same discipline.

Where to look first, in order: config/api-toolbox.php (feature flags), the Features::EXPERIMENTAL constant, then the Boost skill references for whichever area you're touching.

Implementation Patterns

Gate features explicitly, don't assume defaults. Every capability appears to be flag-controlled. The pattern that scales is a small App\Support\ApiFeatures wrapper (or a config read in a service provider) that resolves flags once, so your controllers, middleware registration and tests all agree. Never branch on "is the class there" — branch on the flag.

Errors as exceptions, not as return values. The guideline is explicit: throw problems instead of returning error JSON. In practice that means your domain layer throws, and controllers stay free of response()->json([...], 422) blocks. This is the highest-leverage habit in the package — it makes problem types greppable and keeps status-code decisions out of controllers.

Tie tests to problem types, not strings. Assert on the type URI from the apiguide.dev catalogue plus status, not on the human-readable title or detail. Titles drift; type URIs are a contract.

Webhooks: pin keys by ID. php artisan about surfaces signature key IDs and algorithms — that's your rotation map. The day-to-day pattern is: two active signing keys during a rotation window, receivers resolve by the key ID in the header, then retire the old ID once traffic drains. Never log the secret itself (the about command deliberately won't show it or the key path; get key material from your config/env only).

Prefer + PATCH + locking belong together. For a resource edit flow, send Prefer: return=representation, use PATCH with a conditional request, and let the locking semantics guard against lost updates. Model the client contract as: "read → get validator → write with validator → on 409/412, re-read and retry once". Wire this into your HTTP client's retry layer rather than into each action.

Retries need idempotency. Whatever the package's retry guidance says, the caller side only works if the write is idempotent (idempotency key, or a naturally idempotent operation). Decide this per endpoint and document it in the OpenAPI spec alongside the pagination parameters.

Use the Boost skill as a review checklist. When you add a new endpoint area (say, your first webhook consumer), re-read that skill's reference for the area and diff it against your implementation. The package ships a test that every class, constant, middleware alias, assertion and method mentioned in the guideline exists and every PHP snippet parses — so the docs are mechanically trustworthy, which is rarer than it sounds.

Integration tips. Register the middleware aliases the guideline names rather than hand-rolling middleware; use the package's testing assertions (also named in the skill) in feature tests so you assert on problem documents and headers the same way the package does internally. Keep Features::EXPERIMENTAL off in production config until you're ready to absorb churn.

Gotchas and Tips

• Experimental features can change in a minor release. Features::EXPERIMENTAL is the authoritative list. Treat anything on it as "may break on composer update" — pin the version constraint accordingly, or gate it behind a config flag you can flip off without a deploy.
• Feature flags create two silent failure modes. A disabled feature means middleware aliases don't resolve and assertions aren't available, which surfaces as confusing "class not found"-ish test failures rather than a clear error. If a test behaves strangely, run php artisan about --only=api_toolbox first.
• The about section intentionally omits secrets and key paths. It gives you IDs and algorithms only. That's the right call, but it means "is the key material actually loaded?" is not answerable from about — verify that in a test or a dedicated health check.
• Problem type source changed, URIs did not. The digest problem types now come from the generated apiguide.dev catalogue. If you hardcoded the URI strings you are fine; if you hardcoded page links or descriptions, re-check them.
• Docs accuracy is tested, behaviour is not. The Boost test proves every referenced class, constant, alias, assertion and method exists and that snippets parse. It does not prove the described semantics match runtime. For anything experimental, trust a test you wrote over the guideline.
• boost:update is not boost:install. After upgrading the package, re-run boost:update — otherwise your agent keeps following the previous release's conventions and will happily write code against APIs that moved.
• Debugging: the fastest loop for a problem-document issue is to assert the raw status + type in a Pest/PHPUnit test with the package's own assertions, then inspect the diff. Don't debug via browser because the Content-Type and Prefer response headers carry much of the contract.
• Extension points worth knowing: feature flags (behavioural toggles), config-published problem type mappings, and the signing-key set (rotation without code change). Prefer all three over subclassing package internals.