doctrine-fetch-modes

Doctrine のフェッチモード（Symfony）

使用する場面

• リストまたは詳細エンドポイントが、関連に対して行ごとに 1 つのクエリを実行している（N+1 問題）。
• 読み取り専用のリストで、管理対象エンティティ全体ではなく、いくつかのカラムだけが必要な場合。
• マッピングで LAZY、EAGER、EXTRA_LAZY のいずれを選ぶか検討している場合、または PARTIAL オブジェクトに依存する ORM 2 のコードを移植する場合。
• レポートまたはプロジェクションクエリが DBAL 4 経由で生の SQL に切り替わる場合。

デフォルトのワークフロー

1. マッピングを変更する前に、Symfony プロファイラーで N+1 問題または過剰なデータ取得を確認します。
2. 関連は fetch: 'LAZY' のままにし、大きなコレクションには fetch: 'EXTRA_LAZY' を設定して、count()、contains()、slice() が対象を絞った SQL を実行するようにします。
3. リポジトリでフェッチ結合（addSelect() と leftJoin()）を使い、ユースケースで必要な関連を読み込みます。
4. 読み取り専用のリストでは、SELECT NEW を使って readonly DTO にプロジェクションします（コンストラクター引数の順序は NEW リストと一致させる必要があります）。
5. 結果を表示するだけ、または ID で検索するだけの場合は、Query::HINT_READ_ONLY またはインデックス付きエイリアス（createQueryBuilder('p', 'p.id')）を使います。
6. 生の SQL には、DBAL 4 のメソッド（fetchAllAssociative()、fetchOne()、executeStatement()）を使います。

ガードレール

• DQL の PARTIAL は ORM 3.0～3.2 では失敗し、3.3 以降でのみ結果を返します。代わりに、読み取り専用リストには SELECT NEW DTO を使います。
• マッピングでの fetch: 'EAGER' は避けます。クエリのフェッチ結合で、ユースケースごとに同じ結果を得られます。
• SELECT NEW が返すのは DTO であり、管理対象エンティティではありません。変更したり、フラッシュしたりしないでください。
• DBAL 4 では query()、exec()、fetchAll() が削除されています。

段階的な情報開示

• 実行時の方針とリスク管理には、このファイルを使用します。
• 実装の詳細が必要な場合は、リファレンスを開きます。

出力要件

• ユースケースごとにフェッチ戦略を選択したリポジトリメソッド。
• DTO クラスと、それらに値を設定する SELECT NEW クエリ。
• プロファイラーまたは doctrine:query:dql --show-sql で確認した変更前後のクエリ数。

リファレンス

• reference.md