Laravel 13 ベストプラクティス

Laravel 13 アプリケーション向けの包括的なベストプラクティスガイド。スケーラブルで保守性の高い Laravel アプリケーション構築のための 7 カテゴリ全 31 ルールを含みます。

適用するタイミング

以下の場合にこのガイドラインを参照してください:

• コントローラー、モデル、サービスの作成
• マイグレーションおよびデータベースクエリの記述
• バリデーションとフォームリクエストの実装
• Laravel による API 構築
• Laravel アプリケーションの構造化

ルールカテゴリ（優先度順）

優先度	カテゴリ	影響度	プレフィックス
1	アーキテクチャと構造	重大	arch-
2	Eloquent とデータベース	重大	eloquent-
3	コントローラーとルーティング	高	controller-, ctrl-
4	バリデーションとリクエスト	高	validation-, valid-
5	セキュリティ	高	sec-
6	パフォーマンス	中	perf-
7	API 設計	中	api-

クイックリファレンス

1. アーキテクチャと構造（重大）

• arch-service-classes - ビジネスロジックをサービスに抽出
• arch-action-classes - 単一目的のアクションクラス
• arch-repository-pattern - リポジトリパターンの使用時期
• arch-dto-pattern - データ転送オブジェクト
• arch-value-objects - ドメイン概念のカプセル化
• arch-event-driven - イベントとリスナーで疎結合化
• arch-feature-folders - ドメイン/機能別に整理
• arch-queue-routing - 一元化されたジョブキューのルーティング (Laravel 13+)

2. Eloquent とデータベース（重大）

• eloquent-eager-loading - N+1 クエリを防止
• eloquent-chunking - 大規模データセットの処理
• eloquent-query-scopes - 再利用可能なクエリロジック
• eloquent-model-events - 副作用に Observer を使用
• eloquent-relationships - リレーションシップを適切に定義
• eloquent-casts - 属性の自動キャスティング
• eloquent-accessors-mutators - 属性の変換
• eloquent-soft-deletes - 復旧可能な安全な削除
• eloquent-pruning - 古いレコードの自動クリーンアップ
• eloquent-vector-search - pgvector を使用したセマンティック検索 (Laravel 13+)

3. コントローラーとルーティング（高）

• controller-resource-controllers - リソースコントローラーの使用
• controller-single-action - 単一アクション呼び出し可能コントローラー
• controller-resource-methods - REST リソースメソッド
• controller-form-requests - フォームリクエストの使用
• controller-api-resources - API レスポンスの変換
• controller-middleware - ミドルウェアの適切な適用
• controller-dependency-injection - 依存性の注入

4. バリデーションとリクエスト（高）

• validation-form-requests - フォームリクエストクラスの使用
• validation-custom-rules - カスタムルールの作成
• validation-conditional-rules - 条件付きバリデーション
• validation-array-validation - ネストされた配列のバリデーション
• validation-after-hooks - 複雑なバリデーションロジック

5. セキュリティ（高）

• sec-mass-assignment - 大量割り当てから保護

6. パフォーマンス（中）

このカテゴリのルールファイルはまだ存在しません。

7. API 設計（中）

このカテゴリのルールファイルはまだ存在しません。

必須パターン

フォームリクエスト付きコントローラー

<?php

namespace App\Http\Controllers;

use App\Http\Requests\StorePostRequest;
use App\Http\Requests\UpdatePostRequest;
use App\Models\Post;
use Illuminate\Http\RedirectResponse;

class PostController extends Controller
{
    public function store(StorePostRequest $request): RedirectResponse
    {
        // バリデーションは自動的に実行されます
        $validated = $request->validated();

        $post = Post::create($validated);

        return redirect()
            ->route('posts.show', $post)
            ->with('success', 'Post created successfully.');
    }

    public function update(UpdatePostRequest $request, Post $post): RedirectResponse
    {
        $post->update($request->validated());

        return redirect()
            ->route('posts.show', $post)
            ->with('success', 'Post updated successfully.');
    }
}

フォームリクエストクラス

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()->can('create', Post::class);
    }

    public function rules(): array
    {
        return [
            'title' => ['required', 'string', 'max:255'],
            'body' => ['required', 'string', 'min:100'],
            'category_id' => ['required', 'exists:categories,id'],
            'tags' => ['nullable', 'array'],
            'tags.*' => ['exists:tags,id'],
            'published_at' => ['nullable', 'date', 'after:now'],
        ];
    }

    public function messages(): array
    {
        return [
            'body.min' => 'The post body must be at least 100 characters.',
        ];
    }
}

サービスクラスパターン

<?php

namespace App\Services;

use App\Models\User;
use App\Models\Post;
use App\Events\PostPublished;
use Illuminate\Support\Facades\DB;

class PostService
{
    public function __construct(
        private readonly NotificationService $notifications,
    ) {}

    public function publish(Post $post): Post
    {
        return DB::transaction(function () use ($post) {
            $post->update([
                'published_at' => now(),
                'status' => 'published',
            ]);

            event(new PostPublished($post));

            $this->notifications->notifyFollowers($post->author, $post);

            return $post->fresh();
        });
    }
}

Eloquent モデル

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Builder;

class Post extends Model
{
    use HasFactory;

    protected $fillable = [
        'title',
        'slug',
        'body',
        'category_id',
        'published_at',
    ];

    protected $casts = [
        'published_at' => 'datetime',
    ];

    // リレーションシップ
    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }

    public function category(): BelongsTo
    {
        return $this->belongsTo(Category::class);
    }

    public function tags(): BelongsToMany
    {
        return $this->belongsToMany(Tag::class)->withTimestamps();
    }

    // スコープ
    public function scopePublished(Builder $query): Builder
    {
        return $query->whereNotNull('published_at')
            ->where('published_at', '<=', now());
    }

    public function scopeByCategory(Builder $query, int $categoryId): Builder
    {
        return $query->where('category_id', $categoryId);
    }

    // アクセサーとミューテーター
    protected function title(): Attribute
    {
        return Attribute::make(
            set: fn (string $value) => ucfirst($value),
        );
    }
}

マイグレーションのベストプラクティス

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->foreignId('category_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->string('slug')->unique();
            $table->text('body');
            $table->timestamp('published_at')->nullable();
            $table->timestamps();

            // 一般的なクエリのためのインデックス
            $table->index(['user_id', 'published_at']);
            $table->index('category_id');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

Eager Loading

// N+1 問題
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->author->name;  // ポストごとに 1 クエリ
}

// Eager loading — 合計 3 クエリのみ
$posts = Post::with(['author', 'category', 'tags'])->get();
foreach ($posts as $post) {
    echo $post->author->name;  // 追加のクエリなし
}

// ネストされた eager loading
$posts = Post::with([
    'author.profile',
    'comments.user',
    'tags',
])->get();

// 制約付き eager loading
$posts = Post::with([
    'comments' => fn ($query) => $query->latest()->limit(5),
])->get();

使用方法

詳細な説明とコード例については、個別のルールファイルを参照してください:

rules/arch-service-classes.md
rules/eloquent-eager-loading.md
rules/validation-form-requests.md
rules/_sections.md

各ルールファイルには以下が含まれます:

• メタデータ(タイトル、影響度、タグ)を含む YAML frontmatter
• それが重要である理由の簡潔な説明
• 説明付きの悪い例
• 説明付きの良い例
• Laravel 13 と PHP 8.3 固有のコンテキストと参照

完全にコンパイルされたドキュメント

すべてのルール展開を含む完全なガイド: AGENTS.md