Kit Laravel Package

Technical Evaluation

Architecture fit. Kit is not a Composer library you depend on; it is a Laravel 13 API starter kit you fork and own. That inversion is the single most important architectural fact for a TPM: there is no upstream to upgrade against, no vendor to escalate to, and no composer require integration path. What you inherit is a convention set — Sanctum token auth with ability scoping, versioned routes under routes/api/v1.php, RFC 9457 problem details via api-toolbox, Scribe-generated OpenAPI validated by contract tests, CloudEvents-shaped signed webhooks, Accept-Language localization with an en/es parity test, and a ProductionSecurityChecks boot guard. Fit is strong for a greenfield, externally-consumed HTTP API in Laravel. Fit is poor for retrofitting an existing application, for teams not already on Laravel, or for services that need JSON:API (deliberately removed) or a non-Scribe documentation pipeline.

Integration feasibility. Mechanically trivial, organizationally non-trivial. Clone, composer install, .env, key:generate, migrate, and the app boots. The real cost is the five-gate definition of done — composer lint, composer rector:check, composer stan (PHPStan/Larastan level 10), php artisan test, and legible check public/docs/openapi.yaml — plus CI building and booting the production image. Level 10 static analysis and a docs-readiness linter are the two gates teams will underestimate. Budget a genuine ramp-up: the generator-first loop (php artisan make:endpoint ...) makes the first endpoint fast, but only once the six-piece shape (route, Form Request, Payload, invokable Controller, Resource, Pest test) is internalized. Estimate 3–5 working days for a senior Laravel engineer to reach productive velocity, and longer for a team new to PHPStan level 10 or Scribe attribute-style documentation.

Technical risk.

Key questions to resolve before committing:

1. Who owns the fork? Name a maintainer and a backup, with an explicit patch/upgrade cadence.
2. Do we have (or plan) external API consumers? If yes, #[Deprecation]/#[Sunset] with automated 410, conditional requests, 412/428 lost-update protection, and idempotency keys become a public roadmap commitment — decide that before signing a partner contract.
3. Which of the bundled capabilities do we actually need? Async operations are off by default; webhooks, localization, and security audit logging each carry ongoing cost.
4. Is Laravel 13 acceptable to platform/security, and are we prepared to own it through the next major?
5. What is our Octane/FrankenPHP posture? It changes binding and request-state rules materially.
6. Do we need Spanish (or more) localization for real? The parity test tells you concretely whether this is a one-sprint toggle or a content-ops commitment.

Integration Approach

Stack fit. Kit assumes a containerized Laravel API with a separate php artisan queue:work process (emails and webhooks are queued), CI running five gates plus a production image build, and optionally Octane/FrankenPHP. If the target is a Laravel API behind an API gateway with external consumers, fit is close to ideal. If the target is a monolith or a service already deep in an existing error/pagination/doc convention, adopting Kit wholesale creates two competing standards.

Migration path — pick one deliberately:

• Option A: Greenfield service from Kit (recommended). Fork, prune what you don't need, build the domain. Highest leverage, cleanest ownership.
• Option B: Pattern adoption only. Keep the existing app; adopt api-toolbox, the six-piece endpoint shape, the error convention, and the five-gate CI selectively. Lower blast radius, higher design-review cost, and you lose the generator's payoff.
• Option C: Fork-then-bridge. Fork Kit for a new service and run it alongside the legacy system behind a gateway, migrating endpoints by domain. Best for incremental external-API modernization; requires a gateway routing strategy and a shared auth model.

Do not attempt Option A into an existing codebase — Kit is not designed for that and the CI gates will fail against inherited code.

Compatibility. Pin Laravel, api-toolbox, Scribe, legible, Pest, PHPStan/Larastan, Rector, and Pint versions in the repo. Three specific compatibility traps to pre-empt: (1) config/scribe.php must return early when the dev package is absent, or the production image build fails; (2) lang/vendor/api-toolbox/es/problems.php is version-checked by a test after package upgrades; (3) Rector and Pint must not be configured to disagree — skip Rector rules in rector.php with a documented reason rather than fighting Pint.

Sequencing.

Keep phase 2 strictly to one endpoint end-to-end. The value of Kit is the loop, not the file count, and a team that skips the loop will hand-roll error JSON within a month.

Operational Impact

Maintenance. You are maintaining a fork. Two recurring costs dominate: the toolchain (five CI gates plus a production image build on every change) and the dependency gate (vet.json holds new packages for seven days pending human review — correct, but it makes "add a small library" a scheduled activity). Plan an explicit quarterly review of api-toolbox and a deliberate, project-scoped approach to Laravel majors. Never loosen pint.json or phpstan.neon; once level 10 is relaxed, the substrate's main quality guarantee is gone.

Support. There is no vendor. Support means an internal owner who has read AGENTS.md and docs/README.md, plus a written fork changelog. The AGENTS.md file is unusually valuable here — it is written for coding agents and their supervisors, which makes it a credible onboarding artifact for AI-assisted delivery with a real quality floor. The compensating control for the low-star, single-maintainer profile is the five-gate CI: it is your safety net, and no merge should proceed with a red gate.

Scaling. The runtime surface is standard Laravel: stateless HTTP plus a queue worker, so horizontal scaling is unremarkable. Watch four things. Cursor pagination (CursorPage::of) is the blessed list pattern — offset pagination will degrade and will be inconsistent with the docs. Idempotency keys need a durable store; size it and set retention deliberately. Webhook delivery volume is governed by backoff, Retry-After, and auto-disable on repeated failure, so a broken subscriber cannot consume unbounded resources — but a subscriber flapping at scale still generates delivery-attempt records. Security audit logging grows monotonically; decide retention early. Under Octane/FrankenPHP, the app lives in memory: use scoped() bindings, resolve request state at request time, and never stash request data in singletons or statics.

Failure modes to instrument and document before launch:

• Auth works, route 403s — new abilities missing from sanctum.abilities.default; the most common first-week incident.
• Silent no-op delivery — queue worker not running means emails and webhooks simply never fire; alert on queue depth and failed jobs.
• Docs gate fails late — a path param validated in the Form Request appears as a body field, and a GET Form Request without queryParameters() gets documented as taking a body; both are caught by legible, usually after the endpoint is "finished."
• Rector deletes placeholders — running composer rector before filling in generated TODOs removes the unused payload and empty constructor as dead code.
• Boot refusal in production — ProductionSecurityChecks will not start without HTTPS enforcement, an https:// APP_URL, APP_DEBUG=false, explicit CORS origins, and trusted hosts. Correct behavior; make sure the deploy runbook says configure, not remove.
• CI DNS surprises — the webhook public-URL check runs on every send; tests must Http::fake() and bind App\Webhooks\HostResolver.
• Fork drift — the moment someone bypasses the generator or edits error JSON by hand, the conventions start eroding. Enforce in review.

Ramp-up. Treat ramp-up as a delivery milestone, not an onboarding side-effect. Target: a second engineer ships one endpoint end-to-end, green on all five gates, without pairing. Measure time-to-first-endpoint per engineer and the count of red-gate merges (should be zero). The single biggest adjustment coming from vanilla Laravel is that "finished" now means five gates green plus a committed regenerated OpenAPI spec — burn that in on day one.