Laravel Http3Earlyhints Laravel Package

Technical Evaluation

What changed in 1.5.3. This is a patch-level compatibility release with two changes: Laravel 13 (L13) support and the introduction of serializable_classes. There are no deprecations, no removals, and no migration steps implied by the changelog. Treat it as a maintenance bump that extends the supported framework ceiling rather than a functional change.

Package role and architecture fit. justbetter/laravel-http3earlyhints is a single-purpose HTTP-layer package: it emits 103 Early Hints responses carrying Link: <...>; rel=preload headers ahead of the final response so the browser can begin fetching critical assets while the server is still rendering. Architecturally this is a middleware-shaped concern, which is the correct place for it in Laravel — it sits in the HTTP kernel, has no persistence layer, no schema, no queue or worker involvement, and no long-running state of its own. That is a favourable fit: the blast radius is one middleware in one request lifecycle, and it can be removed by deleting a kernel entry.

Integration feasibility. Low. Composer require, optionally publish config, register middleware, done. The real integration cost is not in Laravel — it is in proving that the 103 response actually reaches the client through our edge.

Technical risk.

• Silent no-op risk (highest). Early Hints are only useful if every hop preserves the interim response. Nginx, some load balancers, and several CDN configurations either strip 103 or only forward it under specific settings. A misconfigured edge yields zero benefit with zero errors, so the failure is invisible in application logs and metrics.
• Redundant preloading. If Vite's modulepreload tags or existing Link headers already hint the same assets, we add header weight and risk duplicate fetches rather than saving time.
• Hint accuracy. Hints are sent before we know the response outcome. Hinting a resource that 404s, redirects, is auth-gated, or varies by user wastes connection setup and can regress metrics on cache-miss paths.
• serializable_classes is under-documented in the release note. The new config key implies a serialization boundary (likely for cached or precomputed hint payloads). Whether it affects only cached hint sets, or also Octane/worker reuse, determines whether it is a config nicety or a correctness concern.

Key questions for the maintainer / spike.

1. What exactly does serializable_classes govern — cached hint payloads, container-resolved hint providers, or something else? Is there a default allowlist, and what happens on a non-serializable entry?
2. What is the PHP version floor for the Laravel 13 path, and are the Laravel 10/11/12 constraints preserved in the same release line?
3. Is the package validated under Octane / Swoole / RoadRunner, where header state can persist across requests?
4. Which servers and CDNs have been verified to forward 103 (nginx version, Cloudflare, Fastly, ALB)?
5. Does it deduplicate against Link headers already set by the application or by Vite?

Integration Approach

Stack fit. Fits our Laravel HTTP stack cleanly, and the package's value proposition is only realised on HTTP/2 or HTTP/3 connections — on HTTP/1.1 the interim response is typically ignored or unsupported. Front-end coupling is to Vite-built assets, which matches our tooling. Confirm the PHP floor and the symfony/http-foundation constraint before assuming it drops into every service.

Migration path. Effectively a no-op upgrade: composer update justbetter/laravel-http3earlyhints within the existing caret constraint. No code changes, no config republish required unless we want to adopt serializable_classes. The meaningful decision is not this bump but whether to adopt the package at all, and 1.5.3 is a good baseline because it removes Laravel 13 from the "blocked" column of our framework upgrade calendar. Adopting a package that already supports the next major reduces the chance of a forced swap during the L13 migration.

Compatibility checks before merge.

• Run the full suite on the lowest and highest supported Laravel/PHP combinations in the matrix, not just our current one.
• Verify the published config merges cleanly over an existing config/early-hints.php (or equivalent) and does not overwrite tuned values.
• Confirm behaviour under Octane if any service runs it.
• Check that the middleware short-circuits correctly for non-HTML responses (JSON APIs, file downloads, streamed responses) — hinting on an API route is pure overhead.

Sequencing.

1. Sandbox spike on one staging service behind the real edge configuration.
2. Verify with curl --http2 -v (or an HTTP/3 client) that the 103 is emitted and received; capture the raw exchange as evidence.
3. Instrument: compare LCP and TTFB for a canary route group against control, with cache-warm and cache-cold cohorts separated.
4. Enable on one user-facing, asset-heavy route group; hold a week.
5. Expand or roll back. Rollback is a middleware removal plus a deploy — the cheapest possible reversal.

Operational Impact

Maintenance. Small, narrowly scoped OSS package with a short changelog history (1.5.2 → 1.5.3 is a two-line note). Low churn, low code volume, low review burden. The realistic maintenance task is per-Laravel-major compatibility verification, not ongoing code work. Pin with a caret constraint and review on each Laravel minor.

Support. Community-maintained (justbetter, maintainer indykoning), no SLA, no commercial backing evident. Acceptable for a performance optimisation that degrades to "current behaviour" when removed. Not acceptable if we were to make correctness depend on it — we should not.

Scaling. Negligible per-request CPU: building a handful of Link header values. The cost is a small increase in response header bytes on every request, which matters only on very high-RPS, cache-miss-heavy paths. If serializable_classes implies a cached hint set, that further flattens the cost curve and is worth enabling once semantics are confirmed. No new infrastructure, no new stateful component, no capacity planning required.

Failure modes to monitor.

• Edge strips 103 — silent, no error signal. Mitigation: an external synthetic check that asserts a 103 on a known route, not an application log line.
• Duplicate or conflicting preloads — watch for increased request counts for the same asset and for preload warnings in browser consoles.
• Hints for non-200 resources — track 404/redirect rates on hinted asset paths.
• Middleware on non-HTML responses — verify JSON and download endpoints are unaffected.
• Serialization failure — if serializable_classes is mis-scoped, expect exceptions on the cached-hint path only, which will surface as intermittent 500s on specific routes; add a targeted test.
• Framework upgrade breakage — isolated to the L13 upgrade window; the 1.5.3 note is exactly the signal that this window is now open rather than closed.

Ramp-up. Roughly half a day for a mid-level Laravel developer to install, configure, and demonstrate a working 103 locally. The disproportionate effort is on the infrastructure side — confirming CDN and load balancer behaviour and building a verification harness that does not depend on application logs. Budget the majority of the effort there, and treat the Laravel work as the easy half.

Recommendation. Accept 1.5.3 as the baseline for evaluation. It is a low-risk compatibility bump that materially improves our framework upgrade position, but it does not change the core adoption question, which hinges on edge support for interim responses and on measured LCP impact rather than on package capability.