laravel-livewire

Laravel 13 上の Livewire 4 を扱います。Blade ビューを伴うリアクティブなクラスベースコンポーネント、wire:model による双方向バインディングとその修飾子（.blur、.live、.debounce）、アクション、コンポーネントのライフサイクルフック、フォーム／バリデーション、イベント（dispatch/listen）、Alpine.js 連携（$wire、@entangle）、ファイルアップロード、コンポーネントのネスト、ローディング状態、SPA ナビゲーション、テスト、セキュリティ（認証／レート制限）、そして Volt（単一ファイルコンポーネント）と Folio（ファイルベースルーティング）のサブ機能を、Precognition によるライブバリデーションや Reverb WebSocket 連携も含めて網羅します。

Laravel Livewire

エージェントワークフロー（必須）

実装を始める前に、3 つのエージェントを並列で起動してください。それぞれ name を指定した Agent 呼び出し 1 回ずつです。

1. fuse-ai-pilot:explore-codebase - 既存の Livewire コンポーネントを確認する
2. fuse-ai-pilot:research-expert - Context7 経由で Livewire 4 のパターンを検証する
3. mcp__context7__query-docs - 特定の Livewire 機能を確認する

実装後は、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

機能	説明
コンポーネント	Blade ビューを伴うリアクティブな PHP クラス
wire:model	双方向データバインディング
アクション	フロントエンドから PHP メソッドを呼び出す
イベント	コンポーネント間の通信
Volt	単一ファイルコンポーネント
Folio	ファイルベースルーティング

---

重要なルール

1. ループ内では常に wire:key を使用する
2. ライブバリデーションには wire:model.live.blur を使用する（Livewire 4.1 以降では、単なる .blur はクライアント状態のみを同期します）。すべての箇所で .live を使わない
3. 検索入力は .debounce.300ms でデバウンスする
4. 機密性の高い ID には #[Locked] を使用する
5. 破壊的なアクションでは authorize() を使用する
6. 内部ロジックには protected メソッドを使用する

---

意思決定ガイド

コンポーネントの種類

Component choice?
├── Complex logic → Class-based component
├── Simple page → Volt functional API
├── Medium complexity → Volt class-based
├── Quick embed → @volt inline
└── File-based route → Folio + Volt

データバインディング

Binding type?
├── Form fields (live validation) → wire:model.live.blur
├── Search input → wire:model.live.debounce.300ms
├── Checkbox/toggle → wire:model.live
├── Select → wire:model
└── No sync → Local Alpine x-data

---

リファレンスガイド

中核となる概念（WHY とアーキテクチャ）

トピック	リファレンス	参照すべきタイミング
コンポーネント	components.md	コンポーネントを作成するとき
Wire ディレクティブ	wire-directives.md	データバインディング、イベント
ライフサイクル	lifecycle.md	フック、mount、hydrate
フォーム	forms-validation.md	バリデーション、フォームオブジェクト
イベント	events.md	dispatch、listen
Alpine	alpine-integration.md	$wire、@entangle
ファイルアップロード	file-uploads.md	アップロードの処理
ネスト	nesting.md	親子関係
ローディング	loading-states.md	wire:loading、lazy
ナビゲーション	navigation.md	SPA モード
テスト	testing.md	コンポーネントのテスト
セキュリティ	security.md	認証、レート制限
Volt	volt.md	単一ファイルコンポーネント

高度な機能

トピック	リファレンス	参照すべきタイミング
Folio	folio.md	ファイルベースルーティング
Precognition	precognition.md	ライブバリデーション
Reverb	reverb.md	WebSocket

テンプレート (完全なコード)

テンプレート	使用する場面
BasicComponent.php.md	標準的なコンポーネント
FormComponent.php.md	バリデーション付きフォーム
VoltComponent.blade.md	Volt パターン
DataTableComponent.php.md	検索・ソート付きテーブル
FileUploadComponent.php.md	ファイルアップロード
NestedComponents.php.md	親子関係
ComponentTest.php.md	テストパターン

---

クイックリファレンス

基本的なコンポーネント

class Counter extends Component
{
    public int $count = 0;

    public function increment(): void
    {
        $this->count++;
    }

    public function render()
    {
        return view('livewire.counter');
    }
}

Volt ファンクショナル

<?php
use function Livewire\Volt\{state};

state(['count' => 0]);

$increment = fn() => $this->count++;
?>

<button wire:click="increment">{{ $count }}</button>

Wire ディレクティブ

<input wire:model.live.blur="email">
<input wire:model.live.debounce.300ms="search">
<button wire:click="save" wire:loading.attr="disabled">Save</button>

---

ベストプラクティス

推奨

• @foreach ループでは wire:key を使用する
• 検索・フィルター入力にはデバウンスを適用する
• 再利用可能なロジックには Form Objects を使用する
• Livewire::test() でテストする
• ID には #[Locked]、派生データには #[Computed] を使用する

非推奨

• すべてのフィールドに wire:model.live を付ける
• render() メソッド内でクエリを実行する
• アクションでの認可を忘れる
• ループ内で wire:key を省略する
• 機密データを public プロパティに保存する

---

Laravel 13 に関する注意点

Laravel 13 上の Livewire 4

Livewire 4 (現行 4.4) は現行のメジャーバージョンであり、L13 Livewire スターターキットで使用されています。主なポイント:

• Livewire 4 の要件: PHP 8.1+ / Laravel 10+ (Laravel 13 はそもそも PHP 8.3 が必要)
• #[Locked]、#[Computed]、#[On] は引き続きサポートされています
• ネイティブの単一ファイル / 複数ファイルコンポーネント (make_command.type = デフォルトで sfc)。Volt は 1.x (現行 1.11)、Folio は 1.x (現行 1.2) に留まります
• ページ: Route::livewire('/dashboard', Dashboard::class) が現在推奨される方法です (単一ファイル / 複数ファイルコンポーネントでは必須)
• ハッシュ化されたエンドポイント: /livewire/update の代わりに /livewire-{hash}/update (APP_KEY から生成) — /livewire/ を対象とするファイアウォール / CDN / ミドルウェアのルールを更新してください
• wire:model.live: 並列リクエスト。wire:poll はノンブロッキングです

Livewire 3 からの移行

• composer require livewire/livewire:^4.0 を実行してから php artisan optimize:clear
• 設定の名前変更: layout → component_layout (layouts::app)、lazy_placeholder → component_placeholder。smart_wire_keys はデフォルトで true
• 4.1+: .blur / .change もクライアント側の同期を制御します → 以前の動作 (blur 時のネットワークリクエスト) にするには wire:model.live.blur と記述します
• wire:model は子からのイベントを無視します (必要なら .deep を追加)。<livewire:x /> タグは閉じる必要があります
• wire:transition は View Transitions API を使用します (修飾子は削除されました)。wire:scroll → wire:navigate:scroll
• $this->stream(): to: は el: に名前変更。$wire.$js('name', fn) は非推奨 → $wire.$js.name = fn
• wire:poll.5s、$this->dispatch('event')、Form Objects (#[\Livewire\Attributes\Validate]) → 変更なし