symfony-components

Symfony コンポーネント

Symfony は年に 2 回、マイナーリリースを公開し、API も変化します。このスキルでは API をそのまま説明し直すことはしません。使用中のバージョンの確認方法、そのバージョンに対応する正確な API の参照先、ドキュメントに複数の選択肢がある場合に優先するデフォルト、そして実際のプロジェクトで繰り返し発生する間違いを説明します。

基本原則

原則	意味
まずバージョンを確認	API を提案する前に、インストール済みのバージョンを確認します。「Symfony 7」という記憶は古くなっていることがよくあります。
記憶よりドキュメント	必要なコンポーネントとバージョンのページを取得します。記憶を頼りに API を貼り付けないでください。
アトリビュートとオートワイヤリング	PHP アトリビュートとオートワイヤリングを優先します。アトリビュートで表現できない場合に限り、YAML または XML を使用します。
明確に失敗し、長時間実行に対応	長時間稼働するワーカーでも動作するコードにします。状態を漏らさず、ハンドラーを冪等にします。
非推奨事項ゼロ	非推奨の通知は、次のメジャーバージョンへのアップグレード経路として捉えます。

ステップ 1：インストール済みのバージョンを確認する

composer.json の制約（^7.2 だけでは多くのことは分かりません）ではなく、composer.lock から読み取ります。

jq -r '.packages[] | select(.name|test("^symfony/(framework-bundle|http-kernel)$")) | .name+" "+.version' composer.lock

また、composer.json の php 制約と CLI のバージョンも確認します。6.4 や 7.4 のプロジェクトと 8.1 のプロジェクトでは、必要な回答が異なります。アトリビュート名は変更され、機能が追加され、8.0 で削除された API もあります。

バージョン一覧

https://symfony.com/releases に基づき、2026-10-21 に確認済みです。

ブランチ	ステータス	最小 PHP バージョン	サポート終了
8.1	現在の安定版、LTS ではありません	8.4	2027 年 1 月（バグ修正とセキュリティ修正）
8.2	開発中、2026 年 11 月にリリース予定	8.4	2027 年 7 月
7.4	LTS	8.2	バグ修正：2028 年 11 月、セキュリティ修正：2029 年 11 月
6.4	LTS	8.1	バグ修正：2026 年 11 月、セキュリティ修正：2027 年 11 月
8.0	メンテナンス終了	8.4	2026 年 7 月に終了
5.4	セキュリティ修正のみ	7.2.5	2029 年 2 月

目安：

• メジャーバージョン内のマイナーバージョンは LTS ではなく、約 8 か月間サポートされます。LTS バージョンは末尾が .4 です。このパターンに従うと、次の LTS は 8.4 です（リリースページでは未確認です）。
• 7.4 から 8.x への移行には、まず PHP 8.4 への移行が必要です。7.4 または 6.4 のプロジェクトでは、8.x のみで使える構文を書かないでください。
• ベースラインとして「PHP 8.3 以上」や「Symfony 7.x」と記載しないでください。プロジェクト固有の制約を使用します。

ステップ 2：docs-lookup で API の詳細を取得する

取得手順には docs-lookup スキルを使用します。インストールされていない場合は、同じルールに従う任意のドキュメントツールを使用します。ライブラリを特定し、1 回のクエリにつき 1 つの概念を検索し、結果のバージョンに関する注記を確認してください。

ソース	Context7 ID	用途
現在のドキュメントサイト	/websites/symfony_doc_current	最新の安定版の動作
ドキュメント、指定ブランチ	/symfony/symfony-docs/__branch__X.Y	特定バージョンを使用するプロジェクト
ドキュメント、7.4 サイト	/websites/symfony_doc_7_4	7.4 のプロジェクト
ドキュメント、広範なインデックス	/websites/symfony	他のソースでトピックが見つからない場合の代替

2026-10-21 時点で存在していた指定ブランチは 6.4、7.4、8.0 です。8.1 ブランチはなかったため、8.1 では現在のドキュメント ID を使用します。ソースリポジトリのドキュメントは /symfony/symfony にもあります（同日時点のタグは v8.0.0、v7.4.3）。

注意すべき点：

• 現在のドキュメント ID の検索結果には、7.4 以前向けのページが含まれることがあります。「introduced in」や「deprecated in」の注記を確認し、インストール済みのバージョンと照らし合わせてください。
• 8.1 で動作するコード例でも、プロジェクトの PHP では実行できない構文が使われている場合があります（たとえば、括弧なしで new を連結する構文には PHP 8.4 が必要です）。
• ツールで該当する結果が見つからない場合は、特定のブランチについて https://symfony.com/doc/X.Y/ を参照してください。

1 回のクエリでは、1 つのコンポーネントと 1 つの概念を検索してください。たとえば「Messenger のリトライ戦略と失敗時のトランスポート」のように指定し、「Messenger と Cache と Forms」のようにまとめて検索しないでください。

独自の推奨デフォルト

ドキュメントにはさまざまなオプションが記載されています。ユーザーから別の指定がない場合は、次の選択肢を使ってください。

• ルート、コマンド（#[AsCommand]）、ハンドラー（#[AsMessageHandler]）、リスナー（#[AsEventListener]）、バリデーション、シリアライザーグループには、YAML/XML よりも属性を優先します。config/packages とサービスパラメーターには YAML を使います。
• アプリケーションサービスには、オートワイヤリングとオートコンフィギュレーションを使います。スカラー引数、インターフェースの特定の実装、またはデフォルト以外のタグが必要な場合に限り、サービスを手動で登録します。
• コンストラクターインジェクションを使い、サービスはプライベートにします。アプリケーションコードでは ContainerInterface を使いません。複数のサービス群が必要な場合は、サービスロケーターまたは #[AutowireIterator] を注入します。
• Workflow コンポーネントでは、デフォルトでステートマシンを使います。オブジェクトが複数の場所に同時に存在する必要がある場合にのみ、完全なワークフローを使います。場所には PHP enum を使います。
• キャッシュには、生の PSR-6 よりも Cache Contracts（$cache->get($key, $callback)）を使います。スタンピード保護と早期有効期限切れに対応できます。必ず TTL を設定し、依存関係ごとにタグを付け、タグを使って無効化します。
• Messenger では、ハンドラーを冪等にし（配信は少なくとも 1 回行われます）、メッセージにはエンティティではなく識別子を含め、コマンドバスに doctrine_transaction ミドルウェアを設定し、失敗時のトランスポートとワーカーの制限（--time-limit、--memory-limit）を設けます。
• Form の CollectionType には、allow_add、allow_delete、by_reference: false が必要です。また、モデルに追加用メソッドと削除用メソッドの両方が必要です。削除用メソッドがないと、削除した行が再び表示されます。
• Validator では、属性を使ってモデルに制約を設定し、コンテキスト固有のルールにはバリデーショングループを使います。カスタムバリデーターは null と空の値なら早期に返すようにします（その処理は NotBlank と NotNull に任せます）。
• Serializer では、シリアライザーグループまたは DTO を使って API 出力を公開します。Doctrine エンティティ全体をシリアライズしてはいけません。エンティティから DTO へのマッピングは明示的に行います（そのための ObjectMapper コンポーネントがあります）。
• Security では、オブジェクトレベルの認可に voter を使い、access_control は大まかな URL ルールにのみ使い、コントローラーには #[IsGranted] を付けます。in_array('ROLE_X', $user->getRoles()) のチェックをあちこちに散在させないでください。
• Events では、カスタムイベントクラスを使い、イベント名にはクラス名を使います。リスナーは小さく、ステートレスにします。時間のかかる処理は kernel.response から kernel.terminate または Messenger に移します。
• 時刻の扱いには ClockInterface を注入します。ドメインコードで new \DateTimeImmutable() や time() を呼び出してはいけません。テストでは MockClock を使います。
• Lock には必ず TTL を設定し、長時間の処理中は TTL を更新します。また、すべてのサーバーで共有されるストアを選びます（ホスト間で flock を使わないでください）。
• Process では、コマンドをシェル文字列ではなく配列で渡します。fromShellCommandline() を使うのは、信頼できるエスケープ済みの入力に限ります。
• 識別子には、主キーとして UUIDv4 よりも UUIDv7 または ULID を優先します。時系列順の ID を使うと、インデックスをコンパクトに保てます。
• バンドルを新たに作成する場合は、AbstractBundle を拡張します。すべての設定オプションにデフォルト値を設け、削除する前に非推奨にします。

横断的な落とし穴

• Doctrine の遅延読み込みによる N+1 クエリ。 リレーションにアクセスするループでは、行ごとに 1 つのクエリが発行されます。JOIN で取得し（addSelect）、プロファイラーでクエリ数を確認し、現実的なデータ量でテストしてください。
• 長時間稼働するワーカーのリーク。 Messenger、Swoole、RoadRunner、FrankenPHP のワーカーはカーネルを稼働状態に保ちます。状態を持つサービスには ResetInterface（または kernel.reset タグ）が必要です。メッセージごとにエンティティマネージャーをクリアし、静的キャッシュが際限なく増加しないようにしてください。デプロイ時には messenger:stop-workers でワーカーを再起動してください。
• 環境変数プロセッサー。 %env(int:PORT)% などは実行時に解決されますが、コンテナーのパラメーターはコンパイル時に解決されます。コンパイル時に構築されるもの（コンパイラーパス、バンドルの拡張ロジック）では、環境変数の値を使用しないでください。型変換にはコード内の処理ではなく、プロセッサーを使用してください。
• 非推奨機能の累積。 非推奨機能のレポートを有効にし、ベースラインファイルを用意してテストを実行し、件数が増加した場合は CI を失敗させてください。次のメジャーバージョンにアップグレードする前に、現在のメジャーバージョンの最後のマイナーバージョンで非推奨機能を解消してください。
• 開発環境と本番環境の差異。 デバッグモードでは、cache:clear --env=prod と lint:container で明らかになるコンテナーエラーが隠されます。CI では両方を実行してください。
• カーネルリスナーで isMainRequest() を忘れると、サブリクエストでもロジックが二重に実行されます。
• ハンドラーで \Throwable を捕捉して処理を返すと、Messenger はメッセージが正常に処理されたと判断します。例外をそのまま伝播させるか、意図的に UnrecoverableMessageHandlingException をスローしてください。

コンポーネントごとの理由を含む詳しい注意事項は、references/pitfalls.md を参照してください。Messenger、Form、Cache、Lock、Workflow、Validator を扱う際は、そちらを確認してください。

コンポーネント一覧

目的のみを記載しています。API は docs-lookup から取得してください。

HTTP とランタイム： HttpFoundation（リクエストオブジェクトとレスポンスオブジェクト）、HttpKernel（リクエストからレスポンスへのパイプラインとカーネルイベント）、Routing（URL のマッチングと生成）、Runtime（分離されたブートストラップ、長時間稼働するサーバー）、PSR-7 Bridge（PSR-7 との相互変換）、HttpClient（同期・非同期の HTTP 呼び出し、再試行、モッククライアント）、BrowserKit と DomCrawler と CssSelector（ブラウザーをシミュレートして HTML を検索）、Mime と Mailer（メールの作成と送信）、Asset と AssetMapper（アセット URL、ビルド不要のフロントエンドアセット）。

メッセージングと時間： Messenger（メッセージバス、トランスポート、ワーカー、再試行）、Scheduler（定期的なメッセージ）、Webhook と RemoteEvent（サードパーティーからのコールバックを受信）、Notifier（SMS、チャット、プッシュ通知）、Clock（テスト可能な時刻、DatePoint）、RateLimiter（トークンバケットとウィンドウ制限、8.1 で属性による設定に対応）。

コンテナーと設定： DependencyInjection（コンテナー、自動配線、コンパイラーパス）、Config（設定ツリー、バンドルオプション）、Contracts（キャッシュ、イベント、HTTP、翻訳のフレームワーク非依存インターフェース）、EventDispatcher（リスナーとサブスクライバー）、ExpressionLanguage（安全な式のサンドボックス）、Yaml（解析とダンプ）、OptionsResolver（検証済みオプション配列）。

データと型： Form（フォーム型、データ変換器、コレクション）、Validator（制約とグループ）、Serializer（オブジェクトから配列／JSON／XML への変換）、ObjectMapper（オブジェクトを別のオブジェクトにマッピング。DTO 向け）、JsonStreamer（メモリー消費を抑えた JSON のエンコードとデコード）、JsonPath（RFC 9535 クエリ）、PropertyAccess（パスによる読み書き）、PropertyInfo と TypeInfo（型とメタデータの抽出）、Uid（UUID と ULID）、Intl（ロケールデータ）、Translation（メッセージと ICU 形式）、HtmlSanitizer（ユーザー入力から安全な HTML を生成）。

セキュリティ： Security（認証器、ファイアウォール、投票者、アクセス制御、パスワードハッシュ化）。

並行処理とシステム： Cache（PSR-6 と PSR-16 のプール、タグ、スタンピード対策）、Lock（プロセス間の排他ロック）、Semaphore（並行アクセス数の制限。8.1 でバックエンドを拡充）、Process（外部コマンドの実行）、Filesystem と Finder（ファイル操作と検索）、Ldap（ディレクトリアクセス）。

コンソールとツール： Console（コマンド、入力、出力、ヘルパー）、Tui（フルスクリーンのターミナル UI。8.1 で追加）、VarDumper（読みやすいダンプ）、VarExporter（OPcache に適したエクスポート、遅延オブジェクト）、PHPUnit Bridge（非推奨の報告、テストでの時間または DNS のモック）。

Symfony のコンポーネントではありませんが、よく使用されます： Twig（テンプレート、Twig Bridge）、Doctrine ORM と DBAL（DoctrineBundle と Doctrine bridge を介して使用。Messenger および Validator との統合もあります）。

クイックチェックリスト

• composer.lock とランタイムから、インストール済みの Symfony および PHP のバージョンを確認します。
• コードを書く前に、そのバージョンの API を取得します。
• 属性、自動配線、コンストラクターインジェクションを優先します。
• 長時間稼働時の動作を確認します：状態のリセット、冪等性、制限。
• 非推奨の報告を有効にしてテストを実行し、新たな警告を修正します。

他のスキルとの連携

状況	推奨スキル
ライブラリの最新ドキュメントを取得する	docs-lookup
Symfony のメジャーバージョン間またはマイナーバージョン間を移行する	symfony-upgrade
パッケージを安全に更新する	composer-dependencies
PHPUnit でテストを書く	testing
認可または入力処理をレビューする	security
クエリの問題を見つける	performance
レイヤーと境界を設計する	clean-architecture