Laravel Filamentカスタマイズ入門：フォームと一覧の作り込み手順

Filamentとは — Laravelの管理画面をPHPだけで定義するUIフレームワーク

Filamentは、Livewire・Alpine.js・Tailwind CSSの上に構築されたLaravel向けのUIフレームワークです。管理画面のフォームや一覧をHTMLやJavaScriptではなくPHPのメソッドチェーンで組み立てられるのが最大の特徴で、Bladeを書かずに入力欄・バリデーション・テーブルを宣言的に定義できます。この記事では、フォームと一覧を実務レベルで作り込む手順を扱います。

導入にはPHP 8.2以上が必要です（composer.jsonで"php": "^8.2"と指定）。土台がLivewireなので、Livewireの基本を押さえておくと挙動の理解が早まります。

カスタマイズを始める前に押さえるFilament専用Artisanコマンドの作法

ファイル生成には、Laravel標準のmake:ではなくFilament専用のArtisanコマンドを使います。リソースやページの雛形が規約どおりに揃うため、手書きより事故が減ります。実行前にphp artisan --helpでオプションを確認し、対話プロンプトで止まらないよう--no-interactionを付けておくこと。CIで生成を回すときにこれを忘れると、入力待ちのまま固まります。

フォームを条件分岐とリレーションで作り込む

フォームで頻出するのが、入力値による出し分けとリレーション先の一括編集です。どちらもFilamentが専用のユーティリティを用意しており、自前のJavaScriptは要りません。

Getで入力値に応じてフィールドを出し分ける

FilamentSchemasComponentsUtilitiesGetで別フィールドの現在値を読み取り、表示を制御できます。種別を選んだときだけ追加項目を出す、といったUIです。

use FilamentSchemasComponentsUtilitiesGet;

Select::make('type')
    ->options(CompanyType::class)
    ->live();

TextInput::make('vat_number')
    ->visible(fn (Get $get) => $get('type') === 'company');

見落としやすいのが->live()です。Filamentの一般的な挙動として、トリガー側をliveにしておかないと、値を変えてもサーバーへ再送されず、依存側の表示が更新されないことがあります。「切り替えたのに反応しない」ときは、まずここを疑ってください。

Repeaterでリレーション先のレコードを一括編集する

HasManyのような一対多を1画面で編集するならRepeaterが有効です。->relationship()を付けると、子レコードの読み込みと保存をFilamentが引き受けます。

use FilamentFormsComponentsRepeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        TextInput::make('name')->required(),
    ]);

ただしRepeaterは全件をフォームに展開するため、子が数百件に達すると描画が重くなります。件数が読めない関連はRepeaterで抱え込まず、別リソースの一覧＋Actionに分けたほうが運用は安定します。

一覧テーブルの表示列とフィルターをカスタマイズする

一覧側の作り込みは、カラムの計算表示とフィルターが中心になります。

stateで複数カラムを結合した計算列をつくる

DBに存在しない値を表示するには、TextColumnのstate()にクロージャを渡します。姓と名を結合したフルネームが典型です。

use FilamentTablesColumnsTextColumn;

TextColumn::make('full_name')
    ->state(fn (User $record): string => "{$record->first_name} {$record->last_name}");

注意したいのは、state列は実カラムではないため、そのままでは並び替えや検索の対象にならない点です。ソートさせたいなら実カラムを併用するか、クエリ側で対応します。

カスタマイズが画面に反映されない時に疑うキャッシュと生成漏れの確認手順

コードを直したのに画面が変わらない――Filamentで頻繁に起きる詰まりです。原因の大半はキャッシュか、Artisan生成の漏れ。次の順で確認します。

  • Laravelの一般的な手順として、php artisan view:clearとconfig:clearでキャッシュを落とす
  • 本番向けにfilament:cache-componentsで登録コンポーネントをキャッシュ済みなら、変更後に再生成する。このコマンドは全パネルのコンポーネントをキャッシュに登録するため、実行済みの環境ではコード変更が反映されず、再キャッシュが必要になる
  • デザイン変更が効かない場合、Tailwind利用時の一般的な確認ポイントとして、Tailwindのクラスがビルドに含まれているか確認する

それでも変わらないときは、編集したファイルが実際に使われているリソースか確認します。専用Artisanを使わず手書きしたクラスが名前空間のずれで読み込まれておらず、無関係な別ファイルを直し続けていた――案件でよくある落とし穴です。

カスタマイズに関するお問い合わせはこちら

    本記事のコード・挙動に関する記述は、filament/filament v5.7.4 の実際のソースコードと照合して確認しています。