Laravel Route To Class Laravel Package

Getting Started

Install the package and publish the config in one go:

composer require zschuessler/laravel-route-to-class
php artisan vendor:publish --tag="route-to-class-config"

The config file (config/route-to-class.php) is where you spend 90% of your time with this package: it defines how routes are transformed into class strings and where you override the defaults. Skim it before writing any Blade templates — the defaults assume a dotted route name convention (admin.users.index → admin-users-index), and most surprises come from a route name that doesn't match what you expected.

The first use case is a <body> tag in your main layout:

{{-- resources/views/layouts/app.blade.php --}}
<body class="@routeClasses">

Then visit a few routes and inspect the rendered markup. You should see the generated class(es) per page. From there, the natural next step is adding a mapping for pages where the auto-generated name is ugly or clashes with utility classes (e.g. a home route → landing-page):

// config/route-to-class.php
'routes' => [
    'home'        => 'landing-page',
    'admin.*'     => 'is-admin',
    'checkout.*'  => 'checkout checkout-flow',
],

Implementation Patterns

Per-layout scoping. Put the directive only on layouts that actually need it. If you have an app, admin, and auth layout, only app.blade.php usually wants route-derived body classes. Applying it globally invites accidental class collisions with Tailwind utilities.

Pair with a data attribute. Keep route identifiers machine-readable instead of relying on CSS:

<body class="@routeClasses" data-route="{{ request()->route()->getName() }}">

This lets JavaScript target [data-route^="admin."] without fighting CSS specificity from generated classes.

Wildcards for section-level styling. Use admin.* and billing.* wildcard mappings to add a section class to every child route, then add specific classes for individual leaf routes. This is the intended way to avoid enumerating every route.

Compose with utility classes. The directive returns a string, so it composes naturally with static classes:

<body class="min-h-screen antialiased @routeClasses">

Just watch for duplicate class output — mapping the same class in the config and also hardcoding it will double up.

Route-parameter interpolation. For routes with parameters (orders.show → /orders/{order}), the mapped class typically stays parameter-agnostic — you get orders-show, not orders-show-42. If you need per-resource identification, add it separately via data- attributes rather than trying to encode IDs in CSS classes.

Fallback for unnamed routes. Laravel doesn't require route names. Routes without names won't produce a class, so provide an explicit fallback in the config (or use Route::name('...') on every route in your app — this package is a good excuse to do so).

Testing. Assert against the rendered HTML in a feature test rather than unit-testing the class generation in isolation; the class output is a presentation concern and small changes to the config surface as test failures, which is exactly what you want.

Gotchas and Tips

Config caching. If you change config/route-to-class.php in production and nothing changes, you forgot php artisan config:cache. In dev this rarely bites; on deploy it always does. Add config:clear locally and config:cache in your deploy script.

Route name mismatches. The most common failure is a route named users.index while your config maps admin.users.index, or vice versa. Dump the current route with php artisan route:list --name=users before you start debugging the package itself — the map is usually what's wrong.

Sub-domain and locale routes. Routes with locale prefixes ({locale}/about) or subdomain bindings can generate odd class strings if the mapping relies on the route name only. Confirm names are stable, or map them explicitly in config.

Duplicate classes. If a wildcard (admin.* → is-admin) and a specific mapping (admin.users.index → is-admin users-page) both emit the same class, you'll get doubled tokens. Modern browsers don't care but it makes DOM snapshots noisy. Keep section and page classes distinct.

Escaping. The directive echoes a plain string. If you're generating classes from user-controlled values (e.g. a route parameter used as a class suffix), the output is not escaped for CSS — sanitise or avoid. For a body-class helper this is rarely exploitable, but it's worth knowing the boundary.

Extension points. The package is small, so if you need richer logic (e.g. class based on the authenticated user's role and route), wrap it rather than fork it: create your own Blade directive or view composer that calls the package helper and appends additional classes. This keeps the config simple and the extra logic testable in your app.

Debugging output. When the class list looks wrong, check request()->route()->getName() directly in a Blade @php block or a dd() in a middleware. Nine times out of ten the package is faithfully reflecting a route name you didn't expect.

Upgrade hygiene. With a 2024-07 release and a small maintainer surface, pin the major version in composer.json and re-read the config file diff after any upgrade — config shape changes are the most likely breaking surface for a package of this size.