laravel-architecture

Laravel アプリケーションのアーキテクチャ全体を網羅します。プロジェクト構成 （Actions、Contracts、DTOs、Services、Repositories のレイアウト）、サービス コンテナと依存性注入、サービスプロバイダーとファサード、 環境設定、開発環境（Sail、Valet、Homestead、 Octane）、Artisan CLI、ファイルシステム／プロセス／コンテキスト、機能フラグ（Pennant）、 MCP サーバー、並行処理、本番環境へのデプロイ（Envoy、 ロギング、エラー処理、パッケージ作成を含む）を扱います。

Laravel アーキテクチャパターン

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

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

1. fuse-ai-pilot:explore-codebase - 既存のアーキテクチャを分析します
2. fuse-ai-pilot:research-expert - Context7 で Laravel のパターンを検証します
3. mcp__context7__query-docs - サービスコンテナと DI のパターンを確認します

実装後、検証のために fuse-ai-pilot:sniper を実行します。

---

概要

Laravel のアーキテクチャでは、関心事の明確な分離、依存性注入、保守しやすいコード構成を重視します。このスキルでは、プロジェクト構成から本番環境へのデプロイまで、あらゆる内容を扱います。

使用する場面

• 新しい Laravel プロジェクトを構成する
• サービス、リポジトリ、アクションを実装する
• 依存性注入を設定する
• 開発環境を構成する
• 本番環境にデプロイする

---

重要なルール

1. コントローラーは薄く保つ - ビジネスロジックはサービスに委譲します
2. インターフェースは app/Contracts/ に配置する - 実装と同じ場所に置かないでください
3. ファサードより DI を優先する - テストしやすいようにコンストラクターインジェクションを使用します
4. ファイルは FUSE_SOLID_MAX_LINES 以内に収める - SOLID に従い、大きなファイルは分割します
5. 環境を分離する - .env はコミットしません

---

アーキテクチャ

app/
├── Actions/              # Single-purpose action classes
├── Contracts/            # Interfaces (DI)
├── DTOs/                 # Data transfer objects
├── Enums/                # PHP 8.1+ enums
├── Events/               # Domain events
├── Http/
│   ├── Controllers/      # Thin controllers
│   ├── Middleware/       # Request filters
│   ├── Requests/         # Form validation
│   └── Resources/        # API transformations
├── Jobs/                 # Queued jobs
├── Listeners/            # Event handlers
├── Models/               # Eloquent models only
├── Policies/             # Authorization
├── Providers/            # Service registration
├── Repositories/         # Data access layer
└── Services/             # Business logic

---

リファレンスガイド

コアアーキテクチャ

リファレンス	使用する場面
container.md	依存性注入、バインド、解決
providers.md	サービスの登録、ブートストラップ
facades.md	静的プロキシ、リアルタイムファサード
contracts.md	インターフェース、疎結合
structure.md	ディレクトリ構成
lifecycle.md	リクエスト処理の流れ

設定とセットアップ

リファレンス	使用する場面
configuration.md	環境、設定ファイル
installation.md	新規プロジェクトのセットアップ
upgrade.md	バージョンアップ、破壊的変更
releases.md	リリースノート、バージョン管理

開発環境

リファレンス	使用する場面
sail.md	Docker 開発
valet.md	macOS ネイティブ開発
homestead.md	Vagrant（レガシー）
octane.md	高性能サーバー

ユーティリティとツール

リファレンス	使用する場面
artisan.md	CLI コマンド、カスタムコマンド
helpers.md	グローバルヘルパー関数
filesystem.md	ファイルストレージ、S3、ローカル
processes.md	シェルコマンドの実行
context.md	リクエストスコープのデータ共有

高度な機能

リファレンス	使用する場面
pennant.md	機能フラグ
mcp.md	Model Context Protocol
concurrency.md	並列実行

操作

リファレンス	使用するタイミング
deployment.md	本番環境へのデプロイ
envoy.md	SSH タスクの自動化
logging.md	ログチャンネル、フォーマット
errors.md	例外処理
packages.md	パッケージの作成

---

テンプレート

テンプレート	目的
UserService.php.md	サービス + リポジトリパターン
AppServiceProvider.php.md	DI バインディング、ブートストラップ
ArtisanCommand.php.md	CLI コマンド、シグネチャ、I/O
McpServer.php.md	MCP サーバー、ツール、リソース、プロンプト
PennantFeature.php.md	フィーチャーフラグ、A/B テスト
Envoy.blade.php.md	SSH デプロイの自動化
sail-config.md	Docker Sail の設定
octane-config.md	FrankenPHP、Swoole、RoadRunner

---

機能マトリクス

機能	リファレンス	優先度
サービスコンテナ	container.md	高
サービスプロバイダー	providers.md	高
ディレクトリ構造	structure.md	高
設定	configuration.md	高
インストール	installation.md	高
Octane (パフォーマンス)	octane.md	高
Sail (Docker)	sail.md	高
Artisan CLI	artisan.md	中
デプロイ	deployment.md	中
Envoy (SSH)	envoy.md	中
ファサード	facades.md	中
コントラクト	contracts.md	中
Valet (macOS)	valet.md	中
アップグレードガイド	upgrade.md	中
ログ	logging.md	中
エラー	errors.md	中
ライフサイクル	lifecycle.md	中
ファイルシステム	filesystem.md	中
ヘルパー	helpers.md	低
Pennant (フラグ)	pennant.md	低
コンテキスト	context.md	低
プロセス	processes.md	低
並行処理	concurrency.md	低
MCP	mcp.md	低
パッケージ	packages.md	低
リリース	releases.md	低
Homestead	homestead.md	低

---

クイックリファレンス

サービスのインジェクション

public function __construct(
    private readonly UserServiceInterface $userService,
) {}

サービスプロバイダーのバインディング

public function register(): void
{
    $this->app->bind(UserServiceInterface::class, UserService::class);
    $this->app->singleton(CacheService::class);
}

Artisan コマンド

php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders

環境変数へのアクセス

$debug = env('APP_DEBUG', false);
$config = config('app.name');

---

Laravel 13 の注意事項

更新されたスタック

• Symfony 7.4 と 8.0 を同時にサポート (HttpFoundation、Console、Mailer)
• PHP 8.3 以上が必須 (8.2 はサポート終了)
• Beanstalk ドライバーには pda/pheanstalk 7.x / 8.x が必要 (5.x はサポート終了)
• 現在の安定版: 13.33 (2026 年 9 月)

Cache::touch() API

値を再計算せずに TTL を更新する新しいメソッドです。

Cache::touch('user:123', 3600);
Cache::touch('user:123', now()->addHour());

動的ルーティングのための Queue::route()

ジョブクラスごとの宣言的ルーティング (Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts')) と Queue::forward() (13.26 以降) については [[laravel-queues]] を参照してください。

ネストされたモデルの boot → LogicException

Laravel 13 では、モデルが自身の boot 中にインスタンス化されると (モデルの boot()またはトレイトのboot*()内でのnew static())、LogicException` がスローされます。そのロジックは boot サイクルの外に移動してください。

13.x の新機能 (13.1 → 13.33)

• php artisan dev (13.16 以降): サーバー、queue:listen、Pail、Vite を 1 つのターミナルで実行します。AppServiceProvider::boot() 内の Illuminate\Foundation\DevCommands::artisan('horizon', 'horizon') でカスタマイズでき、php artisan dev:list で一覧表示できます (Node 22.13 以上が必要)
• #[BindWhen(Impl::class, static fn () => ...)] (13.22 以降): インターフェース上で宣言する条件付きバインディング — PHP 8.5 が必要
• ほとんどのマネージャー (Cache::store()、Queue、Log、Mail、Auth::guard() など) で Enum (UnitEnum) をサポート (13.3 → 13.7)
• Guzzle 8 をサポート (13.26 以降)

Laravel 12 → 13 への移行

トピック	変更前 (12)	変更後 (13)
PHP の最小バージョン	8.2	8.3
PHPUnit	11	12 (13 もサポート)
Pest	3	4 (PHP 8.4 以上では 5)
CSRF	VerifyCsrfToken	PreventRequestForgery (Sec-Fetch-Site によるオリジンチェック)
キャッシュプレフィックス	アンダースコア	デフォルトでハイフン (後方互換性のために CACHE_PREFIX、REDIS_PREFIX、SESSION_COOKIE を設定)
Beanstalk	pheanstalk 5.x	pheanstalk 7.x / 8.x
Symfony	7.x	7.4 / 8.0
モデルの boot	許容されていた	モデルの boot 中のネストされたインスタンス化 → LogicException
Config	—	新しい cache.serializable_classes (許可リストによるハードニング、デフォルトは false)

# Backward-compatible cache prefixes when upgrading from L12
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session

// config/cache.php — deserialization hardening
'serializable_classes' => [
    App\DTO\PaymentDto::class,
    App\DTO\OrderDto::class,
],

ベストプラクティス

推奨

• DTO と値オブジェクトには final readonly class を使用する (PHP 8.3 以上)
• コンストラクタプロモーション + interface による注入 (依存関係の逆転)
• ジョブやリクエストをまたいでメタデータを伝播するには Context::add() でログを記録する
• 本番環境では serializable_classes を設定する
• App::make() よりも app(Contract::class) を優先する (厳密な型付け)

非推奨

• モデル自身の boot 中にモデルをインスタンス化する (boot() 内の new static() → L13 では LogicException)
• 絶対パスをハードコードする (base_path()、storage_path() を使用する)
• Repository と Service を混在させる (責務ごとに1つ)
• new ConcreteClass() でコンテナをバイパスする
• L12 からのアップグレード時にキャッシュプレフィックスの変更を無視する