FilamentPHP
#10 FilamentPHP基礎

Filamentを本番環境へ——設定の最終確認とデプロイ

本番デプロイの全体チェックリスト

Filamentアプリを本番環境にデプロイする前に確認すべき項目をまとめます。

□ アセット・コンポーネントキャッシュの実行
□ /admin URLの変更（セキュリティ）
□ HTTPS強制・CSRF設定の確認
□ ストレージのシンボリックリンク作成
□ キューワーカーの設定（メール送信等）
□ セッション・キャッシュドライバーをRedisに変更
□ ファイルパーミッションの確認

filament:optimize でアセットを最適化

Filament v5以降では filament:optimize コマンドで最適化処理をまとめて実行できます。

php artisan filament:optimize

このコマンドは内部的に以下を実行します。

php artisan filament:cache-components  # コンポーネントをキャッシュ
php artisan icons:cache               # アイコンをキャッシュ

デプロイスクリプトに組み込む例：

#!/bin/bash
# deploy.sh

git pull origin main
composer install --no-dev --optimize-autoloader

php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Filamentの最適化
php artisan filament:optimize

php artisan queue:restart

キャッシュのクリア方法

キャッシュを無効化したいときは以下を実行します。

php artisan filament:optimize-clear

# または個別に
php artisan filament:clear-cached-components
php artisan icons:clear

filament:cache-components の詳細

php artisan filament:cache-components

このコマンドは app/Filament/ 以下のリソース・ページ・ウィジェットをスキャンし、マニフェストファイルを生成します。discoverResources() での動的スキャンを省略できるため、ページロードが速くなります。

生成されるマニフェスト：

bootstrap/cache/filament/
├── panels.php      ← パネル設定のキャッシュ
└── ...

アセットのパブリッシュ

設定ファイルのパブリッシュ

php artisan vendor:publish --tag=filament-config

config/filament.php が生成されます。

<?php
// 📁 config/filament.php

return [
    // アセットのパスプレフィックス
    'assets_path' => null,

    // キャッシュドライバー
    'cache' => [
        'store' => env('FILAMENT_CACHE_STORE', config('cache.default')),
    ],

    // グローバル検索の設定
    'broadcasting' => [
        'echo'    => null,
    ],
];

ビュー（Bladeテンプレート）のパブリッシュ

フォームコンポーネントなどのビューをカスタマイズしたい場合：

php artisan vendor:publish --tag=filament-views

/admin URL の変更

デフォルトの /admin は攻撃者に管理画面の存在を知られやすいため、変更を推奨します。

// 📁 app/Providers/Filament/AdminPanelProvider.php

->path('manage')   // /manage に変更

または環境変数で管理：

->path(env('ADMIN_PATH', 'admin'))
# .env
ADMIN_PATH=xK9mP2admin

SPA モードの有効化

SPA（Single Page Application）モードを有効にすると、ページ遷移時にフルリロードせずLivewireのWireNavigateを使うため、体感速度が向上します。

// 📁 app/Providers/Filament/AdminPanelProvider.php

->spa()  // SPAモードを有効化

注意点：

  • ブラウザの戻るボタンの挙動が変わる場合がある
  • 一部のJavaScriptライブラリとの相性問題が発生することがある
  • 問題が起きた場合は ->spa(false) で無効化

セキュリティ設定

HTTPS 強制

<?php
// 📁 app/Providers/AppServiceProvider.php

use Illuminate\Support\Facades\URL;

public function boot(): void
{
    if (app()->environment('production')) {
        URL::forceScheme('https');
    }
}

Content Security Policy（CSP）

FilamentはLivewireを使うため、インラインスクリプトが必要です。CSPを設定する場合はnonceを使用します。

// 📁 app/Providers/Filament/AdminPanelProvider.php

->contentSecurityPolicy(
    "default-src 'self'; " .
    "script-src 'self' 'nonce-{nonce}'; " .
    "style-src 'self' 'nonce-{nonce}' https://fonts.googleapis.com; " .
    "font-src 'self' https://fonts.gstatic.com; " .
    "img-src 'self' data: blob:;"
)

{nonce} プレースホルダーは自動的にランダムな値に置換されます。

セッションの保護

# .env（本番環境）
SESSION_DRIVER=redis
SESSION_LIFETIME=120
SESSION_ENCRYPT=true

CACHE_STORE=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

よくあるエラーと解決法

エラー1: アセットが読み込まれない（404）

症状: 管理画面のCSSやJavaScriptが読み込まれず、レイアウトが崩れる。

原因と解決策:

# シンボリックリンクを再作成
php artisan storage:link

# アセットを再パブリッシュ
php artisan vendor:publish --tag=filament-assets --force

Nginx設定で public/ 以外のディレクトリへのアクセスを制限している場合：

# /etc/nginx/sites-available/myapp
location /vendor/ {
    alias /var/www/myapp/public/vendor/;
}

エラー2: CSRF Token Mismatch

症状: フォーム送信時に419エラーが発生する。

解決策:

# セッションドメインを正しく設定
SESSION_DOMAIN=.example.com
// config/session.php
'same_site' => 'lax',   // 'strict' だとリダイレクト後にセッションが切れる

エラー3: クラスが見つからない（Class not found）

症状: リソースを追加後に管理画面にアクセスできなくなる。

解決策:

# autoloadキャッシュを再生成
composer dump-autoload

# キャッシュをクリア
php artisan optimize:clear
php artisan filament:optimize-clear

エラー4: N+1問題によるタイムアウト

症状: 一覧ページを開くと非常に遅い、またはタイムアウトする。

解決策: リソースの getEloquentQuery() でeager loadingを設定します。

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()
        ->with(['category', 'author', 'tags']); // 必要なリレーションをwith
}

エラー5: ファイルアップロードが保存されない

症状: FileUpload コンポーネントでファイルを選んでも保存されない。

解決策:

# ストレージリンクを確認
php artisan storage:link
ls -la public/storage

# ディレクトリのパーミッションを確認
chmod -R 775 storage/
chmod -R 775 bootstrap/cache/
chown -R www-data:www-data storage/
FILESYSTEM_DISK=public

デプロイ後の動作確認手順

  1. /admin にアクセスできるか
  2. ログインできるか
  3. 各リソースの一覧・作成・編集・削除が動作するか
  4. ファイルアップロードが正常に保存されるか
  5. グローバル検索が動作するか
  6. ウィジェットのデータが表示されるか

シリーズのまとめ

このシリーズでは、FilamentPHP v5を使った管理画面開発の基礎から本番デプロイまでを10回にわたって解説しました。

回テーマ
第1回FilamentPHPのインストールと基本設定
第2回リソースの作成（テーブル・フォーム）
第3回フォームフィールドの全体像
第4回テーブルカラムとフィルター
第5回リレーション（BelongsTo・HasMany）
第6回フォームのレイアウトと条件付き制御
第7回ウィジェットとカスタムページ
第8回認証とアクセス制御
第9回グローバル検索とナビゲーション
第10回本番デプロイと最適化

次のステップ

Filamentをより深く使いこなすために、以下の公式ドキュメントを参考にしてください。

主なプラグイン例：

# スケジューラー管理
composer require solution-forest/filament-tree

# Excel/CSVエクスポート
composer require pxlrbt/filament-excel

# アクティビティログ
composer require rmsramos/activitylog

# 多言語対応
composer require filament/spatie-laravel-translatable-plugin

Filamentの開発体験は非常に快適で、一度使うと手放せなくなります。ぜひ実際のプロジェクトに取り入れてみてください。