Skip to content

Refresh: Laravel 13 and api-toolbox - #2

Merged
JustSteveKing merged 11 commits into
mainfrom
refresh/laravel-13-api-toolbox
Oct 20, 2026
Merged

JustSteveKing merged 11 commits into
mainfrom
refresh/laravel-13-api-toolbox

Conversation

@JustSteveKing

@JustSteveKing JustSteveKing commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

Brings Kit up to Laravel 13 and moves its HTTP plumbing onto api-toolbox, which needs Laravel 13.30+.

What changes for API clients

  • Errors are RFC 9457 problem details (application/problem+json), typed from the apiguide.dev catalogue. Clients branch on type; detail carries the message, still translated via Accept-Language where Kit raised it. instance is the request ID.
  • Resources are plain JSON, not JSON:API. Bodies are {"data": {...}} with attributes at the top level.
  • GET /v1/auth/tokens is cursor paginated: the body is the page of tokens, navigation is in Link headers, and meta.count is gone.
  • GET /v1/auth/me sends an ETag and answers If-None-Match with 304.
  • Idempotency follows the IETF draft: a reused key with a different payload is 422 (was 409), a retry while the first is in flight is 409, errors are replayed too, and Idempotency-Replayed is gone.
  • Request IDs are UUIDv7, and requests join W3C trace context.
  • Deprecation is #[Deprecation] / #[Sunset] on the controller instead of the sunset: middleware string; past the sunset date the endpoint is a 410 problem.
  • 415 comes from consumes:application/json and carries an Accept header naming the supported type.
  • /.well-known/api-catalog advertises /v1 with its OpenAPI description.

Under the hood

  • Kit's IdempotencyKey, Sunset, AttachRequestId and EnsureJsonApiRequest are removed in favour of the package. The security headers move to AddSecurityHeaders; the 410 after sunset stays in Kit as RetireSunsetEndpoints, reading the same attributes.
  • The exception callbacks in bootstrap/app.php now only write the security audit log; map() swaps in translated messages.
  • Guests are no longer redirected to a non-existent login route. Forcing Accept: application/json used to hide this; without it, a request with no Accept header was a 500.
  • Scribe documents errors as application/problem+json, and the contract test now checks each response's media type against the spec, not only its body.
  • PHPStan (level 10) had 72 errors and wasn't in CI. They're fixed, and CI now runs Pint and PHPStan before the tests.
  • Boost guidance is refreshed for Laravel 13 with api-toolbox's guideline and skill opted in. Cloud is turned off explicitly.
  • composer.json is renamed from laravel/laravel to juststeveking/kit, larastan comes off 3.x-dev, and minimum-stability is back to stable.

Follow-ups landed in this PR

  • api-toolbox v0.3.0 makes the package's own problem details translatable; Kit ships Spanish for all of them in lang/vendor/api-toolbox/es/problems.php, with a test that fails if a package upgrade adds a line the Spanish file lacks.
  • v0.3.0 types CursorPage generically, so the PHPStan ignore in ListTokensController is gone.
  • GEMINI.md and .gemini/ are removed: Boost 2.10 no longer writes Gemini guidance.
  • CI creates .env before composer install (the cause of ci-tests failing on main since February), and .gitleaksignore covers two Idempotency-Key test fixtures.

85 tests pass; composer lint and composer stan are clean.

Laravel 13.30 is the floor api-toolbox needs. Scribe moves to 5.11 for
Laravel 13 support, larastan comes off 3.x-dev now a stable release
covers it, and minimum-stability goes back to stable. The package is
renamed from laravel/laravel to juststeveking/kit.
…est ids

Every API error is now RFC 9457 problem details typed from the
apiguide.dev catalogue. Kit's own messages stay translated: they are
mapped onto the exceptions api-toolbox renders and arrive as the
problem's detail. The exception callbacks keep only the security audit
log.

Kit's hand-rolled middleware gives way to the package:

- IdempotencyKey becomes `idempotent`, with locking for in-flight
  retries; a reused key with a different payload is now 422, and the
  Idempotency-Replayed header is gone, as the draft defines none.
- Sunset becomes #[Deprecation] and #[Sunset] on the controller.
  RetireSunsetEndpoints keeps kit's 410 after the sunset date, reading
  the same attributes.
- AttachRequestId becomes Negotiation request IDs (UUIDv7) with W3C
  trace context, and problems carry the ID as their instance.
- EnsureJsonApiRequest becomes `consumes:application/json`; its
  security headers move to AddSecurityHeaders.

Guests are no longer redirected to a login route that does not exist,
which forcing Accept: application/json used to hide.
JSON:API resources give way to plain Laravel resources, so success and
error responses tell one story: application/json for data, RFC 9457
problem details for errors.

- GET /v1/auth/tokens is cursor paginated through api-toolbox, with
  navigation in RFC 8288 Link headers and a 400 for a cursor that
  cannot be decoded. The body is the page of tokens.
- GET /v1/auth/me sends an ETag and answers If-None-Match with 304.
- Documented error examples are problem details, and a Scribe generator
  labels them application/problem+json. The contract test now checks
  each runtime response's media type against the spec as well as its
  body.
PHPStan at level 10 reported 72 errors that CI never ran. They are fixed
with typed reads (Arr::string, config()->string(), typed model
properties) rather than casts from mixed, and CI now runs Pint and
PHPStan before the tests. The payloads' fromReqest is renamed
fromRequest.

Two errors are ignored in place with the reason: CursorPage::of() in
api-toolbox types its paginator too narrowly to accept int keys, and
Sanctum types currentAccessToken() as never being a TransientToken.
boost:update with api-toolbox opted in under "packages", so agents get
its guideline and the api-toolbox-development skill. Boost's own skills
move to their current set (testing-best-practices replaces
pest-testing). Cloud is set off explicitly: Boost treats a missing key
as on and installs a Laravel Cloud deployment skill.
The README described JSON:API resources, the Sunset middleware and
Laravel 12. It now covers problem details and how localization applies
to them, idempotency, deprecation attributes, pagination, ETags and the
API catalog, and lists the token endpoints it was missing.

A test covers the API catalog the README points clients at, and the
user factory sets a ULID so Scribe's examples document a real id
rather than a nullable one.
@coderabbitai

coderabbitai Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Too many files!

This PR contains 130 files, which is 30 over the limit of 100.

To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch.

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e55397aa-02aa-4fbc-8e94-ff2b6efac709
📥 Commits

Reviewing files that changed from the base of the PR and between 8a0cf3d and eb6f6f3.

⛔ Files ignored due to path filters: 1
  • composer.lock is excluded by !**/*.lock
📒 Files selected for processing: 130
  • .claude/skills/api-toolbox-development/SKILL.md
  • .claude/skills/api-toolbox-development/references/api-lifecycle.md
  • .claude/skills/api-toolbox-development/references/caching-and-pagination.md
  • .claude/skills/api-toolbox-development/references/problem-details.md
  • .claude/skills/api-toolbox-development/references/signatures-and-digests.md
  • .claude/skills/api-toolbox-development/references/testing.md
  • .claude/skills/api-toolbox-development/references/writes.md
  • .claude/skills/infer-conventions/SKILL.md
  • .claude/skills/infer-conventions/references/checklist.md
  • .claude/skills/laravel-best-practices/SKILL.md
  • .claude/skills/laravel-best-practices/rules/advanced-queries.md
  • .claude/skills/laravel-best-practices/rules/architecture.md
  • .claude/skills/laravel-best-practices/rules/blade-views.md
  • .claude/skills/laravel-best-practices/rules/caching.md
  • .claude/skills/laravel-best-practices/rules/collections.md
  • .claude/skills/laravel-best-practices/rules/config.md
  • .claude/skills/laravel-best-practices/rules/db-performance.md
  • .claude/skills/laravel-best-practices/rules/eloquent.md
  • .claude/skills/laravel-best-practices/rules/error-handling.md
  • .claude/skills/laravel-best-practices/rules/events-notifications.md
  • .claude/skills/laravel-best-practices/rules/http-client.md
  • .claude/skills/laravel-best-practices/rules/mail.md
  • .claude/skills/laravel-best-practices/rules/migrations.md
  • .claude/skills/laravel-best-practices/rules/queue-jobs.md
  • .claude/skills/laravel-best-practices/rules/routing.md
  • .claude/skills/laravel-best-practices/rules/scheduling.md
  • .claude/skills/laravel-best-practices/rules/security.md
  • .claude/skills/laravel-best-practices/rules/style.md
  • .claude/skills/laravel-best-practices/rules/testing.md
  • .claude/skills/laravel-best-practices/rules/validation.md
  • .claude/skills/pest-testing/SKILL.md
  • .claude/skills/testing-best-practices/SKILL.md
  • .claude/skills/testing-best-practices/rules/assertions.md
  • .claude/skills/testing-best-practices/rules/endpoint-tests.md
  • .claude/skills/testing-best-practices/rules/finding-features.md
  • .claude/skills/testing-best-practices/rules/isolation.md
  • .claude/skills/testing-best-practices/rules/naming.md
  • .claude/skills/testing-best-practices/rules/performance.md
  • .claude/skills/testing-best-practices/rules/review.md
  • .claude/skills/testing-best-practices/rules/security.md
  • .claude/skills/testing-best-practices/rules/test-data.md
  • .env.example
  • .gemini/settings.json
  • .github/workflows/ci-tests.yml
  • .github/workflows/dependency-updates.yml
  • .gitleaksignore
  • .scribe/.filehashes
  • .scribe/endpoints.cache/00.yaml
  • .scribe/endpoints/00.yaml
  • .scribe/intro.md
  • CLAUDE.md
  • GEMINI.md
  • README.md
  • app/Http/Controllers/Api/V1/Auth/DeleteAllTokensController.php
  • app/Http/Controllers/Api/V1/Auth/DeleteTokenController.php
  • app/Http/Controllers/Api/V1/Auth/ForgotPasswordController.php
  • app/Http/Controllers/Api/V1/Auth/ListTokensController.php
  • app/Http/Controllers/Api/V1/Auth/LoginController.php
  • app/Http/Controllers/Api/V1/Auth/LogoutController.php
  • app/Http/Controllers/Api/V1/Auth/MeController.php
  • app/Http/Controllers/Api/V1/Auth/RegisterController.php
  • app/Http/Controllers/Api/V1/Auth/ResetPasswordController.php
  • app/Http/Controllers/Api/V1/Auth/SendEmailVerificationNotificationController.php
  • app/Http/Controllers/Api/V1/Auth/ShowResetPasswordTokenController.php
  • app/Http/Controllers/Api/V1/Auth/VerifyEmailController.php
  • app/Http/Middleware/AddSecurityHeaders.php
  • app/Http/Middleware/AttachRequestId.php
  • app/Http/Middleware/EnforceTransportSecurity.php
  • app/Http/Middleware/EnsureJsonApiRequest.php
  • app/Http/Middleware/IdempotencyKey.php
  • app/Http/Middleware/RetireSunsetEndpoints.php
  • app/Http/Middleware/SetRequestLocale.php
  • app/Http/Middleware/Sunset.php
  • app/Http/Payloads/V1/DeleteTokenPayload.php
  • app/Http/Payloads/V1/ForgotPasswordPayload.php
  • app/Http/Payloads/V1/LoginPayload.php
  • app/Http/Payloads/V1/RegisterPayload.php
  • app/Http/Payloads/V1/ResetPasswordPayload.php
  • app/Http/Payloads/V1/ShowResetPasswordTokenPayload.php
  • app/Http/Payloads/V1/VerifyEmailPayload.php
  • app/Http/Requests/Auth/DeleteTokenRequest.php
  • app/Http/Requests/Auth/ShowResetPasswordTokenRequest.php
  • app/Http/Requests/Auth/VerifyEmailRequest.php
  • app/Http/Resources/PersonalAccessTokenResource.php
  • app/Http/Resources/UserResource.php
  • app/Models/User.php
  • app/Providers/AppServiceProvider.php
  • app/Support/ProblemDetailsOpenApiGenerator.php
  • app/Support/ProductionSecurityChecks.php
  • app/Support/SecurityAudit.php
  • boost.json
  • bootstrap/app.php
  • composer.json
  • config/api-toolbox.php
  • config/app.php
  • config/cors.php
  • config/idempotency.php
  • config/scribe.php
  • config/security.php
  • database/factories/UserFactory.php
  • database/migrations/0001_01_01_000000_create_users_table.php
  • database/migrations/0001_01_01_000001_create_cache_table.php
  • database/migrations/0001_01_01_000002_create_jobs_table.php
  • database/migrations/2026_02_22_210901_create_personal_access_tokens_table.php
  • lang/en/api.php
  • lang/es/api.php
  • lang/scribe.php
  • lang/vendor/api-toolbox/es/problems.php
  • public/docs/collection.json
  • public/docs/index.html
  • public/docs/js/theme-default-5.11.0.js
  • public/docs/js/tryitout-5.11.0.js
  • public/docs/openapi.yaml
  • routes/api/routes.php
  • routes/api/v1.php
  • tests/Feature/ApiCatalogTest.php
  • tests/Feature/ApiSecurityHardeningTest.php
  • tests/Feature/AuthAuditTrailTest.php
  • tests/Feature/AuthSecurityTest.php
  • tests/Feature/AuthTokenManagementTest.php
  • tests/Feature/AuthTokenTest.php
  • tests/Feature/DeprecationTest.php
  • tests/Feature/IdempotencyKeyTest.php
  • tests/Feature/LocalizationTest.php
  • tests/Feature/OpenApiContractTest.php
  • tests/Feature/ProductionSecurityChecksTest.php
  • tests/Feature/RequestIdMiddlewareTest.php
  • tests/Feature/SunsetMiddlewareTest.php
  • tests/Feature/TransportSecurityMiddlewareTest.php
  • vet.json

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Composer's post-autoload-dump boots the app, which with no .env runs as
production and fails ProductionSecurityChecks. ci-tests has failed on
main for this reason since the checks landed.

Gitleaks reads two Idempotency-Key fixtures in IdempotencyKeyTest as
generic API keys; their fingerprints go in .gitleaksignore.
Boost 2.10 no longer writes Gemini guidance, so GEMINI.md and
.gemini/settings.json were stuck describing Laravel 12. Gemini comes
out of boost.json's agents so a reinstall does not bring them back.
api-toolbox 0.3.0 reads the details of the problems it raises through
the translator, so Kit adds Spanish for every one of them in
lang/vendor/api-toolbox/es. The idempotency conflict and 415 tests
assert the Spanish detail again, and a test fails if a package upgrade
adds a line the Spanish file lacks.

0.3.0 also types CursorPage over the paginator's key and value, so the
PHPStan ignore in ListTokensController goes.
composer audit only knows published advisories, so a freshly
compromised release passes it and the dependency bot would open a PR
for it. Laravel Vet closes that gap as a Composer plugin:

- vet.json records what has been read; composer install fails on
  anything else, including a version re-published with other files.
- minimum-release-age holds back every release younger than 7 days.
  juststeveking/* and roave/security-advisories are excluded: the first
  are first-party, the second has to be current to protect anything.

The baseline is today's lock moved back to releases at least a week
old, which is why fourteen packages step down a patch or minor
(laravel/framework 13.37.0 to 13.35.0, guzzle 8.3.0 to 8.2.0).

The dependency bot moves to weekly. Vet refuses the update it writes,
so the workflow tolerates that, installs the new lock without the
plugin, and puts Vet's report in the PR body. The PR passes CI once
vet.json is updated on its branch.
@JustSteveKing
JustSteveKing merged commit 50cebe0 into main Oct 20, 2026
7 checks passed
@JustSteveKing
JustSteveKing deleted the refresh/laravel-13-api-toolbox branch October 20, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant