はじめに こんにちは。リテールハブ開発部小売アプリチームの池です。 業務で Laravel Octane のメモリが残る挙動について調査する機会がありました。 Laravel Octane は、長時間稼働するプロセス上で Laravel アプリケーションを動かして高速化するツールです。便利な一方で、プロセスが長く生きるためメモリが残り続け、書き方次第ではリクエスト間で状態が引き継がれてしまうという、従来の Nginx + PHP-FPM 構成の Laravel では発生しにくい特性を持っています。この特性を理解せずに使うと予期しない事故につながる可能性があると感じました。 そこで本記事では、Octane + Swoole の仕組みを整理した上で、サンプルプログラムで挙動を検証し、Worker プロセスが常駐することに起因して気をつけるべきポイントについて整理したいと思います。 Laravel および Octane について多少の知識がある方を前提に書いており、Laravel 本体の解説等には触れません。 なお、本記事の内容は一次情報から確認するように努めていますが、私の理解違いや Octane / Swoole のバージョン差による挙動の違いが含まれている可能性があります。誤って実装すると事故につながり得る領域でもあるため、最終的にはご自身でソースコードや公式ドキュメントをご確認の上で適用ください。 仕組みの整理 この章では、Octane + Swoole で前のリクエストの情報が次のリクエストに残る仕組みを、次の 4 つの観点から整理します。 Octane + Swoole では Worker プロセスが常駐するため、PHP プロセス内のメモリがリクエストごとに初期化されない Octane はリクエストごとに $this->app を clone して $sandbox 上で処理することで、ベースのアプリインスタンスを直接書き換えないようにしている ただし PHP の clone はシャローコピーなので、共有されたオブジェクトの内部状態はリクエスト間で残り得る Octane は RequestReceived イベントに紐づくリスナー群でフレームワーク側の状態をリセットしている 本記事に登場するアーキテクチャ図やライフサイクル図は必要な要素に絞って簡略化しています。 1. Worker プロセスが常駐するため、メモリは初期化されない Octane + Swoole は、長時間生きる PHP プロセスを立ち上げる仕組みです。 Swoole のプロセスアーキテクチャ Worker は OS プロセスです。Manager から複数生成され、一定数のリクエストを処理するか停止シグナルを受信するまで走り続けます。 Worker のライフサイクル 長時間生き続ける Worker プロセスは次のように動きます。 注目したいのは、1 つの Worker プロセスが生き続けたまま複数のリクエストを順に処理し続ける構造です。Worker 起動時に 1 回だけ Laravel アプリケーションを組み立てて $this->app に保持し、その後はリクエストのたびにこの $this->app を clone して $sandbox として使い回します。この「同じ $this->app が複数リクエストにまたがって使われる」点が、後で見る「前のリクエストの情報が次のリクエストに残ってしまう」仕組みの一部になっています。 Worker 起動時に Laravel アプリケーションを組み立てている処理 Worker::boot() の実装は以下の通りです。 <?php // vendor/laravel/octane/src/Worker.php public function boot ( array $ initialInstances = []) : void { // ベースとなる Laravel アプリインスタンスを1つ生成 // 以降、リクエストのたびにここから clone する $ this -> app = $ app = $ this -> appFactory -> createApplication ( ... ) ; $ this -> dispatchEvent ( $ app , new WorkerStarting ( $ app )) ; } なぜメモリが残るのか Swoole + Octane では以下の仕組みでメモリが残ります。 Worker プロセスが生き続けるため、リクエスト終了時に変数・オブジェクトに割り当てられたメモリが解放されない 結果として、 $this->app を含む変数・オブジェクトがリクエストをまたいでメモリに残り続ける ここから先は、この「メモリに残り続ける $this->app をリクエストごとにどう扱うか」ということに焦点を当てます。 2. Octane はリクエストごとに $this->app を clone する Worker が常駐すれば $this->app も残ります。ただ、リクエスト処理の中で $this->app を直接書き換えてしまうと、その変更が次のリクエストにそのまま残ります。Octane はこれを避けるために、リクエストのたびに $this->app を clone して $sandbox を作り、その上でリクエスト処理を回す設計になっています。 <?php // vendor/laravel/octane/src/Worker.php public function handle ( Request $ request , RequestContext $ context ) : void { // アプリインスタンスを clone してリクエスト用の sandbox を作る CurrentApplication :: set ( $ sandbox = clone $ this -> app ) ; $ gateway = new ApplicationGateway ( $ this -> app, $ sandbox ) ; try { $ response = $ gateway -> handle ( $ request ) ; // ... レスポンス返却 ... } finally { $ sandbox -> flush () ; // sandbox 側の bindings クリア unset ( $ gateway , $ sandbox , ... ) ; CurrentApplication :: set ( $ this -> app ) ; // 元のアプリインスタンスに戻す } } ここでの clone の役割は、リクエスト処理を $sandbox 側に隔離して、ベースの $this->app を直接書き換えないようにすることです。 $this->app 自体は Worker 寿命までずっと生き続けますが、毎リクエストの処理が $this->app を直接書き換えなければ、結果としてベースを変更せずに使い回せる、という設計になっています。 3. clone はシャローコピーなので、内部状態はリクエスト間で残り得る ただし、PHP の clone はシャローコピーであるため、前節の「ベースを書き換えない」が成り立つ範囲には限界があります。 Application オブジェクト自体は新規（リクエストごとの器） 配列プロパティ（ bindings / instances など）はコピーされる（sandbox 側で書き換えても元には反映されない） 配列の中身（実際のオブジェクト）は元のアプリ $this->app と $sandbox で共有される これにより、以下のような挙動になります。 例えばリクエスト中に app()->instance('request', $req) のように差し替えても、 $sandbox 側にのみ反映され、ベースの $this->app には反映されない 一方で、ベースの $this->app に登録された解決済み singleton インスタンスは両者で共有されたまま 「singleton にリクエスト固有データを入れると次のリクエストにも残る」という現象は、この「clone してもオブジェクト自体は共有される」ことが要因と考えられます。 clone はコンテナの配列レベルでの隔離は提供するものの、配列の中に入っているオブジェクトの内部状態までは守ってくれない、というのがポイントです。 4. Octane の RequestReceived リスナーが一部の状態をリセットする clone だけでは配列の中に入っているオブジェクトのプロパティ書き換えを防げないため、Octane はそこを、リクエストごとに発火するイベントとそれに紐づくリスナーで、明示的に状態をリセットすることで補っています。 Worker のメインループ Worker のメインループの中では RequestReceived イベントが発火し、デフォルトで 8 個のリスナーを順に実行してから HTTP Kernel に処理を渡します。 Worker 起動 ↓ WorkerStarting イベント ↓ ┌── メインループ ─────────────────────────────────────────┐ │ RequestReceived イベント ─→ [8 listeners] │ │ ├─ FlushLocaleState │ │ ├─ FlushQueuedCookies │ │ ├─ FlushSessionState │ │ ├─ FlushAuthenticationState │ │ ├─ EnforceRequestScheme │ │ ├─ EnsureRequestServerPortMatchesScheme │ │ ├─ GiveNewRequestInstanceToApplication │ │ └─ GiveNewRequestInstanceToPaginator │ │ ↓ │ │ HTTP Kernel (Middleware → Controller) │ │ ↓ │ │ リクエスト終了 │ └─────────────────────────────────────────────────────────┘ ↓ max_requests に達したら Worker 再起動 これら 8 個のリスナーは、Locale / Cookie / Session / Auth といったフレームワーク状態のリセットや、 app('request') の差し替え、HTTPS スキームやポートの整合性チェックなどを担います。 実装の中でも、特に挙動を把握しておきたい 2 つを確認します。 まず、認証ガードを毎リクエスト破棄する FlushAuthenticationState を見てみます。 Laravel の AuthManager は内部で Guard インスタンスを $guards 配列にキャッシュし、各 Guard はさらに認証済みユーザーをプロパティに保持します。Octane でこのインスタンスをクリアしないと、 singleton で起きる現象と同じ構造で、前のリクエストの認証ユーザーが次のリクエストに引き継がれてしまいます。 FlushAuthenticationState は、このキャッシュを毎リクエスト破棄することで、前のリクエストの情報が次のリクエストに残らないようにしています。 実装は以下の通りです。 <?php // vendor/laravel/octane/src/Listeners/FlushAuthenticationState.php class FlushAuthenticationState { public function handle ( $ event ) : void { if ( $ event -> sandbox -> resolved ( 'auth.driver' )) { $ event -> sandbox -> forgetInstance ( 'auth.driver' ) ; } if ( $ event -> sandbox -> resolved ( 'auth' )) { with ( $ event -> sandbox -> make ( 'auth' ) , function ( $ auth ) use ( $ event ) { $ auth -> setApplication ( $ event -> sandbox ) ; $ auth -> forgetGuards () ; }) ; } } } auth がコンテナで解決済みの場合に forgetGuards() を呼びだし、Guards のキャッシュをクリアしていることがわかります。 次に、Request インスタンスを差し替える GiveNewRequestInstanceToApplication の実装は以下の通りです。 <?php // vendor/laravel/octane/src/Listeners/GiveNewRequestInstanceToApplication.php class GiveNewRequestInstanceToApplication { public function handle ( $ event ) : void { $ event -> app -> instance ( 'request' , $ event -> request ) ; $ event -> sandbox -> instance ( 'request' , $ event -> request ) ; } } app('request') を新しい Request インスタンスに差し替えます。 app('request') を呼ぶコードが常に最新の Request を見られるのは、このリスナーの働きによるものと理解できます。 何が残って、何が消えるのか 2 つのレイヤーに分けて整理します レイヤー 何が常駐するか リセット手段 Worker プロセス全体 Worker プロセス自体 + 関数テーブル / クラステーブル / static 変数 / グローバル変数 octane:reload / max_request 到達による Worker 再起動 Laravel Application ( $this->app ) bindings、singleton インスタンス、boot 済み ServiceProvider RequestReceived リスナー（部分的） なお、各 Worker は独立した OS プロセスであるため、Worker 間のメモリは分離されています。コルーチン無効時には同じ Worker 内のリクエストも順次処理されるため、気にすべきは「同じ Worker の中で、前のリクエストのデータが次のリクエストに引き継がれてしまわないか」という点に絞られると考えられます。 そのうえで、Laravel アプリコード上でよく使う状態保持の方法ごとに、同じ Worker・別リクエストでどう振る舞うかを整理すると次のようになります。 状態保持の方法 同 Worker・別リクエスト static 変数 残る グローバル変数 / $GLOBALS 残る Worker boot 時点などで解決済みの singleton インスタンスのプロパティ 残る 通常 bind (毎回新規) 毎回新規 scoped バインディング 次のライフサイクル開始時に flush $request->attributes Request 自体が新規生成 「残る」となっている static / グローバル変数 / singleton プロパティは、リクエスト固有のデータや、リクエストごとに増え続けるデータを置くと事故につながり得る点に注意が必要です。アプリ起動時に 1 度だけ初期化されるような不変なデータや、Worker 内で意図的に共有したいデータを置く分には問題ないと考えています。 ここまでは仕様上こうなっているはず、という整理でした。次は簡易的なプログラムで動作を検証します。 検証 仕組みの整理で示した観点を、実機で順に確認していきます。 static 変数 / グローバル変数がリクエスト間で残ること $this->app の内部状態（singleton インスタンスのプロパティ）がリクエスト間で残ること RequestReceived リスナーが一部の状態を実際にリセットすること 加えて、これらの検証が成立する前提として「同 Worker 内ではリクエストが順次処理される」ことを最初に確認します。 検証環境 検証は macOS 上のローカル Docker コンテナで、以下のバージョン構成で行います。 ソフトウェア バージョン Laravel 12.59.0 Octane 2.17.3 Swoole 6.2.1 Octane は次のコマンドで起動します。 php artisan octane:start --server=swoole --workers=10 --max-requests=500 このとき内部で適用される主な Swoole オプションは次の通りです。 設定 値 由来 enable_coroutine false Octane デフォルト（Laravel 本体がコルーチンセーフでないため意図的に無効化） worker_num 10 --workers=10 で指定 max_request 500 --max-requests=500 で指定（メモリリーク対策） 特別な設定はしておらず、Octane / Swoole のデフォルトのままです。 検証用ルートは routes/web.php に用意し、curl で叩いて結果を観察します。 前提の確認: 同 Worker 内でリクエストが順次処理されること まず大前提として、1 Worker 内では複数リクエストが並行処理されず、1 つずつ順番に処理されることを確認します。これ以降の検証はすべて「同じ Worker に来た複数リクエストが順番に処理される」という前提で議論を組み立てるため、確認します。 確認用コード リクエストを受け取ったら 2 秒スリープして PID とコルーチン ID を返すだけの単純なルートを用意します。 <?php Route :: get ( '/test-coroutine' , function () { $ pid = getmypid () ; $ cid = \Swoole\Coroutine :: getCid () ; sleep ( 2 ) ; return [ 'pid' => $ pid , 'cid' => $ cid , 'is_coroutine' => $ cid !== - 1 , ] ; }) ; 実行 Worker 数を 1 に絞った状態（ --workers=1 ）で、3 リクエストを並列で投げます。もし並行処理されるなら合計 2 秒前後で完了するはずです。 start= $( date +%s ) curl -s http://localhost:8001/test-coroutine > /tmp/r1 & curl -s http://localhost:8001/test-coroutine > /tmp/r2 & curl -s http://localhost:8001/test-coroutine > /tmp/r3 & wait echo " Total: $(( $ ( date +%s ) - start )) s " 結果 { " pid ": 14 ," cid ": -1 ," is_coroutine ": false } { " pid ": 14 ," cid ": -1 ," is_coroutine ": false } { " pid ": 14 ," cid ": -1 ," is_coroutine ": false } Total : 6s 3 リクエストの PID が一致（=14）し、 cid = -1 でコルーチン外、合計時間が 2 秒×3 ＝ 6 秒となっていることから、1 Worker 内ではリクエストが並行ではなく順次処理されることが確認できました。 検証 1: static 変数 / グローバル変数がリクエスト間で残ること 仕組みの整理で「static 変数は同 Worker 内では持続する」と書きました。これを実際に確かめます。 確認用コード <?php Route :: get ( '/test-static' , function () { static $ counter = 0 ; $ counter ++ ; $ GLOBALS [ 'global_counter' ] = ( $ GLOBALS [ 'global_counter' ] ?? 0 ) + 1 ; return [ 'pid' => getmypid () , 'static_counter' => $ counter , 'global_counter' => $ GLOBALS [ 'global_counter' ] , ] ; }) ; static 変数とグローバル変数の両方をインクリメントするシンプルなコードです。 実行 まず、同 Worker 内挙動を見るため Worker 数 1（ --workers=1 ）で順次 10 リクエストを投げます。 for i in { 1 .. 10 } ; do curl -s http://localhost:8001/test-static echo done 次に、Worker 数 10（ --workers=10 ）で並列 20 リクエストを投げ、Worker 間の独立性を確認します。 for i in { 1 .. 20 } ; do curl -s http://localhost:8001/test-static > /tmp/s_ $i & done wait for i in { 1 .. 20 } ; do cat /tmp/s_ $i ; echo; done | sort 結果 順次 10 リクエスト（ --workers=1 ）： { " pid ": 14 ," static_counter ": 1 ," global_counter ": 1 } { " pid ": 14 ," static_counter ": 2 ," global_counter ": 2 } { " pid ": 14 ," static_counter ": 3 ," global_counter ": 3 } ... { " pid ": 14 ," static_counter ": 10 ," global_counter ": 10 } 並列 20 リクエスト（ --workers=10 ）： { " pid ": 22 ," static_counter ": 1 ," global_counter ": 1 } { " pid ": 22 ," static_counter ": 2 ," global_counter ": 2 } { " pid ": 23 ," static_counter ": 1 ," global_counter ": 1 } { " pid ": 23 ," static_counter ": 2 ," global_counter ": 2 } { " pid ": 24 ," static_counter ": 1 ," global_counter ": 1 } { " pid ": 24 ," static_counter ": 2 ," global_counter ": 2 } ... { " pid ": 31 ," static_counter ": 1 ," global_counter ": 1 } { " pid ": 31 ," static_counter ": 2 ," global_counter ": 2 } 順次 10 リクエストでは全て同じ PID（=14）で、 static_counter と global_counter が 1 から 10 まで連続して増加しています。同 Worker 内では static / グローバル変数が持続していることが確認できます 並列 20 リクエストでは 10 個の異なる PID（22 〜 31）にリクエストが分散し、それぞれの Worker でカウンタが独立に 1 から始まっています。Worker 間でメモリが分離されていることが分かります 以上から、 static 変数とグローバル変数は同 Worker 内のリクエスト間で持続し、Worker 間では分離されることが確認できました。 これは、1 リクエスト目の値が 2 リクエスト目に意図せず見えてしまう可能性を意味します。前のリクエストの情報が次のリクエストに残るパターンと考えられるため、利用には注意が必要そうです。 検証 2: $this->app の内部状態がリクエスト間で残ること singleton の中にリクエスト固有のデータを保持して、リクエスト間で値が残ることを確認します。 確認用コード <?php // app/Services/UserContextSingletonService.php class UserContextSingletonService { private ? string $ currentUserName = null ; public function setCurrentUser ( string $ name ) : void { $ this -> currentUserName = $ name ; } public function getCurrentUser () : ? string { return $ this -> currentUserName; } } <?php // app/Providers/AppServiceProvider.php public function register () : void { $ this -> app -> singleton ( UserContextSingletonService :: class ) ; } public function boot () : void { // ベースの $this->app->instances にインスタンスを格納するため、boot 時点で resolve する $ this -> app -> make ( UserContextSingletonService :: class ) ; } 通常の singleton() だけでは、初回 app(...) 解決時にインスタンスが sandbox 側に入り、リクエスト終了時の $sandbox->flush() で破棄されます。リクエスト間で持続する状態を再現するため、サンプルでは boot() で make() を呼んでベースの $this->app->instances にインスタンスを積んでいます。 <?php use App\Services\UserContextSingletonService; Route :: get ( '/test-singleton-set/{name}' , function ( string $ name ) { app ( UserContextSingletonService :: class ) -> setCurrentUser ( $ name ) ; return [ 'pid' => getmypid () , 'action' => 'SET' , 'value' => app ( UserContextSingletonService :: class ) -> getCurrentUser () , ] ; }) ; Route :: get ( '/test-singleton-get' , function () { return [ 'pid' => getmypid () , 'action' => 'GET' , 'value' => app ( UserContextSingletonService :: class ) -> getCurrentUser () , ] ; }) ; 実行 curl http://localhost:8001/test-singleton-set/Alice curl http://localhost:8001/test-singleton-get curl http://localhost:8001/test-singleton-get 結果 { " pid ": 14 ," action ":" SET "," value ":" Alice " } { " pid ": 14 ," action ":" GET "," value ":" Alice " } ← 別リクエストなのに残っている { " pid ": 14 ," action ":" GET "," value ":" Alice " } ← まだ残っている 別のリクエストにもかかわらず、Alice という値がそのまま見えています。 singleton バインディングのインスタンスプロパティに格納した値が残ることが確認できました。 検証 3: RequestReceived リスナーが一部の状態をリセットすること FlushAuthenticationState リスナーが Guard キャッシュを破棄していることを確かめます。 確認用コード <?php use App\Models\User; use Illuminate\Support\Facades\Auth; Route :: get ( '/test-auth-set/{name}' , function ( string $ name ) { $ user = new User ([ 'name' => $ name ]) ; Auth :: setUser ( $ user ) ; return [ 'pid' => getmypid () , 'action' => 'SET' , 'user_name' => Auth :: user () ?-> name , ] ; }) ; Route :: get ( '/test-auth-get' , function () { return [ 'pid' => getmypid () , 'action' => 'GET' , 'user_name' => Auth :: user () ?-> name , ] ; }) ; Auth::setUser() を利用してデフォルトの Guardの $user プロパティに直接 User インスタンスを入れ、Guard キャッシュの状態を作って検証します。 実行 (1) デフォルト構成（ FlushAuthenticationState 有効） curl http://localhost:8001/test-auth-set/Alice curl http://localhost:8001/test-auth-get 結果は以下の通りです。 { " pid ": 14 ," action ":" SET "," user_name ":" Alice " } { " pid ": 14 ," action ":" GET "," user_name ": null } ← flush で消えている 実行 (2) FlushAuthenticationState を外した場合 検証のため、 RequestReceived リスナーから FlushAuthenticationState を除外します。 <?php // config/octane.php （listeners 部分のみ抜粋） use Laravel\Octane\Events\RequestReceived; use Laravel\Octane\Listeners\FlushAuthenticationState; use Laravel\Octane\Octane; return [ // ... 'listeners' => [ // ... RequestReceived :: class => array_values ( array_filter ( Octane :: prepareApplicationForNextRequest () , fn ( $ listener ) => $ listener !== FlushAuthenticationState :: class , )) , // ... ] , ] ; 同じ curl を実行します。 { " pid ": 15 ," action ":" SET "," user_name ":" Alice " } { " pid ": 15 ," action ":" GET "," user_name ":" Alice " } ← 前のリクエストの情報が残っている リクエストをまたいで Alice という値が残っています。 検証結果から、 FlushAuthenticationState を外すと認証状態がリクエスト間で残り、有効な場合は Guard キャッシュが毎リクエスト破棄されることが確認できました。フレームワーク標準の Auth が Octane でも安全に使えるのは、このリスナーが裏で動いているからこそだと言えます。 おわりに 本記事では、Octane + Swoole で前のリクエストの情報が次のリクエストに残る仕組みを整理し、サンプルコードで動作を検証しました。その結果、 clone とリスナーによって Auth などのフレームワーク側の状態はリクエストごとにクリアされる一方、 static 変数 / グローバル変数や、Worker boot 時に解決済みの singleton インスタンスのプロパティは自動ではクリアされないことが確認できました。 持続させてはいけない場所に状態を置かないこと、また、もし独自のグローバル状態を持たせる場合には RequestReceived などのイベントに自前のリスナーを追加してクリアすることを意識できればと思います。 最後まで読んでいただきありがとうございました。 参考 Deep Dive into Laravel Octane（Albert Chen）

はじめに こんにちは、リテールハブ開発部でバックエンドエンジニアをしているホシと申します。 現在、Laravel などを利用しながら小売アプリ開発に取り組んでいます。 少し前になりますが、先日3月17日にLaravel13がリリースされました。 （ https://laravel.com/docs/13.x/releases ） 昨年にもLaravel12について、バージョンアップ内容などを記事にしたのですが、 今年も新バージョンについてお話しできればと思います。 前回同様にまずはサポート期限の一覧を記載します。 1年サイクルでリリースしているのと、サポート期間はあっという間に過ぎてしまうことがわかります。 毎年のバージョンアップは大変でも2年ごとくらいには実施した方が良さそうです。 Laravel13の機能の紹介やバージョンアップ方法などはすでにたくさんあるとは思いますが、 本記事では、Laraveをバージョンアップする際にどんなことが必要かを調べてみたのと、 今回のLaravel13の大きな特徴として「破壊的変更を抑えつつ、AI時代向けにLaravelを進化させたバージョン」のようなので、 AI関連の気になる機能についても、あまり詳しくない私を含め、なるべくわかるような内容にできればと思います。 Laravel13のバージョンアップよりも、PHPバージョンアップが大変？ 今回もLaravelのバージョンアップ自体は破壊的変更も少なく、比較的低コストでできるようなのですが、 今回のバージョンでは、PHPが8.3からになりました。 PHP8.2以下の場合、ここが実は一番手間がかかる対応なのかもしれません。 まずはPHP8.3に変更することが問題なくできるかを調べるのが先になります。 また、今回のタイミングでできれば8.4まで上げることができれば、 今後のバージョンアップもスムーズにしやすくなるので、なるべく最新にしたいところです。 ただ、8.5まで上げてしまうとまだサポートしていないものなどでうまく行かない可能性も高くなるので、 8.4で試してみるのがバランスが良いのかなと思いました。 バージョンアップする際の対応項目 先ほどはPHPを上げる方が大変かもと記載していますが、 laravelの変更点もカバーすることを考えるとどちらもそれなりに対応は必要そうです・・・。 以下に現環境で必要な対応項目を整理してみました。 1. ランタイム / 環境の確認 PHP を最低 8.3（推奨 8.4）に統一 composer.json Dockerfile PHP 拡張・PECL（Swoole / OpenSwoole）が PHP 8.3/8.4 対応バージョンか確認 ECS タスク定義側で参照している base image / runtime も同期 2. 現在使用しているLaravelは全て13に対応しているか laravel/sanctum laravel/octane laravel/tinker laravel/boost laravel/pint など、使用しているもの全てが「13」に対応しているか確認しておく。 (上記は一部最新の情報ではないかもしれませんので参考程度にしてもらえると幸いです。) 3. 周辺ライブラリ（互換確認・場合によりバージョンアップ） sentry/sentry-laravel aws/aws-sdk-php など、周辺ライブラリがまだ未対応などがありそうなので、調べておく必要あり。 4. テスト / 静的解析（バージョンアップ対応） PHPUnit: 12.x（Pest 3 が要求） Pest: 3.0 へ移行 tests/Pest.php の uses() / プラグイン構成見直し Larastan phpstan.neon のルール再調整必須 mockery/mockery fakerphp/faker など、テストに関する変更は調べる限り、いろいろ見直しも必要そうです。 ちょっとここは詳しくないので、実際には試行錯誤しながらやらないと詰まりそうな雰囲気も感じています。 5. コード内の修正・確認が必要そうなところ（一部抜粋） Carbon 3 への移行（Laravel 12 から Carbon3.x を使用する必要あり） → now(), Carbon::parse() を使う全箇所を回帰テスト Eloquent / Query Builder → クエリの修正は不要の見込み Container / Service Provider → bootstrap/providers.php に記載すること推奨されていて、 Validation → カスタムルールがある場合、問題ないか確認など Authentication / Authorization → Hash::make の確認、Sanctum トークン形式の互換性確認など Octane → State leak / メモリリークなどが起きないかなど あまり特殊な処理などはしていないのですが、Carbon系は特にたくさん使っているのでよくみた方が良さそうでした。 テスト実行して問題ないか全体を確認は必須ですが、 基本的には利便性向上、追加機能系なので動かなくなるなどほぼほぼなさそうです。 メモリリークとかそういったものがすぐにはわかりにくいのでここもしっかり確認はした方が安全かなと思います。 6. CI / Docker / デプロイ バージョンを変えるなどは必須だと思いますが、 あとは環境やもともと記載している内容に合わせての変更になると思います。 ここは実際に動かしながら修正・動作確認して間違いの無いようにしたいです。 7. アップデート手順 もし複数バージョンアップの場合は、アップデート手順として推奨されているのは、 Laravelでも段階アップデートが安全なようなので、12 → 13 のように段階アップデートにするか、 一気に上げる方法にするかは変更、確認コストを見て決めていけると良いかなと思います。 Laravel 13の気になる機能：AIサポート ここからは、Laravel 13で一番気になったAI関連機能についてお話しできればと思います。 特に注目したいのは以下です。 Laravel AI SDK Embeddings Vector Search Semantic Search 今までは、様々なライブラリや外部サービスを組み合わせてAI検索などを実現する必要がありましたが、 Laravel13では、Laravel標準に近い形で実装できるようになっています。 ただ、Laravel13自体がAIモデルを持っているわけではなく、実際には外部のAIサービスを利用してEmbedding生成や意味検索を行います。 Laravel13では、それらをLaravelらしいAPIで扱いやすくなった、というイメージです。 また、Laravel側でAIサービスの差異をある程度吸収できるため、将来的に利用するAIモデルやサービスを変更しやすくなる可能性があります。 従来のように各AIサービスごとに個別実装するよりも、Laravelアプリへ組み込みやすくなったのかなと思いました。 Embeddingsとは？ そもそも、上記の各AIに関連するワードについてもしっかりと理解できていなかったので調べてみました。 Embeddingsとは、文章をAIが扱いやすい数値データに変換する仕組みです。 例えば、 「胃に優しい料理」 という文章を、AIが意味を比較できるベクトルデータに変換します。 内部的には： [0.183, -0.929, 0.442, ...] みたいな大量の数値になります。 この数値化はすでに大量の文章、単語関係、文脈を学習済みのモデルを利用することで実現できています。 use Illuminate\Support\Str; // 検索したい文章をEmbedding化する $embedding = Str::of('胃に優しい料理')->toEmbeddings(); 以下のwhereVectorSimilarTo() は、内部で検索文をEmbedding化し、保存済みEmbeddingとの意味距離を比較するイメージです。 use Illuminate\Support\Facades\DB; $recipes = DB::table('recipe_embeddings') ->whereVectorSimilarTo('embedding', '胃に優しい料理') ->limit(10) ->get(); このようなEmbedding生成やVector SearchをLaravelらしいAPIで扱いやすくなりました。 また、DB保存はPostgreSQLのpgvectorを利用してデータを保存したりします。 他にもいろいろあるようなのですが、ただMySQLだと、すでにVector Search関連機能が追加され、Embeddingを利用した類似検索自体は可能なのですが、 最適化やパフォーマンス面ではpgvectorなどを利用する方が現状は良いようです。 そのため、もしすでにMySQLを使用している場合は使い分けが一番コスト面、メリットの点で良いのかなと思います。 これにより、単なる文字一致ではなく、 数値の近似値の比較をすることができるようになり、 胃に優しい ↓ 雑炊、豆腐、うどん、茶碗蒸し のように、意味が近いものを検索しやすくなります。 Vector Searchとは？ Vector Search（ベクトル検索）は、 ベクトル同士の距離を比較して、近いものを探す技術です。 つまり、 検索文 ↓ Embedding（数値化） ↓ DB内のベクトルと距離比較 ↓ 近いものを取得 という流れになります。 意味が近い文章ほど、数値的にも近い位置に配置されるため、Semantic Search「意味検索」をしているようになります。 LIKE検索と意味検索の違い 従来のLIKE検索は、文字が一致するものを探します。 WHERE name LIKE '%豆腐%' これは商品名やコード検索には強いです。 一方、意味検索は、 疲れている時に食べたい 夜でも重くない 夏バテでも食べやすい のような曖昧な検索に向いています。 これにより、レシピや記事など様々な情報を持っているものから キーワード検索のような文字列一致ではなく、意味検索をできることから キーワード検索では拾えないような曖昧な検索にも対応できるようになります。 ハイブリッドがバランス良い 意味検索は強力な検索ですが、上記の商品名やコード検索には弱く、 どちらにもメリット、デメリットがあるため、 LIKE検索から切り替えるのではなく、組み合わせるのが一番バランスが良いかなと思います。 まずLIKE検索 結果が少なければVector Search 重複を除いて結果を返す 商品名検索ならLIKE検索で十分なことも多いです。 一方、レシピ検索や記事検索のように「意味」や「状況」で探したいものは、Vector Searchと相性が良いです。 上記は例になりますが、ここは工夫の余地の大きいところでもあり、 仕様や検索内容、実施頻度、パフォーマンスなどを考慮して実現できるようにしたいです。 精度を上げるポイント ここは私は勘違いしていましたが、 Vector Searchは、データ件数よりも説明文や属性情報が重要です。 確かにいくら大量にデータがあっても、１つ１つの情報が少ないと意味を持たせられないと思いました。 悪い例： 麻婆豆腐 良い例： 辛味が強く、ご飯が進む中華料理。 豆腐とひき肉を使った定番メニュー。 満足感があり、夕食向き。 このように、AIが理解しやすい説明を持たせることで検索精度が上がります。 精度検証の進め方 ここまででとりあえず試してみたいと思った際は、最初から大規模に導入する必要はありません。 検証の際も大量のデータというよりは、１つ１つのデータ量が揃っているかが重要で、 その上で、まずは小さく試すのが良さそうです。 500〜3000件程度のデータを用意 検索クエリを30〜100個作る LIKE検索とVector Searchを比較する 上位5件に納得できる結果があるか確認する 最初は厳密な評価指標より、人間が見て「使えそうか」を確認するだけでも十分です。 最後に いかがでしたでしょうか。 今回のバージョンアップはAI関連の進化が大きな特徴だったことがよくわかりました。 私でも実際に簡単なAI検索であれば、比較的低コストで実装もできそうなので、導入も気軽にできます。 もちろん精度アップや検証面はどうしても最初は大変かと思いますが、少しずつ試しながらノウハウも蓄積しつつ 少しずつ規模を大きくしつつ、応用していくのが大事かなと思いました。 ただ肝心のバージョンアップはそこまでコード改修は不要なものの、 全体を見るとやることは多いので、しっかり時間を確保して対応が必要かなと思います。 今後のLaravelバージョンアップの際にぜひ少しでも参考にしていただければ幸いです。 最後までお読みいただき、ありがとうございました。

概要 新卒研修で初めてPHP+Laravelのコードを書いて以来、ずっとLaravel(稀にPython)で仕事をしてきた。しかし風の噂によると、社内でもTypeScriptを使ったプロジェクトが増えてきていて需要があるのはJavaやTypeScriptらしい。 せっかくClaudeでコードを書ける環境にいるので、勉強しながら記事を書くことにした。 AIにコードを書かせる過程で浮かんだ疑問も載せたので、似た境遇にある人は読んでみてほしい。