Filament 3 の案件に `composer require livewire/livewire` を無指定で打つとハマる

Laravel 12 + Filament v3 の構成に、あとから Livewire を明示的に追加しようとして地雷を踏んだので共有します。

結論

Filament v3 を使うプロジェクトでは、Livewire を単独でインストールするコマンドをバージョン無指定で打ってはいけません。

# NG: 2026年時点の最新である Livewire 4 が入る
composer require livewire/livewire

# OK: v3 系に明示ピン
composer require livewire/livewire:^3.6

何が起きるか

Filament v3 は Livewire 3.x に対する hard dependency を持っています。無指定コマンドで Livewire 4 が入った状態から Filament v3 を追加すると、Composer の依存解決が Livewire を 3 系へダウングレードする破壊的な更新を行い、autoload の dump が壊れることがあります。

具体的には次のようなエラーで気づくことになります。

PHP Fatal error:  Uncaught Error: Failed opening required
'.../vendor/phpunit/phpunit/src/Framework/Assert/Functions.php'

一見 PHPUnit や Pest 側の問題に見えますが、根本原因は Livewire のバージョン競合による vendor の半壊状態です。

正しい順序

# 1. Livewire を v3 明示でインストール
composer require livewire/livewire:^3.6

# 2. Filament 3 を入れる（-W で関連依存も同時更新）
composer require filament/filament:^3.0 -W

# 3. パネルをスカフォールド（admin パネル + AdminPanelProvider 自動登録）
php artisan filament:install --panels

Livewire → Filament の順でバージョンを固定してから入れれば、依存解決で余計なダウングレードが走りません。

壊れてしまった場合の復旧

vendor が半壊した状態からは、個別に直そうとせず完全に再構築するのが最速でした。

rm -rf vendor composer.lock
composer install --no-interaction

テストランナーのバージョンにも注意

同じ Laravel 12 starter 環境で Pest を使う場合、Pest 4 系は PHPUnit 12 を要求しますが、Laravel 12 starter は PHPUnit 11 にロックされています。ここも無指定で composer require pestphp/pest --dev すると噛み合わなくなるため、^3.8 系で明示的に入れる必要があります。

composer require pestphp/pest:^3.8 pestphp/pest-plugin-laravel --dev

まとめ

• Filament v3 を使うなら Livewire は ^3.6 で明示ピン
• Livewire → Filament の順でインストールする
• Pest も ^3.8 系を明示する（Laravel 12 starter の PHPUnit 11 ロックと噛み合わせるため）
• 壊れたら中途半端に直さず vendor ごと作り直す

似た構成（Laravel 12 + Filament v3）のプロジェクトを新規に立ち上げる方の参考になれば幸いです。