🍰

Laravel11以降のミドルウェアの設定の書き方

2025/03/29に公開

Laravel

PHP

tech

はじめに

Laravel10から11以降にバージョンを上げた時に書き方が大きく変わりました。

その中でLaravel10まではapp/Http/Kernel.phpでミドルウェアのグループやエイリアスの設定などを行なっていたが、Laravel11以降ではbootstrap/app.phpに書くように変わりました。

そこで今回はLaravel11以降の書き方を少し整理したいと思います。

環境

PHP 8.4.5
Laravel 12.3.0

ミドルウェアの登録

まずはすべてのHTTPリクエストに対して実行するミドルウェアの指定する書き方です。

Laravel10

app/Http/Kernel.phpの$middlewareプロパティに実行するミドルウェアを指定します。

$middlewareプロパティの配列の要素を書き換えることで実行する順番を変えたり、独自のミドルウェアを指定することもできます。

    protected $middleware = [
        \App\Http\Middleware\TrimStrings::class, // trimを一番最初に動くように順番を変える
        \App\Http\Middleware\TrustProxies::class,
        \Illuminate\Http\Middleware\HandleCors::class,
        \App\Http\Middleware\PreventRequestsDuringMaintenance::class,
        \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
        \App\Http\Middleware\AAA::class, // 独自のミドルウェアを追加
    ];

Laravel12

bootstrap/app.phpのwithMiddlewareメソッドを使ってミドルウェアを指定します。

初期では処理が何も書かれていないです。
これはwithMiddlewareメソッドの引数のクロージャの引数で指定しているIlluminate\Foundation\Configuration\Middlewareクラスにデフォルトで指定しているミドルウェアがあるためです。

Laravel10同様にミドルウェアを指定する場合は、appendメソッドを使うと最後に追加、prependメソッドを使うと最初に追加します。

use App\Http\Middleware\AAA;
use App\Http\Middleware\BBB;
// use App\Http\Middleware\CCC;
// use App\Http\Middleware\DDD;
// use App\Http\Middleware\EEE;
// use App\Http\Middleware\FFF;

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(AAA::class);
    $middleware->prepend(BBB::class);

    // 配列を使えば複数指定することもできる
    // $middleware->append([CCC::class, DDD::class]);
    // $middleware->prepend([EEE::class, FFF::class]);
})

また、replaceメソッドを使うことでデフォルトのミドルウェアを書き換えることができます。
さらにデフォルトで指定しているミドルウェアを削除する場合はremoveメソッドを使います。

use App\Http\Middleware\GGG;
//use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull:
use Illuminate\Foundation\Http\Middleware\TrimStrings;
use Illuminate\Http\Middleware\ValidatePostSize;

->withMiddleware(function (Middleware $middleware) {
    $middleware->replace(TrimStrings::class, GGG::class);

    $middleware->remove(ValidatePostSize::class);

    // removeメソッドは配列を使えば複数指定することもできる
    // $middleware->remove([TrimStrings::class, ConvertEmptyStringsToNull::class]);
})

それぞれのメソッドを使って指定を書き換えることができますが、useメソッドを使うことで一括で書き換えることもできます。

->withMiddleware(function (Middleware $middleware) {
    $middleware->use([
        \App\Http\Middleware\HHH::class,
        \Illuminate\Http\Middleware\ValidatePathEncoding::class,
        \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
        \Illuminate\Http\Middleware\TrustProxies::class,
        \Illuminate\Http\Middleware\HandleCors::class,
        \Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class,
        \Illuminate\Http\Middleware\GGG::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
        \App\Http\Middleware\III::class,
    ]);
})

ミドルウェアグループの登録

つぎに複数のミドルウェアを1つのキーにまとめて、ルートに割り当てる場合の書き方です。

Laravel10

app/Http/Kernel.phpの$middlewareGroupsプロパティに実行するミドルウェアを指定します。

デフォルトでwebとapiの2つのミドルウェアグループが定義されている。
この2つはミドルウェアグループはapp/Providers/RouteServiceProvider.phpで対応するwebとapiルートファイルを自動で読み込みを行う。

$middlewareGroupsプロパティのweb、apiの配列の要素を書き換えることで実行する順番を変えたり、独自のミドルウェアを指定することもできます。

    protected $middlewareGroups = [
        'web' => [
            \App\Http\Middleware\VerifyCsrfToken::class, // csrfトークンのチェックを一番最初に動くように順番を変える
            \App\Http\Middleware\EncryptCookies::class,
            \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
            \Illuminate\Session\Middleware\StartSession::class,
            \Illuminate\View\Middleware\ShareErrorsFromSession::class,
            \Illuminate\Routing\Middleware\SubstituteBindings::class,
            \App\Http\Middleware\AAA::class, // 独自のミドルウェアを追加
        ],

        'api' => [
            \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
            \Illuminate\Routing\Middleware\SubstituteBindings::class,
        ],
    ];

また、ミドルウェアグループを追加することもできる。
追加したミドルウェアグループはルートに割り当てることもできる。

    protected $middlewareGroups = [
        'web2' => [
            \App\Http\Middleware\AAA::class,
            \App\Http\Middleware\BBB::class,
            \App\Http\Middleware\CCC::class,
        ],
    ];

Route::get('/', function () {
    // ...
})->middleware('web2');

    public function boot(): void
    {
        $this->routes(function () {
            Route::middleware('web2')
                ->group(base_path('routes/web2.php'));
        });
    }

Laravel12

ミドルウェアの登録同様にbootstrap/app.phpのwithMiddlewareメソッドを使ってミドルウェアグループの登録を行います。
また、Laravel10同様、webとapiがデフォルトのミドルウェアグループとして定義しています。

これらのミドルウェアグループに独自のミドルウェアを登録する場合はwithMiddlewareメソッドの引数のクロージャの引数で指定しているIlluminate\Foundation\Configuration\Middlewareクラスに定義しているwebメソッド、apiメソッドを使います。

use App\Http\Middleware\AAA;
use App\Http\Middleware\BBB;

->withMiddleware(function (Middleware $middleware) {
    // webミドルウェアグループの最後に追加
    $middleware->web(append: [
        AAA::class,
    ]);

    // apiミドルウェアグループの最初に追加
    $middleware->api(prepend: [
        BBB::class,
    ]);
})

また、replaceを使うことでデフォルトのミドルウェアを書き換えることができます。
さらにデフォルトで指定しているミドルウェアを削除する場合はremoveを使います。

use App\Http\Middleware\GGG;
use Illuminate\Foundation\Http\Middleware\TrimStrings;
use Illuminate\Http\Middleware\ValidatePostSize;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(replace: [
        TrimStrings::class, GGG::class
    ]);

    $middleware->web(remove: [
        ValidatePostSize::class,
    ]);
})

また、groupメソッドを使って、ミドルウェアグループの登録ができる。

use App\Http\Middleware\AAA;
use App\Http\Middleware\BBB;

->withMiddleware(function (Middleware $middleware) {
    // webミドルウェアグループの最後に追加
    $middleware->group('web2' [
        AAA::class,
        BBB::class,
    ]);
})

エイリアスの登録

ミドルウェアへエイリアスを割り当てる場合の書き方です。

Laravel10

app/Http/Kernel.phpの$middlewareAliasesプロパティにエイリアスを設定したいミドルウェアを指定します。

デフォルトでいくつか登録済みです。

    protected $middlewareAliases = [
        'auth' => \App\Http\Middleware\Authenticate::class,
        'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
        'auth.session' => \Illuminate\Session\Middleware\AuthenticateSession::class,
        'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
        'can' => \Illuminate\Auth\Middleware\Authorize::class,
        'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
        'password.confirm' => \Illuminate\Auth\Middleware\RequirePassword::class,
        'precognitive' => \Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests::class,
        'signed' => \App\Http\Middleware\ValidateSignature::class,
        'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
        'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
        'aaa' => \App\Http\Middleware\AAA::class,   // 独自のミドルウェアを指定
    ];

Laravel12

ミドルウェアの登録同様にbootstrap/app.phpのwithMiddlewareメソッドを使ってミドルウェアのエイリアスを設定できます。

Laravel10同様にデフォルトでいくつか登録済みです。

実際に設定する場合はwithMiddlewareメソッドの引数のクロージャの引数で指定しているIlluminate\Foundation\Configuration\Middlewareクラスに定義しているaliasメソッドを使います。

use App\Http\Middleware\AAA;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'aaa' => AAA::class
    ]);
})

まとめ

ミドルウェアの設定についてLaravel11以降で変わった部分を整理してみました。
書きながら思ったのは、大きく変わっていますね。これをバージョンを上げる時に変更するのはお勧めしないとアップグレードガイドに書かれているのも頷けます。

おそらく他にもありそうなので、気づいた箇所は適宜追記したいと思います。

GitHubで編集を提案

はじめに

環境

ミドルウェアの登録

Laravel10

Laravel12

ミドルウェアグループの登録

Laravel10

Laravel12

エイリアスの登録

Laravel10

Laravel12

まとめ

Discussion