SubstituteBindings Middleware works only in route group

[f-liva]

Hello everyone, I need to understand why registering the binding substitution middleware at the API Group level while declaring the routes works, whereas if I register and declare it inside the Dingo configuration file it doesn't work.

It works:

> routes/api.php

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
    $api->group(['middleware' => \Illuminate\Routing\Middleware\SubstituteBindings::class], function($api) {
        $api->resource('countries', 'App\Http\Controllers\Api\CountryController');
    });
});

Doesn't work:

> config/api.php

/*
    |--------------------------------------------------------------------------
    | API Middleware
    |--------------------------------------------------------------------------
    |
    | Middleware that will be applied globally to all API requests.
    |
    */

    'middleware' => [
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ],

[specialtactics]

Hi @f-liva I think it depends on your route definition, how are your api routes defined? Also what Laravel version do you have?

API middlware should be added to the App\Http\Kernel file typically, and in Laravel versions 11+ in bootstrap/app.php file.

[f-liva]

Hi, sorry for the late reply, I was on vacation.

I tried to attach the SubstituteBindings middleware in three different points and these are my considerations:

1) bootstrap/app.php ❌

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__ . '/../routes/web.php',
        api: __DIR__ . '/../routes/api.php',
        commands: __DIR__ . '/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->prependToGroup('api', [
            \Illuminate\Routing\Middleware\SubstituteBindings::class
        ]);
    })
    ->create();

Registering the middleware through bootstrap/app.php has no consequences.

2) config/api.php ❌

return [

    ...

    /*
    |--------------------------------------------------------------------------
    | API Middleware
    |--------------------------------------------------------------------------
    |
    | Middleware that will be applied globally to all API requests.
    |
    */

    'middleware' => [
        \Illuminate\Routing\Middleware\SubstituteBindings::class
    ],

    ...
];

Registering middleware through config/api.php causes a 500 error "Call to a member function parameters() on null".

3) routes/api.php ⚠️

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
    $api->group(['middleware' => \Illuminate\Routing\Middleware\SubstituteBindings::class], function($api) {
        $api->resource('countries', 'App\Http\Controllers\Api\CountryController');
    });
});

Registering the middleware through routes/api.php causes the bindings to work EXCEPT when using PhpUnit for testing. In that case, when making Internal Requests from unit tests, the bindings do not work.

[f-liva]

I am doing some debugging and I notice that at the point where the route is executed, the middleware are not present.

We are in \Illuminate\Routing\Router::runRouteWithinStack where it is done

$middleware = $shouldSkipMiddleware ? [] : $this->gatherRouteMiddleware($route);

If I call the route via Postman, the middleware is present:

array:2 [▼
  0 => "Dingo\Api\Http\Middleware\PrepareController"
  1 => "Illuminate\Routing\Middleware\SubstituteBindings"
]

If I call the route through a unit test, the middleware is absent:

[]

Tracing back in \Illuminate\Routing\Router::gatherRouteMiddleware and debugging the $route built starting from a normal Postman request is this:

Illuminate\Routing\Route {#3182 ▼
  +uri: "countries/{country}"
  +methods: array:2 [▶]
  +action: array:13 [▶]
  +isFallback: false
  +controller: 
App\Http\Controllers\Api
\
CountryController
 {#2432 ▶}
  +defaults: []
  +wheres: []
  +parameters: array:1 [▶]
  +parameterNames: array:1 [▶]
  #originalParameters: array:1 [▶]
  #withTrashedBindings: false
  #lockSeconds: null
  #waitSeconds: null
  +computedMiddleware: array:2 [▼
    0 => "api.controllers"
    1 => "Illuminate\Routing\Middleware\SubstituteBindings"
  ]
  +compiled: 
Symfony\Component\Routing
\
CompiledRoute
 {#3176 ▶}
  #router: 
Illuminate\Routing
\
Router
 {#45 ▶}
  #container: 
Illuminate\Foundation
\
Application
 {#8 …44}
  #bindingFields: []
}

And it can be seen that SubstituteBindings is present in computedMiddleware.

However, when performing an Internal Request, it reaches the point \Illuminate\Routing\Router::dispatchToRoute where $this->findRoute($request) is called, and the returned Route object lacks the middleware in computedMiddleware.

Illuminate\Routing\Route {#4045 ▼
  +uri: "countries/{country}"
  +methods: array:2 [▶]
  +action: array:13 [▶]
  +isFallback: false
  +controller: null
  +defaults: []
  +wheres: []
  +parameters: array:1 [▶]
  +parameterNames: array:1 [▶]
  #originalParameters: array:1 [▶]
  #withTrashedBindings: false
  #lockSeconds: null
  #waitSeconds: null
  +computedMiddleware: null
  +compiled: 
Symfony\Component\Routing
\
CompiledRoute
 {#4213 ▶}
  #router: 
Illuminate\Routing
\
Router
 {#384 ▶}
  #container: 
Illuminate\Foundation
\
Application
 {#455 …44}
  #bindingFields: []
}

From this point, I wouldn't know how to proceed anymore.

[f-liva]

Hello any news here?

[specialtactics]

Hey @f-liva sorry, this package is a bit on life-support, just until I can figure out a way to replace it. I imagine the reason is, in your example, you are adding the middleware to the Laravel's routes and Dingo has it's own route table, so while adding the middleware works, it's not picked up by the dingo router.

Does that make sense?

[adjiekrazz]

Hello, let me jump into this discussion. Here is what I’ve concluded based on the investigation.

While SubstituteBindings is supported by Dingo, it must be registered as a route middleware (via version() or group() definitions). As @f-liva mentioned before, this works:

> routes/api.php

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
    $api->group(['middleware' => \Illuminate\Routing\Middleware\SubstituteBindings::class], function($api) {
        $api->resource('countries', 'App\Http\Controllers\Api\CountryController');
    });
});

Registering it as an API/global middleware will cause it to be executed before routing occurs, resulting in $request->route() being null and leading to errors. The thrown error is Call to a member function parameters() on null.

This behavior is expected because SubstituteBindings is a route-level middleware, not a generic HTTP middleware. This is evident from its namespace Illuminate\Routing\Middleware and its internal implementation, which depends on an injected Illuminate\Contracts\Routing\Registrar (the router instance) and explicitly operates on a resolved route via $request->route().

As such, SubstituteBindings requires the router and route instance to be fully resolved before it can safely run. When registered as an API/global middleware in Dingo (via the api.php configuration), it is executed too early—before routing has taken place—making it incompatible at that stage.

This is consistent with other Laravel route middleware such as ThrottleRequests and ValidateSignature, which are also designed to run after route resolution and therefore must be registered at the route level rather than as global or API-level middleware.

Hope this helps.

[specialtactics]

Thanks @adjiekrazz that's a great explanation 👍