Admin Views 近接配置ルール

🤖 AI自動生成時の必須ルール

app/Admin配下で新しいコンポーネントを作成する際は、以下のルールを厳守すること:

ビュー配置: クラスと同じディレクトリ直下に Views ディレクトリを作成し、Bladeファイルを配置
名前空間: ビュー参照は EcSpokeAdmin::view-name 形式を使用
自動登録: AppServiceProvider により自動検出されるため、手動登録は不要
対象: Filament/Livewire/Bladeの全コンポーネント

配置例:

app/Admin/Components/NewComponent.php
app/Admin/Components/Views/new-component.blade.php

ビュー指定例:

protected string $view = 'EcSpokeAdmin::new-component';

概要

/app/Admin配下に適用するルール /app/FrontEndはまた、別のルールになる

開発を効率的に進めるために、Laravel標準から逸脱しているが、ビューとクラスを近接させる。ビューはクラスファイルのディレクトリ直下に Views ディレクトリを作りそこに置く。

配置例

① ページクラスとビュー
app/Admin/Base/Pages/Views/update-footer.blade.php
app/Admin/Base/Pages/BaseUpdateRecord.php

② コンポーネントとビュー
app/Admin/Components/Views/tree-select.blade.php
app/Admin/Components/TreeSelect.php

自動登録システム

app/Admin 配下のすべての Views ディレクトリは、AppServiceProvider により自動的にスキャンされ、EcSpokeAdmin:: 名前空間のビューコンポーネントとして登録されます。

仕組み

開発環境: リクエストごとに app/Admin を再帰的にスキャンし、すべての Views ディレクトリを検出
本番環境: キャッシュファイル（bootstrap/cache/admin-views.php）から読み込み、パフォーマンスを最適化

キャッシュの生成

本番環境ではデプロイ時に以下のコマンドを実行してキャッシュを事前生成：

php artisan admin:cache-views

コンポーネント種別による$viewプロパティの必要性

$viewプロパティの明示が必須

Filamentコンポーネント（Filament\Support\Components\ViewComponentを継承）は、設計上$viewプロパティを明示的に定義する必要があります。

// ✅ 正しい（$viewプロパティを明示）
class TreeSelect extends Field
{
    protected string $view = 'EcSpokeAdmin::tree-select';
}

// ❌ エラー（$viewプロパティがないとLogicException）
class TreeSelect extends Field
{
    // protected string $view = 'EcSpokeAdmin::tree-select'; ← コメントアウト不可
}

理由: Filamentは明示的な設定を重視する設計思想。クラス名からビュー名を自動推測する機能は実装されていない。

Livewireコンポーネント

$viewプロパティは不要（render()メソッドで指定）

Livewireコンポーネント（Livewire\Componentを継承）は、render()メソッド内でビューを指定します。

class TwoFactorAuthenticationManager extends Component
{
    public function render()
    {
        return view('EcSpokeAdmin::two-factor-authentication-manager');
    }
}

Livewireコンポーネント自体は自動登録されるため、Bladeテンプレートから直接呼び出せます：

<livewire:EcSpokeAdmin::two-factor-authentication-manager />

まとめ

コンポーネント種別	$viewプロパティ	ビュー指定方法	自動登録
Filamentコンポーネント	必須	`protected string $view = 'EcSpokeAdmin::xxx'`	不要
Livewireコンポーネント	不要	`render()`メソッド内で`view()`を使用	必要

共通点: どちらもEcSpokeAdmin::名前空間を使用してビューを参照でき、Viewsフォルダの自動検出の恩恵を受けます。

ビューの参照方法

1. Filamentフォームコンポーネント

class TreeSelect extends Field
{
    // ⚠️ このプロパティは必須（削除するとLogicException）
    protected string $view = 'EcSpokeAdmin::tree-select';
}

2. Filamentページ

class ListCategories extends Page
{
    protected string $view = 'EcSpokeAdmin::list-categories';
}

3. Livewireコンポーネント

public function render()
{
    return view('EcSpokeAdmin::category-tree-builder', [
        'items' => $this->items,
    ]);
}

Livewireコンポーネントの自動登録

app/Admin配下のLivewireコンポーネント（Livewire\Componentを継承）は自動的に検出・登録されます：

// クラス名をケバブケース化してEcSpokeAdmin名前空間で登録
TwoFactorAuthenticationManager → EcSpokeAdmin::two-factor-authentication-manager
EmailAuthenticationPanel → EcSpokeAdmin::email-authentication-panel
PageBuilderCanvas → EcSpokeAdmin::page-builder-canvas

使用例：

{{-- 自動登録されたLivewireコンポーネントを使用 --}}
<livewire:EcSpokeAdmin::two-factor-authentication-manager />
<livewire:EcSpokeAdmin::email-authentication-panel />

登録対象： - Livewire\Componentを継承する具象クラス - app/Admin配下の全PHPファイルを再帰的にスキャン

除外対象： - 抽象クラス（abstract class） - インターフェース - トレイト

4. Blade匿名コンポーネント

{{-- app/Admin/Components/Views/example.blade.php --}}
<x-ec-spoke-admin::example />

例外的な使用方法（ルール外のビュー配置）

自動登録システムは既存のLaravelビュー機能を補完するものです。特殊なケースでは、通常のLaravelビュー参照を引き続き使用できます：

パターン1: 標準的なLaravelビュー（resources/views/）

// resources/views/emails/notification.blade.php
protected string $view = 'emails.notification';

パターン2: 条件付きビュー切り替え

public function render()
{
    if ($this->isSpecialMode()) {
        return view('special.alternative-view');
    }

    return view('EcSpokeAdmin::standard-view');
}

パターン3: 明示的なドット区切りパス

// app/Admin/Base/Views/button.blade.php を直接指定
return view('Base.Views.button');

注意: 同名ファイルの扱い

複数の Views ディレクトリに同名のBladeファイルがある場合、最初に登録されたものが優先されます：

app/Admin/Base/Views/button.blade.php          → EcSpokeAdmin::button (優先)
app/Admin/Components/Views/button.blade.php    → EcSpokeAdmin::button (無視される)

推奨される回避策： - ファイル名を明確に区別する（例：base-button.blade.php, component-button.blade.php） - または直接パス指定を使用する（例：view('Base.Views.button')）

メリット

✅ 完全自動化：手動登録不要、新しい Views ディレクトリを作成すれば即座に利用可能
✅ シンプル：ファイル名ベースの参照で可読性向上
✅ 一貫性：すべてのAdmin Viewsが同じルールで管理
✅ パフォーマンス：本番環境ではキャッシュで高速化
✅ 保守性：ディレクトリを追加しても設定変更不要
✅ 柔軟性：ルール外のビュー参照も通常通り可能