laravel-permission

Spatie Laravel Permission によるロールベースのアクセス制御を扱います。ロールと権限、ルートミドルウェア、Blade の認可ディレクティブ、マルチテナントのチームスコープ、ワイルドカード／階層型の権限、スーパー管理者によるバイパス、キャッシュ管理、直接権限とロール権限の継承、クエリスコープ、イベントベースの監査ログ、Policy との統合、Sanctum／Passport の API 利用、カスタムモデル（UUID サポート）、テストパターンを取り上げます。

Laravel Permission（Spatie）

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

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

1. fuse-ai-pilot:explore-codebase - 既存の認証パターンを確認する
2. fuse-ai-pilot:research-expert - Context7 経由で Spatie Permission のドキュメントを確認する
3. mcp__context7__query-docs - Laravel の認可パターンを確認する

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

---

概要

Spatie Laravel Permission は、Laravel アプリケーション向けにロールベースのアクセス制御（RBAC）を包括的に提供します。

コンポーネント	目的
ロール	権限のグループ（admin、writer）
権限	個別の操作権限（記事の編集）
ミドルウェア	ルートの保護
Blade ディレクティブ	UI の認可
チーム	マルチテナントのスコープ設定
ワイルドカード	階層型の権限
スーパー管理者	すべてのチェックをバイパス
イベント	監査ログ（v6.15.0+）
クエリスコープ	ロール／権限によるユーザーの絞り込み
API サポート	Sanctum／Passport との統合
ポリシー	リソースベースの認可

---

重要なルール

1. DatabaseSeeder でロール／権限をシードする
2. 変更後にキャッシュをリセットする：php artisan permission:cache-reset
3. 名前にはケバブケースを使用する：edit-articles
4. コントローラーにロールチェックをハードコードしない - ミドルウェアを使用する
5. マルチテナントアプリでは、リクエストの早い段階でチームコンテキストを設定する
6. API ではガードを指定する - permission:edit,api
7. テストでキャッシュをクリアする - setUp()/beforeEach() でリセットする

---

リファレンスガイド

基本概念

トピック	リファレンス	参照するタイミング
セットアップ	spatie-permission.md	インストール、モデルのセットアップ、基本メソッド
ミドルウェア	middleware.md	ルート保護のパターン
Blade	blade-directives.md	UI の認可ディレクティブ
直接権限とロール権限	direct-permissions.md	権限の継承

高度な機能

トピック	リファレンス	参照するタイミング
チーム	teams.md	マルチテナントの権限
ワイルドカード	wildcard-permissions.md	階層型のパターン
スーパー管理者	super-admin.md	すべての権限をバイパス
カスタムモデル	custom-models.md	UUID、モデルの拡張

統合

トピック	リファレンス	参照するタイミング
API の利用	api-usage.md	Sanctum、ガード、JSON レスポンス
ポリシー	policies.md	Laravel Policy との統合
クエリスコープ	query-scopes.md	User::role()、User::permission()
イベント	events.md	監査ログ、通知

運用と品質

トピック	リファレンス	参照するタイミング
キャッシュ	cache.md	パフォーマンス、デバッグ
CLI	artisan-commands.md	Artisan コマンド
テスト	testing.md	テスト、ファクトリー、セットアップ
パフォーマンス	performance.md	最適化、N+1、キャッシュ

---

テンプレート（コード例）

セットアップとシーディング

テンプレート	目的
UserModel.php.md	HasRoles トレイトを使用するユーザーモデル
RoleSeeder.php.md	基本的なロールのシーディング
PermissionSeeder.php.md	権限を作成するシーダー
WildcardSeeder.php.md	階層型権限

ルートとミドルウェア

テンプレート	目的
routes-example.md	保護されたルートの例
ControllerMiddleware.php.md	コントローラー内のミドルウェア
BladeExamples.blade.md	Blade ディレクティブの例

チームとマルチテナント

テンプレート	目的
TeamMiddleware.php.md	マルチテナント用ミドルウェア
TeamSeeder.php.md	チームスコープのロール用シーダー
TeamModel.php.md	boot を含むチームモデル

スーパー管理者とキャッシュ

テンプレート	目的
SuperAdminSetup.php.md	Gate::before によるバイパス
CacheConfig.php.md	キャッシュ設定
DeployScript.sh.md	CI/CD のキャッシュ管理

API 連携

テンプレート	目的
ApiPermissionSetup.php.md	API ガードと Sanctum
ApiExceptionHandler.php.md	JSON エラーレスポンス
ApiUserResource.php.md	権限を含むユーザーリソース

ポリシーとイベント

テンプレート	目的
PostPolicy.php.md	Spatie 連携を含むポリシー
PermissionEventListener.php.md	監査イベントリスナー
UserQueryExamples.php.md	クエリスコープの例
PermissionAudit.php.md	監査サービス

テスト

テンプレート	目的
PermissionTest.php.md	Pest と PHPUnit のテスト
UserFactory.php.md	権限の状態を含むファクトリー

カスタムモデル

テンプレート	目的
CustomRole.php.md	拡張された Role モデル
CustomPermission.php.md	拡張された Permission モデル
UUIDMigration.php.md	UUID テーブルのマイグレーション
SetupPermissions.php.md	カスタム artisan コマンド

---

クイックリファレンス

ロールの割り当て

$user->assignRole('admin');

権限の確認

$user->can('edit articles');

ミドルウェア（Web）

Route::middleware(['role:admin'])->group(fn () => ...);

ミドルウェア（API）

Route::middleware(['auth:sanctum', 'permission:edit,api'])->group(fn () => ...);

Blade

@role('admin') ... @endrole
@can('edit articles') ... @endcan

クエリスコープ

User::role('admin')->get();
User::permission('edit articles')->get();

チーム

setPermissionsTeamId($team->id);

ワイルドカード

$role->givePermissionTo('articles.*');

スーパー管理者

Gate::before(fn ($user, $ability) =>
    $user->hasRole('Super-Admin') ? true : null
);

テスト

beforeEach(fn () => app(PermissionRegistrar::class)->forgetCachedPermissions());

---

機能マトリックス

機能	状態	参照
基本的な RBAC	✅	spatie-permission.md
ミドルウェア	✅	middleware.md
Blade ディレクティブ	✅	blade-directives.md
マルチガード（web/api）	✅	middleware.md, api-usage.md
チーム（マルチテナント）	✅	teams.md
ワイルドカード権限	✅	wildcard-permissions.md
スーパー管理者	✅	super-admin.md
キャッシュ管理	✅	cache.md
直接権限とロール権限	✅	direct-permissions.md
Artisan コマンド	✅	artisan-commands.md
UUID サポート	✅	custom-models.md
カスタムモデル	✅	custom-models.md
イベント（v6.15.0+）	✅	events.md
クエリスコープ	✅	query-scopes.md
ポリシー統合	✅	policies.md
API / Sanctum	✅	api-usage.md
テスト	✅	testing.md
パフォーマンス	✅	performance.md

---

Laravel 13 に関する注意事項

Spatie Permission 8.x（現在のバージョンは 8.3。PHP 8.3 以降と Laravel 12/13 が必要）は Laravel 13 に対応しています。L13 との統合：

• v6 → v7 → v8 へのアップグレード：イベントクラスには Event が付加され（RoleAttachedEvent…）、コマンドには Command が付加されます。clearClassPermissions() は削除され、findByName() / findOrCreate() は BackedEnum|string を受け付けます（v8）。events.md を参照してください。
• キャッシュ：permission.cache.key キーは config/permission.php 内で明示的に (spatie.permission.cache) 設定されます → L13 でハイフン区切りのプレフィックスに変更されても影響を受けません。
• コントローラー属性：#[Authorize]（ポリシー）と #[Middleware('role:admin')]（RBAC）を組み合わせます。名前空間は Illuminate\Routing\Attributes\Controllers です。[[laravel-blade]] を参照してください。
• PHP 8.3：カスタムの Role/Permission DTO には final readonly class を使用します。

#[Middleware(['auth', 'role:admin|editor'])]
#[Authorize('update', 'post')]
public function update(UpdatePostRequest $request, Post $post) { /* ... */ }

ベストプラクティス

推奨事項

• 真実の単一の情報源を定義します。同じアクションに対して Policy または Permission のどちらか一方を使い、両方は使いません。
• 明確さのために permission:create-post（動詞-名詞）を使用します。
• マルチテナンシーが実際に必要な場合にのみ teams を有効にします。
• ユーザーごとに権限をキャッシュします（Cache::remember('user.permissions.'.$id, ...)）。
• スーパー管理者には Gate::before() を使用します（* ワイルドカード権限は使用しません）。

避けるべきこと

• 権限をセッションに保存しないでください（Spatie のキャッシュを使用します）。
• 一貫したアーキテクチャなしに hasRole() と hasPermissionTo() を併用しないでください。
• ロール名をコードにハードコードしないでください（RoleEnum 列挙型を使用します）。
• シーダーで assignRole() を実行した後に、キャッシュをフラッシュするのを忘れないでください。
• スーパー管理者に * を付与しないでください（対象を絞った Gate::before() を優先します）。