Originally published at hafiz.dev
When route metadata got merged into Laravel 13.17, the first comment on the pull request was a long-time framework contributor asking what it's actually for. His follow-up was blunter: "IMO none of this behavior belongs on the Route, but oh well."
I get the skepticism. On paper, "attach arbitrary data to routes" sounds like a solution looking for a problem. But here's the thing: Laravel developers have been attaching arbitrary data to routes for years. We just did it badly. Config files keyed by route name. Abused ->defaults() calls that leak into controller parameters. Naming conventions like admin.reports.legacy.v1 that encode three different facts into a string and pray nobody renames the route. A GitHub discussion from 2022 asked for exactly this feature and got zero answers.
So the question isn't whether attaching data to routes is a good idea. You're already doing it. The question is whether you keep doing it through hacks or use the supported, cache-safe API that ships in every Laravel app from 13.17 onwards.
This post covers what shipped, the merge rules that make groups powerful, and five concrete problems where route metadata replaces something uglier. Working code for each.
What Laravel 13.17 Actually Shipped
Three methods. That's the whole API.
metadata() attaches an array of data to a route or a group:
use App\Http\Controllers\UserController;
use Illuminate\Support\Facades\Route;
Route::get('/users', [UserController::class, 'index'])
->metadata(['head' => ['title' => 'Users']]);
getMetadata() reads it back from the resolved route, with dot notation and an optional default:
$request->route()->getMetadata('head.title'); // 'Users'
$request->route()->getMetadata('head.author', 'Hafiz'); // 'Hafiz' (fallback)
$request->route()->getMetadata(); // the full array
And setMetadata() replaces everything instead of merging, for the rare case where you want a route to opt out of whatever its group defined.
The part that makes this more than a glorified array property: metadata is stored on the route action under a dedicated metadata key. That means it flows through the existing route group logic and gets serialized by route:cache. Your metadata survives production route caching with zero extra work. Anything you'd find with php artisan route:list still resolves the same way (the full command reference is in the Laravel Artisan Commands guide if you need it).
Resources and singletons work too:
Route::resource('users', UserController::class)
->metadata(['head' => ['title' => 'Users']]);
Every route the resource generates carries the metadata. Before 13.17 there was no clean way to do this, because resource routes are registered in a pending state and you couldn't hook data onto them mid-registration.
The merge rules worth memorizing
Group metadata cascades down to every route inside the group. The merge follows two rules:
- Associative arrays merge recursively. Nested groups layer values on top of each other.
- Lists and scalar values replace what they inherit.
Here's both rules in one example:
Route::metadata(['head' => ['robots' => ['noindex'], 'author' => 'Hafiz']])
->group(function () {
Route::get('/users', [UserController::class, 'index'])
->metadata(['head' => ['title' => 'Users']]);
});
// $request->route()->getMetadata('head') returns:
// [
// 'robots' => ['noindex'], // inherited from the group
// 'author' => 'Hafiz', // inherited from the group
// 'title' => 'Users', // added by the route
// ]
The route added title without losing robots or author. But if the route had defined its own robots list, it would have replaced the group's list entirely, not merged with it. Lists replace. Associative keys merge. Once that clicks, the whole feature is predictable.
How We Hacked This Before
Every workaround for this problem had a real cost. Quick tour, because recognizing your own code in this list is the fastest way to see why the feature matters.
Custom keys in the action array. You could always smuggle extra keys into the route action and read them back with getAction(). It worked for single routes. It fell apart for groups, resources, and singletons, because there was no supported way to carry the data through the route-building pipeline. That's the exact gap the PR closes.
Abusing ->defaults(). Route defaults exist to provide default values for route parameters. Stuffing page titles or permission strings in there technically works, until a controller method with a matching parameter name silently receives your metadata as an argument. I've debugged that one. Not fun.
Config maps keyed by route name. A config/seo.php file with a hundred route names mapped to titles and descriptions. Now every route rename is a two-file change, nothing enforces the mapping stays in sync, and the data lives nowhere near the route it describes.
Encoding facts into route names. Names like api.v1.legacy.reports.index where "v1" and "legacy" are load-bearing. String parsing as architecture.
Route metadata replaces all four with data that lives on the route definition itself, cascades through groups, and survives caching. Now the five problems.
Problem 1: Per-Route SEO Tags Without a Config Map
The classic case, and the one the PR uses in its own examples. Marketing pages need distinct titles, meta descriptions, and robots directives. Most Laravel apps solve this with view-level variables passed from every controller method, which means every controller method has to remember to pass them.
With metadata, the route definition carries the SEO data and one middleware shares it with every view:
// routes/web.php
Route::metadata(['seo' => ['robots' => 'index,follow']])
->group(function () {
Route::view('/pricing', 'pages.pricing')
->metadata(['seo' => ['title' => 'Pricing', 'description' => 'Plans from 9 euro a month.']]);
Route::view('/about', 'pages.about')
->metadata(['seo' => ['title' => 'About us']]);
});
// app/Http/Middleware/ShareSeoMetadata.php
public function handle(Request $request, Closure $next): Response
{
View::share('seo', $request->route()->getMetadata('seo', []));
return $next($request);
}
Your layout reads $seo['title'] with a sensible fallback and you're done. Controllers stop caring about SEO entirely. The /about page didn't define a description, so getMetadata() just won't return one, and your Blade fallback handles it.
The win over a config map: renaming a route can't break anything, because nothing is keyed by route name anymore.
Problem 2: Feature Flag Gating for Whole Route Groups
You're rolling out a new billing section behind a flag. The old approach is a middleware that takes the flag name as a parameter, ->middleware('feature:new-billing'), repeated on every route or group. Workable, but middleware parameters are strings, they don't cascade with any structure, and stacking more than one gets noisy.
Metadata handles the cascade for you:
// routes/web.php
Route::metadata(['feature' => 'new-billing'])
->prefix('billing-v2')
->group(function () {
Route::get('/', [BillingController::class, 'index']);
Route::get('/invoices', [BillingController::class, 'invoices']);
Route::resource('payment-methods', PaymentMethodController::class);
});
// app/Http/Middleware/EnforceFeatureFlags.php
use Laravel\Pennant\Feature;
public function handle(Request $request, Closure $next): Response
{
$flag = $request->route()->getMetadata('feature');
if ($flag && ! Feature::active($flag)) {
abort(404);
}
return $next($request);
}
Register the middleware globally on the web group. Routes without a feature key pass straight through. The resource inside the group is covered automatically, which is exactly the pending-registration case the old action-array hack couldn't handle.
And when the rollout finishes, you delete one metadata line instead of hunting middleware strings across three files.
Problem 3: Declarative Permission Tags in Middleware
To be clear about scope first: this doesn't replace policies and gates. Model-level authorization belongs in policies. But plenty of apps also have coarse route-level access rules ("everything under /admin/reports needs the reports.view permission") that end up scattered across can: middleware strings.
Metadata gives you a single declarative layer:
Route::metadata(['permissions' => ['admin.access']])
->prefix('admin')
->group(function () {
Route::get('/dashboard', [DashboardController::class, 'index']);
Route::metadata(['permissions' => ['admin.access', 'reports.view']])
->prefix('reports')
->group(function () {
Route::get('/', [ReportController::class, 'index']);
Route::get('/export', [ReportController::class, 'export']);
});
});
Note the nested group repeats admin.access in its list. That's deliberate: permissions is a list, and lists replace inherited values rather than merging. If you want additive permissions, either repeat the inherited ones like I did here, or structure them as an associative array (['admin.access' => true, 'reports.view' => true]) so the recursive merge works in your favor. This is the sharpest edge in the whole feature, so it's worth internalizing early.
The enforcement middleware is five lines:
public function handle(Request $request, Closure $next): Response
{
foreach ($request->route()->getMetadata('permissions', []) as $permission) {
abort_unless($request->user()?->can($permission), 403);
}
return $next($request);
}
One place to audit route-level access. php artisan route:list shows you the routes, the metadata shows you the rules, and nothing is hidden in controller constructors.
Problem 4: Breadcrumbs That Build Themselves
This is the use case Ben Bjurstrom, the PR's author, gave when asked what the feature is for: package authors need a place to attach data to routes while group and resource registration is still pending. Breadcrumbs are the perfect example because they're hierarchical, exactly like nested route groups.
Route::metadata(['breadcrumb' => ['Admin' => '/admin']])
->prefix('admin')
->group(function () {
Route::metadata(['breadcrumb' => ['Admin' => '/admin', 'Users' => '/admin/users']])
->prefix('users')
->group(function () {
Route::get('/', [UserController::class, 'index']);
Route::get('/{user}', [UserController::class, 'show'])
->metadata(['breadcrumb' => ['Admin' => '/admin', 'Users' => '/admin/users', 'Detail' => null]]);
});
});
A Blade component reads $request->route()->getMetadata('breadcrumb', []) and renders the trail. No third-party breadcrumb package, no separate breadcrumb definition file that drifts out of sync with your routes, no reflection tricks.
Because breadcrumb maps are associative arrays, nested groups merge cleanly and you could even skip repeating the parent crumbs. I repeat them anyway for explicitness, since key order in merged arrays is something I'd rather not depend on for UI. Expect packages to build nicer APIs on top of this primitive soon; error trackers are already reading it, and Flare 3.1.0 displays route metadata next to stack traces.
Problem 5: API Deprecation Headers From One Middleware
If you version APIs, you eventually deprecate endpoints. Communicating that properly means Deprecation and Sunset headers on every affected response, and most teams either skip it or hardcode headers in a dozen controllers.
Tag the routes instead:
Route::prefix('api/v1')
->metadata(['api' => ['version' => 1]])
->group(function () {
Route::get('/orders', [Api\V1\OrderController::class, 'index'])
->metadata(['api' => [
'deprecated_at' => '2026-07-01T00:00:00Z',
'sunset' => '2026-12-31T23:59:59Z',
'successor' => '/api/v2/orders',
]]);
Route::get('/customers', [Api\V1\CustomerController::class, 'index']);
});
// app/Http/Middleware/AddDeprecationHeaders.php
use Illuminate\Support\Carbon;
public function handle(Request $request, Closure $next): Response
{
$response = $next($request);
if ($deprecatedAt = $request->route()->getMetadata('api.deprecated_at')) {
$response->headers->set('Deprecation', '@'.Carbon::parse($deprecatedAt)->timestamp);
if ($sunset = $request->route()->getMetadata('api.sunset')) {
$response->headers->set('Sunset', Carbon::parse($sunset)->toRfc7231String());
}
if ($successor = $request->route()->getMetadata('api.successor')) {
$response->headers->set('Link', '<'.$successor.'>; rel="successor-version"');
}
}
return $response;
}
The header formats matter here. RFC 9745, published March 2025, standardized the Deprecation header as a structured field date, meaning @ followed by a unix timestamp, and the older Sunset header from RFC 8594 takes a classic HTTP-date. Storing ISO strings in metadata and converting with Carbon at the edge keeps the route file readable while the wire format stays spec-compliant. Plenty of APIs still ship Deprecation: true from the pre-RFC draft days, but new code has no excuse.
Notice the dot notation doing real work too: api.deprecated_at reaches into the merged array, and the group's version key merged with the route's keys because both live under the associative api key.
The same metadata doubles as input for documentation tooling. Iterate the route collection in a command, read getMetadata('api'), and generate a deprecation report for your changelog. The data has one home and two consumers.
Where I'd Draw the Line
The contributor who questioned this feature on the PR wasn't entirely wrong. There's a version of route metadata that makes your app worse, and it looks like this: a junk drawer of loosely related keys that grows forever because "just add it to metadata" became the answer to everything.
My rules so far:
Metadata should describe the route, not configure behavior that belongs elsewhere. "This route is deprecated" describes. "Retry this route's queue jobs three times" configures, and belongs where queue configuration lives.
Keep values serializable. Everything goes through route:cache in production, so closures and objects are out. Strings, numbers, booleans, arrays. If you're tempted to put a closure in metadata, you actually want middleware.
Prefer associative structures over lists when groups are involved. You saw why in the permissions example. Lists replace on inheritance, and that surprises people.
Test the metadata directly. Since metadata is now load-bearing (a missing feature key means an unguarded route), a cheap test that iterates the route collection and asserts every route under a prefix carries the expected keys catches drift before production does:
it('guards every billing-v2 route with a feature flag', function () {
$routes = collect(app('router')->getRoutes())
->filter(fn ($route) => str_starts_with($route->uri(), 'billing-v2'));
expect($routes)->not->toBeEmpty();
$routes->each(fn ($route) => expect($route->getMetadata('feature'))->toBe('new-billing'));
});
Five lines of Pest, and nobody can add a route to that group that silently skips the gate. This kind of route-collection assertion was always possible, but metadata finally gives it something structured to assert against.
And know when the old tools are still right. A one-off route with one middleware doesn't need a metadata layer plus a global middleware reading it. Metadata earns its place when the same kind of data applies across many routes, especially through groups and resources. For single-route concerns, route model binding and plain middleware parameters are still the simpler answer.
If you're not on Laravel 13 yet, this feature alone won't justify the jump, but combined with everything else in the release it's another reason to schedule it. The Laravel 12 to 13 upgrade guide covers the path, and the upgrade itself is one of the smallest major-version jumps Laravel has shipped.
FAQ
Which Laravel version do I need for route metadata?
Laravel 13.17.0 or later. The PR was merged on June 19, 2026 and shipped in the 13.17.0 release. It's a minor release, so if you're on any 13.x version, composer update gets you there with no breaking changes.
Does route metadata work with route:cache?
Yes, and this is the main advantage over rolling your own. Metadata is stored on the route action under a dedicated key, so php artisan route:cache serializes it and getMetadata() reads it back identically in cached and uncached environments.
Can I use this in Laravel 12 or 11?
No. The feature landed in 13.x only and there's no official backport. On older versions you're back to config maps or action-array workarounds, which is a decent nudge toward upgrading.
How is metadata() different from defaults()?
defaults() provides default values for route parameters, which means the values can be injected into controller method arguments. metadata() is inert data that never touches parameter binding. If you've been using defaults() to store non-parameter data, metadata is the correct home for it.
What's the difference between metadata() and setMetadata()?
metadata() merges with whatever the route already has, including values inherited from groups. setMetadata() replaces the entire metadata array, which is how a route opts out of its group's metadata completely.
Wrapping Up
Route metadata is a small feature with a long tail. Nothing here was impossible before. All of it was awkward before. The difference between "possible with hacks" and "supported with clean cascade semantics and cache safety" is the difference between a pattern you avoid and a pattern you reach for.
Start with one use case. The SEO middleware is the lowest-risk entry point, and once the getMetadata() pattern is in your muscle memory, you'll spot the other four in your own codebase within a week.
Running a Laravel app that's accumulated years of route-name conventions and config maps, and want help untangling it during a 13.x upgrade? Let's talk.
Top comments (0)