On a Laravel travel-agency site, a SetLocale middleware appended to the web group runs after SubstituteBindings, so localized destination slugs fail to bind; how do you fix the order?

## The failure A travel-agency site serves destination pages under localized slugs: `/destinations/lisbon` in English and `/destinations/lisboa` in Portuguese. The `Destination` model resolves `{destination}` by looking up the slug for the **current application locale**. A `SetLocale` middleware reads the visitor's language from the session and calls `App::setLocale()`. It was registered like this: ```php $middleware->web(append: [SetLocale::class]); ``` The `web` group already ends with `SubstituteBindings`, the middleware that resolves route parameters into models. Appending places `SetLocale` after it, so binding runs with the default locale, the Portuguese slug is not found, and the visitor gets a 404. The middleware that sets the locale runs after the one that needs it. ## How Laravel orders route middleware The router builds a route's middleware list from the route's groups, the route itself and its controller, removes exclusions and duplicates, and then **sorts** the result with `Illuminate\Routing\SortedMiddleware` against the kernel's **priority list**. Key properties of that sort: - Only middleware that appear on the priority list are moved. Entries that are not on it are never moved themselves, so their relative order is the order you assigned. - A listed middleware that appears **after** another listed middleware with a later priority is moved in front of it; the process repeats until the listed entries follow the list's order. - Matching strips parameters and also checks the class's interfaces and parent classes, which is why the default list can name `Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests` and still catch `auth`. - The **global stack is never sorted**; it runs in registration order in the kernel pipeline. The framework's default list, in `Illuminate\Foundation\Http\Kernel`, places the precognition, cookie and session middleware first, then the `AuthenticatesRequests` contract, the throttle middleware, the `AuthenticatesSessions` contract, `SubstituteBindings` and finally `Authorize`. ## The fix: extend the list, do not replace it ```php ->withMiddleware(function (Middleware $middleware): void { $middleware->web(append: [SetLocale::class]); $middleware->prependToPriorityList( before: SubstituteBindings::class, prepend: SetLocale::class, ); }) ``` - `prependToPriorityList(before:, prepend:)` inserts `SetLocale` into the list immediately ahead of `SubstituteBindings`. The sorter now lifts it above binding. - `StartSession` stays earlier on the list, so the session is still started before `SetLocale` reads from it. - `appendToPriorityList(after:, append:)` is the mirror image; `appendToPriorityList(after: StartSession::class, append: SetLocale::class)` would work equally well here. - `before:` and `after:` accept arrays. If none of the named classes is on the list, the new entry is simply added at the end, where it rarely achieves anything; a typo in the class name fails silently this way. ## The alternatives, and why they fail | Attempt | Result | |---|---| | `web(prepend: [SetLocale::class])` | Runs before `StartSession`, so the session locale cannot be read | | `$middleware->prepend(SetLocale::class)` (global) | Runs before routing and before the session; never sorted | | `$middleware->priority([SetLocale::class, SubstituteBindings::class])` | Replaces the whole default list; session, auth and authorization ordering guarantees are gone | | `prependToPriorityList(before: SubstituteBindings::class, ...)` | Correct: after the session, before binding | The `priority()` trap deserves emphasis. `priority()` stores the array you pass as the complete list. With only two entries, `Authorize` (the `can` alias) is no longer guaranteed to run after binding, and `auth` is no longer guaranteed to run after `StartSession`. Nothing errors; routes with middleware assigned in an unlucky order simply start behaving differently. Use `priority()` only when you intend to restate the whole list. ## When the priority list is the wrong tool The priority list exists for the case the documentation calls rare: middleware assigned from several places whose order you do not control. When you control every assignment, explicit order is clearer: - Put related middleware in one named group in the order they must run. - Keep a custom middleware that depends on another next to it, rather than appending it to a distant group. - Reserve the priority list for cross-cutting classes, such as a locale or tenant resolver, that must precede framework middleware like `SubstituteBindings` wherever they are assigned. ## Verifying the order `php artisan route:list -v` prints each route's middleware after exclusion and sorting, one per line. After the fix, the destination route should list `StartSession` above `SetLocale` above `SubstituteBindings`. Checking this output belongs in the review of any change that touches middleware registration, because ordering bugs rarely surface as errors, only as wrong behaviour on some routes.