laravel-best-practices

Laravel のベストプラクティス

Laravel のベストプラクティスを、ルールファイルのインデックスとしてまとめています。各ルールファイルでは、何をすべきか、そしてその理由を説明します。正確な API 構文は、search-docs で確認してください。

まず一貫性を重視する

ルールを適用する前に、アプリケーションですでにどのように実装されているかを確認してください。Laravel には有効なアプローチがいくつかあります。理論上は別のパターンのほうが優れていても、コードベースですでに使われているものが最善の選択です。一貫性の欠如は、最適でないパターンよりも問題です。

既存のパターンがあるか、同じ階層のファイルや関連するコントローラー、モデル、テストを確認してください。パターンが見つかったら、それに従ってください。同じ目的に別の方法を導入しないでください。これらのルールは、まだパターンが存在しない場合のデフォルトであり、既存のパターンを覆すものではありません。

適用方法

1. 変更するファイル、周辺のコード、プロジェクト設定、関連するテストを確認し、既存のパターンを把握してください。正確性またはセキュリティ上の欠陥がある場合に限り、既存のパターンから逸脱し、その理由を明記してください。
2. 影響するすべての懸念事項を、以下のルールインデックスに対応付けてください。編集前に、対応するルールファイルをすべて読んでください。無関係なルールファイルは読み飛ばしてください。
3. 一貫性のある最小限の変更にしてください。同じ目的に別のパターンを導入するのではなく、アプリケーションのアーキテクチャと命名規則を維持してください。
4. バージョンに依存する Laravel API は、インストールされているバージョンに合わせて search-docs で確認してください。search-docs を利用できない場合は、インストール済みのフレームワークを調べてください。
5. まず、関連する範囲を絞ったテストを実行してください。変更に応じて、プロジェクトのフォーマッターと静的解析チェックも実行してください。
6. 作業を終える前に、対応するすべてのルールと照らし合わせて差分を再確認してください。

ルールインデックス

複数の領域にまたがる変更では、複数のルールファイルを参照する必要がある場合があります。

懸念事項	参照先
クエリ数、Eager Loading、インデックス、大規模データセット	rules/db-performance.md
サブクエリ、集計、複雑な並べ替え、クエリプラン	rules/advanced-queries.md
モデル、リレーション、スコープ、キャスト	rules/eloquent.md
認証、認可、入力の安全性、シークレット、アップロード	rules/security.md
Form Request とバリデーションルール	rules/validation.md
コントローラー、ルートバインディング、リソース、ミドルウェア	rules/routing.md
スキーマ変更、カラム、外部キー、インデックス	rules/migrations.md
ジョブ、再試行、一意性、バッチ、Horizon	rules/queue-jobs.md
キャッシュの有効期間、無効化、ロック、メモ化	rules/caching.md
外部へのリクエスト、再試行、タイムアウト、フェイク	rules/http-client.md
例外、レポート、レンダリング、ログコンテキスト	rules/error-handling.md
イベントと通知	rules/events-notifications.md
Mailable とメールのアサーション	rules/mail.md
スケジュールタスクと重複実行の防止	rules/scheduling.md
コレクション、遅延イテレーション、一括操作	rules/collections.md
Blade コンポーネント、属性、コンポーザー	rules/blade-views.md
環境値とアプリケーション設定	rules/config.md
テスト：カバレッジ、ファクトリー、フェイク、アサーション	testing-best-practices スキル
命名、ヘルパー、ファイルの責務範囲、PHP スタイル	rules/style.md
アクション、サービス、依存関係、アプリケーション構成	rules/architecture.md

判断ルール

• 新しいヘルパーや依存関係を追加するよりも、フレームワークの機能と既存のアプリケーション抽象化を優先してください。
• 先回りした抽象化は避けてください。明確なドメイン境界を作る、有意義な重複を取り除く、または振る舞いを個別にテストしやすくする場合に、コードを切り出してください。
• Blade ビューでデータベースにアクセスしないようにし、コントローラー、リソース、ジョブ、シリアライズ処理をまたいだ、隠れた N+1 クエリを防いでください。