Laravel Http3Earlyhints Laravel Package

Getting Started

Install the package:

composer require justbetter/laravel-http3earlyhints

Publish the config:

php artisan vendor:publish --tag="http3-earlyhints-config"

The service provider and EarlyHints middleware are auto-discovered (Laravel 13 is supported as of 1.5.3). Look first at config/http3-earlyhints.php, the JustBetter\Http3EarlyHints\Facades\Http3EarlyHints facade, and the JustBetter\Http3EarlyHints\Http\Middleware\EarlyHints middleware.

First use case — preload your critical CSS from a service provider or middleware:

use JustBetter\Http3EarlyHints\Facades\Http3EarlyHints;

Http3EarlyHints::add('/build/assets/app.css', ['as' => 'style']);

The middleware flushes a 103 Early Hints response with Link: </build/assets/app.css>; rel=preload; as=style before Laravel sends the final response — the browser can start fetching assets while PHP renders.

Implementation Patterns

• Global preloads — register fonts, CSS, and above-the-fold JS in AppServiceProvider::boot() so every response carries the same hints. Cache the list so it isn't rebuilt per request.
• Route-scoped hints — push hints from a controller method or a route middleware group to preload route-specific chunks (e.g. a Vite entry that only that page needs).
• Vite integration — read public/build/manifest.json once (and cache it) and map entry names to emitted files, then register those as preloads. Prefer this to hardcoding paths — a manifest-sourced hint can't drift out of date.
• Preconnect / preload / prefetch — use ['rel' => 'preconnect'] for third-party origins (fonts, analytics, CDNs) and ['rel' => 'preload', 'as' => 'font', 'crossorigin' => 'anonymous'] for fonts. Mixing the rels in one collector is fine.
• Octane / RoadRunner — the middleware stays resident across worker requests. As of 1.5.3, the new serializable_classes config option lets the hint collection round-trip through serialization (workers, queues, jobs). Populate it with any custom hint classes you register.
• Testing — Laravel's HTTP test client only sees the final response, so assert via the Http3EarlyHints facade or by inspecting the collector's toArray() rather than expecting a 103 status in $response->getStatusCode().

Gotchas and Tips

• 103 must be forwarded. nginx, Caddy, Cloudflare, and HTTP/3 endpoints handle interim responses differently. Verify with curl -I --http2 https://your.app — you need to see a 103 block before the final 200. If you only see 200, your server or CDN is eating the hint.
• Hints work over HTTP/2 too, not just HTTP/3. HTTP/3 gives the biggest win, but nothing breaks over H/2.
• Don't hint on non-idempotent requests (POST, PUT, DELETE). Browsers may re-issue prefetched GETs; guard the middleware or hint only on $request->isMethod('GET').
• Wrong URLs still fetch. A 404 preload wastes a round trip and can hurt Core Web Vitals. Only hint resources you know exist (manifest-sourced, not hand-typed).
• Font hints need crossorigin. Without as="font" and crossorigin="anonymous", the browser downloads the font twice — once for the hint, once for the CSS-referenced request.
• Keep the header small. Browsers and proxies cap total early-hint header size (roughly 8 KB); 20 hints is a reasonable ceiling. Prefer the 2–4 highest-impact assets per page.
• Serialization caveat (1.5.3). If you build hints in one process (a queue job, an event listener) and need them in the response, whitelist your hint classes in serializable_classes — otherwise the collector arrives empty.
• Debugging. Use Http3EarlyHints::toArray() in Tinker or log it from a terminate() hook to confirm hints are populated; inspect Link headers in the network tab for the final response to confirm they're being emitted.
• Extension points. Swap the middleware via $middleware->replace(...), or bind a custom collector in a service provider if you need different hint semantics.