Laravelを用いたチーム開発をしていたときに、IDE上にErrorやWarningは出ていないのにローカルでページを確認すると500 Server Errorが表示されて困惑していたときの話です。
また、その際に行った対処の方法を誰かの助けになればと思い、記録として残します。
(※初めての技術記事投稿のため、間違い等がある場合はご指摘いただけますと幸いです。)

開発環境

OS : Ubuntu 24.04 (WSL2上で利用)
IDE : JetBrains PhpStorm 2024.2
Docker : Docker Desktop 4.33.1
バックエンド : Laravel 10.47.0
フロントエンド : React 18.2.0
バンドラ : Vite 5.0.0

発生した問題

チームで開発していたプロジェクトのmainブランチをpullし、ホットリロードで更新された画面を確認すると500 Server Errorが表示された。
このとき、コンフリクトがあったわけでもなくIDE上でErrorやWarningもない状態だった。
Dockerやホットリロード機能は常に起動しており、pull前にページが表示できていたことは確認していた。
(※同様にmainブランチをpullしていた他のメンバーにページが表示できるか確認したところ、問題なく表示できていたため自分側に問題があると考えた。)

問題の原因

結論、git pullによるファイルの追加や変更に伴って一部PHPファイルのパスに変更が生じ、pull以前でComposerのautoload機能により作成されていた「PHPのファイルパス状況を整理した情報」と、「現在のPHPファイルのパス状況」の食い違いが原因だった。

対処方法

Composerのautoload機能で利用するファイルパス情報を最新にすることで解決できる。
具体的な方法として、composer.jsonを置いている階層で以下のコマンドを実行する。

composer dump-autoload

おわりに

今回発生した問題ではコードにErrorやWarningが発生していなかった、かつpullしてきたコード自体や他のメンバーの環境にも問題がなかったため、原因の特定が非常に難しかった。
また、Composerに対する理解が浅かったことに起因した問題であったが、“ファイルパスが食い違った”場合に何らかのErrorを表示することは可能なのだろうか。

参考資料