Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@ryokwkm

Laravel 12 & Filament v4：ディレクトリ構成と機能の完全マップ

Posted at

概要

laravel12, filament v4.x の機能を把握するために、まずはディレクトリ構造から
どこにどんな機能が配置されているのかを把握する。

Part I: 基盤層: ルートディレクトリの役割

プロジェクトの最上位階層は、アプリケーション全体の起動と設定、そしてWebサーバーとの接続点を定義します。

myapplication/
├── app/                  <-- 【Part II, III, IVで詳述】アプリケーションのコアロジック
├── bootstrap/            <-- アプリケーションの起動と設定
│   ├── app.php           <-- ミドルウェア、ルート、例外処理の集約点
│   └── providers.php     <-- 【Filament連携】サービスプロバイダの登録リスト
├── config/               <-- 設定ファイル
│   └── filament.php      <-- （オプション）グローバルFilament設定
├── database/             <-- マイグレーション、ファクトリ、シーダー
├── public/               <-- Webサーバーのドキュメントルート
│   └── index.php         <-- アプリケーションへの全リクエストのエントリポイント
├── resources/            <-- 【Part Vで詳述】Bladeビューと未コンパイルアセット
├── routes/               <-- ルート定義ファイル
│   ├── web.php           <-- Web（ブラウザ）ルート
│   └── console.php       <-- Artisanコマンド定義
├── storage/              <-- キャッシュ、ログ、セッション、アップロードファイル
├── tests/                <-- 自動テスト
├── vendor/               <-- Composer依存関係
├──.env                  <-- 環境変数ファイル（ローカル設定）
├── composer.json         <-- PHP依存関係定義
└── vite.config.js      <-- 【Filamentテーマ連携】Vite（アセットコンパイラ）設定

主要ファイル・ディレクトリの機能解説:

  • bootstrap/app.php: アプリケーションの「カーネル」です。ルーティング（web.phpなど）、ミドルウェア、例外処理、そして次に説明するproviders.phpの読み込みを一元管理します。
  • bootstrap/providers.php: アプリケーションがロードするサービスプロバイダを定義します。php artisan filament:installを実行すると、Filamentのパネル設定クラス（例：App\Providers\Filament\AdminPanelProvider::class）がここへ自動的に登録されます。
  • config/filament.php: （オプション）php artisan vendor:publish --tag=filament-configで発行されます。パネル固有の設定は後述のPanelProviderが優先されますが、デフォルトのファイルシステムディスク指定など、一部のグローバル設定はここで行います。
  • vite.config.js: アセットコンパイラViteの設定ファイルです。Filament v4でカスタムテーマを作成する場合、このファイルのinput配列に、コンパイル対象となるテーマのCSSファイルパスを明示的に追加する必要があります。

Part II: app/ ディレクトリ（コア・ロジック層）の全体像

app/ディレクトリは、ビジネスロジック（Models）と、FilamentのUIロジック（Filament/, Providers/Filament/）が共存する、開発の心臓部です。

app/
├── Filament/             <-- 【Filament v4 機能実装層】
│   ├── Pages/            <-- (B) グローバルなカスタムページ（ダッシュボード等）
│   ├── Resources/        <-- (C) CRUDリソース（モデル単位）
│   └── Widgets/          <-- (B) グローバルなダッシュボードウィジェット
├── Http/                 <-- HTTPトランスポート層
│   ├── Controllers/      <-- コントローラ
│   └── Middleware/       <-- ミドルウェア
├── Models/               <-- 【Filamentリソースの源泉】Eloquentモデル
│   └── User.php
├── Policies/             <-- 【Filament認可】Eloquentポリシー
│   └── UserPolicy.php
└── Providers/            <-- サービスプロバイダ
    ├── AppServiceProvider.php  <-- カスタムアセット登録等
    └── Filament/         <-- 【Filament v4 設定層】
        └── AdminPanelProvider.php  <-- (A) パネル定義ファイル

主要ディレクトリの機能解説:

  • app/Models/: Eloquentモデル。Filamentリソースの「源泉」です。make:filament-resourceは、ここにあるモデルを対象とします。
  • app/Policies/: Eloquentポリシー。Filamentは、モデル（例：User）に対応するポリシー（例：UserPolicy）を自動検出し、viewAny()やdelete()メソッドに基づき、ナビゲーションやボタンの表示/非表示を自動制御します。
  • app/Providers/Filament/: (A) パネル設定層。Filament v4のアーキテクチャの心臓部です。各管理画面の全体設定を定義します。（Part IIIで詳述）
  • app/Filament/: (B)(C) 機能実装層。makeコマンドで生成される、FilamentのUIを構成する全PHPクラスが格納されます。（Part IVで詳述）

Part III: パネル設定層 (app/Providers/Filament/)

php artisan filament:install --panels または
php artisan make:filament-panel [PanelName] コマンドは、app/Providers/Filament/内にAdminPanelProvider.phpのようなファイル（パネルプロバイダ）を生成します。

このファイルが、Filament v4の事実上の設定ファイルです。
bootstrap/providers.phpに登録されることで、アプリケーション起動時にロードされ、panel()メソッド内でパネルの全設定を定義します。

// app/Providers/Filament/AdminPanelProvider.php

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin') // パネルID
        ->path('admin') // URLパス (例: /admin)
        ->login() // ログインページを有効化
        ->colors([ // カラースキーム
            'primary' => Color::Amber,
        ])
        ->viteTheme('resources/css/filament/admin/theme.css') // カスタムテーマ
        
        // 【自動検出】規約に基づき、対応するディレクトリからクラスをスキャンする
        ->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
        ->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages')
        ->discoverWidgets(in: app_path('Filament/Widgets'), for: 'App\\Filament\\Widgets')
        
        ->middleware([
            //...
        ])
        ->authMiddleware([
            Authenticate::class, // ログインが必要なページのミドルウェア
        ]);
}

このdiscoverメソッド群が、Filament v4のアーキテクチャの鍵です。「app/Filament/Resourcesディレクトリにリソースクラスを追加する」というファイル操作を行うだけで、AdminPanelProviderがそれを自動検出し、ナビゲーションメニューが構築されます。

Part IV: 機能実装層 (app/Filament/)

app/Filament/は、PanelProviderで定義された「規約」に基づき、UIの具体的な機能（ページ、CRUD、ウィジェット）を実装するPHPクラスが格納される場所です。

4-1. app/Filament/の階層構造

app/Filament/
├── Pages/            <-- (B) パネルワイド・コンポーネント（グローバル）
│   ├── Dashboard.php
│   └── Settings.php
├── Resources/        <-- (C) リソース中心設計（モデル単位）
│   ├── UserResource.php  <-- リソースのハブ
│   └── UserResource/     <-- リソース関連コンポーネント
│       ├── Pages/
│       ├── Schemas/
│       ├── Tables/
│       ├── RelationManagers/
│       └── Widgets/
└── Widgets/          <-- (B) パネルワイド・コンポーネント（グローバル）
    └── StatsOverview.php

4-2. (B) パネルワイド・コンポーネント (Global Components)

これらは、特定のモデルに強く依存せず、パネル全体（例：メインダッシュボード）に関連付けられます。

  • app/Filament/Pages/:
    • ├── Dashboard.php: （オプション）php artisan make:filament-page Dashboardで作成。Filament標準のダッシュボードを上書き・拡張し、ウィジェットのレイアウト（カラム数）をカスタマイズしたり、表示するウィジェットを明示的に定義したりします。
    • └── Settings.php: php artisan make:filament-page Settingsで作成。ナビゲーションに「Settings」項目を独立して追加するための、フルページのLivewireコンポーネントです。
  • app/Filament/Widgets/:
    • └── StatsOverview.php: php artisan make:filament-widget StatsOverview --stats-overviewで作成。グローバルダッシュボードに表示される統計ウィジェット（例：「総ユーザー数」）を定義します。

4-3. (C) リソース中心設計 (Resource-Driven Architecture)

これはFilamentアプリケーションの中核であり、app/Models/Userモデルに対する完全なCRUDインターフェースを定義します。

  • app/Filament/Resources/:

    • ├── UserResource.php: php artisan make:filament-resource Userで作成される、Userモデルリソースの「ハブ」または「コントローラ」ファイルです。このファイルは、リソース全体の設定と、関連する他のコンポーネントを束ねる役割を持ちます。

      • $model = User::class: 関連付けるEloquentモデルを定義します。
      • getRelations(): array: リレーションマネージャ（PostsRelationManager::classなど）を登録します。
      • getPages(): array: このリソースが使用するページ（ルート）（List, Create, Edit）とそのURLを登録します。
      • getWidgets(): array: このリソースのページ（一覧や編集）に表示するリソースウィジェットを登録します。

    • └── UserResource/: UserResource.phpに関連するすべてのコンポーネント群を格納するディレクトリです。

      • ├── Pages/: リソースの各ページ（ルート）の具体的なロジックを定義するLivewireコンポーネントです。

        • │ ├── ListUsers.php: 一覧表示ページ。Tables/UserTable.phpを読み込みます。「新規作成」ボタンのアクションもここで定義します。
        • │ ├── CreateUser.php: 新規作成ページ。Schemas/UserForm.phpを読み込みます。
        • │ ├── EditUser.php: 編集ページ。Schemas/UserForm.phpを読み込みます。
        • │ └── ViewUser.php: （--viewフラグで作成時）表示専用ページ。Schemas/UserInfolist.phpを読み込みます。

      • ├── Schemas/: 【重要概念】 フォーム（Form）およびインフォリスト（Infolist）のスキーマ（フィールド定義）をカプセル化するクラス群です。

        • │ ├── UserForm.php: CreateUser.phpとEditUser.phpの両方から参照される、共通のフォームフィールド定義を格納します。
        • │ └── UserInfolist.php: （オプション）ViewUser.phpから参照される、表示専用のフィールド定義を格納します。

      • ├── Tables/: 【重要概念】 テーブルのスキーマ（列、フィルタ、アクション）をカプセル化するクラスです。

        • │ └── UserTable.php: ListUsers.phpから参照される、テーブルの定義（カラム、フィルター、テーブルアクション、バルクアクション）を格納します。

      • ├── RelationManagers/: 関連モデルの管理インターフェースを定義します。

        • │ └── PostsRelationManager.php: php artisan make:filament-relation-manager UserResource posts titleで作成。Userの編集/表示ページ下部に、関連する「Posts」のテーブル（作成・編集・削除機能付き）を表示します。

      • └── Widgets/: リソース固有のウィジェット（特定のモデルに依存するウィジェット）です。

        • └── UserStatsOverview.php: php artisan make:filament-widget UserStatsOverview --resource=UserResourceで作成。UserResourceのListUsersやEditUserページのヘッダー/フッターに、「このユーザーの総投稿数」のようなコンテキストに応じた統計を表示します。

4-4. アーキテクチャ的洞察：「関心の分離」と「再利用性」

Filament v4のResources/配下の構造は、モダンなソフトウェア設計原則である**「関心の分離（SoC）」と「再利用性」**を徹底しています。

フォームのフィールド定義はSchemas/UserForm.phpにカプセル化され、CreateUserページとEditUserページの両方から再利用されます。
同様に、テーブルの列定義はTables/UserTable.phpにカプセル化され、ListUsersページから呼び出されます。

これにより、UserResource.phpはUIの具体的な定義から解放され、リソース全体の「ハブ」としての役割に専念できます。結果として、コードベース全体の保守性とテスト容易性が向上します。

Part V: プレゼンテーション層: resources/によるカスタマイズ

app/ディレクトリが「機能」を定義するのに対し、resources/ディレクトリは、その「外観（Look & Feel）」、すなわちプレゼンテーション層を定義します。

resources/
├── css/                  <-- 未コンパイルのCSS
│   └── filament/
│       └── admin/        <-- （パネルID `admin` の場合）
│           └── theme.css   <-- 【レイヤー2】カスタムテーマファイル
├── js/                   <-- 未コンパイルのJS
│   └── custom.js         <-- （例）カスタムスクリプト
└── views/                <-- Bladeビュー
    ├── filament/         <-- `make:filament-page`等が生成するカスタムビュー
    │   ├── pages/
    │   │   └── settings.blade.php  <-- `app/Filament/Pages/Settings.php`用ビュー
    │   └── widgets/
    │       └── stats-overview.blade.php <-- `app/Filament/Widgets/StatsOverview.php`用ビュー
    └── vendor/           <-- 【レイヤー3】`vendor:publish`による上書きファイル
        └── filament/
            ├── components/
            │   └── layouts/
            │       └── app/
            │           ├── header.blade.php  <-- 【レイアウト上書き】パネル全体のヘッダー
            │           ├── sidebar.blade.php <-- 【レイアウト上書き】パネル全体のサイドバー
            │           └── footer.blade.php  <-- 【レイアウト上書き】パネル全体のフッター
            └── forms/
                └── components/
                    └── checkbox-list.blade.php <-- 【コンポーネント上書き】特定のフォーム部品

UIカスタマイズの「3つのレイヤー」

FilamentのUIカスタマイズには、推奨される順に3つのレイヤーがあります。

  1. レイヤー1: PanelProvider（PHP）
    • 方法: app/Providers/Filament/AdminPanelProvider.phpで、->colors()や->brandLogo()などのPHPメソッドを呼び出します。
    • 評価: 最も安全で推奨される方法。 Filamentが公式にサポートするAPIのみを使用するため、アップデート耐性が最も高いです。
  2. レイヤー2: テーマ（CSS）
    • 方法: php artisan make:filament-themeでresources/css/filament/admin/theme.cssを作成し、vite.config.jsでコンパイルします。
    • 評価: 推奨されるスタイリング方法。 Tailwind CSSの知識が必要ですが、HTML構造の変更には影響されにくく、アップデート耐性は高いです。
  3. レイヤー3: ビューの上書き（Blade）
    • 方法: php artisan vendor:publishで、resources/views/vendor/filament/にFilamentコアのBladeファイルをコピーし、直接編集します。
    • 評価: 最も強力ですが、最も危険な方法です。 コピーしたファイルは、Filament本体がアップデートされても自動更新されないため、将来的にアプリケーションが破損するリスクがあります。HTML構造の根本的な変更が必須な場合のみ、自己責任で利用する最終手段です。

まとめ

Laravel 12とFilament v4のディレクトリ構造は、一見すると複雑に見えるかもしれませんが、実際には**「関心の分離」と「再利用性」**というモダンな設計原則に強く基づいています。

  • パネル設定は app/Providers/Filament/ に集約されます。
  • UI機能は app/Filament/ 配下に「規約」として配置されます。
  • UIロジックは Schemas（フォーム定義）と Tables（テーブル定義）に分離され、再利用性が高められています。
  • 外観は resources/ で安全なレイヤー（階層）別にカスタマイズできます。

この規約に従うことで、開発者はファイル配置に悩むことなく、本質的なビジネスロジックの実装に集中でき、スケーラブルで保守性の高いクリーンなアプリケーションを構築することが可能になります。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?