DoctrineExtensionsはflush時にどのビヘイビアをDoctrineへ足すのか
Doctrine2 の動作拡張機能、翻訳可能、Sluggable、Tree-NestedSet、Timestampable、Loggable、Sortable。
ひと目でわかる
- これは何？
- gedmo/doctrine-extensionsはDoctrine ORMとMongoDB ODMのイベントに振る舞いを載せるPHPパッケージ。Translatable、Sluggable、Tree、Timestampable、Loggable、SortableなどをREADMEから切り分ける。
- 誰に向いている？
- Doctrine 2.14または3.0系のEntityをflushするタイミングでslug、翻訳、ツリー、監査ログを自動更新したいPHPチーム向け。LoggableをDBAL 4.0と組み合わせたい場合や、MongoDB ODMでNestedSetを使いたい場合には向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 15 日前です。
- 何の言語で書かれている？
- 主に PHP です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
DoctrineExtensionsがflush時にビヘイビアを差し込む位置
DoctrineExtensionsは、Doctrine ORMとMongoDB ODM向けの拡張をまとめたPHPパッケージである。README冒頭は「新しい機能や、Doctrineをより効率的に使う道具を提供する」と書き、振る舞いはDoctrineのイベントシステムへ容易に接続でき、flushされるレコードをビヘイビアとして扱う、と説明する。Packagist上の名前はgedmo/doctrine-extensionsである。言語はPHP、ライセンスはMIT、スター数は素材時点で4139、フォークは1252、デフォルトブランチはmainである。
3.0は「今日のPHP向けにパッケージを刷新する」リリースとしてREADMEが節を立てている。内容はPHPとDoctrineほか依存の最低バージョン引き上げ、最新のDoctrine MongoDBおよびCommonへの対応、テストスイートとコーディング標準とビルドツールの更新、文書とコードとコメントの整理である。絵文字付きの見出しがあるが、技術的な約束はupgrade文書/doc/upgrading/upgrade-v2.4-to-v3.0.mdへ誘導している。2.4系から上げる作業は、このファイルを読まないと差分が見えない。
フレームワーク無しでEntity Managerを組む場合、READMEはexample/em.phpを見よと書く。理由としてissue #1310のような問題を防ぐため、とある。つまり拡張をcomposerで入れただけでは足りず、リスナーの登録方法をexampleに合わせる必要がある。Symfony、Laravel、Laminas向けの手順はそれぞれ/doc/frameworks/symfony.md、laravel.md、laminas.mdに分かれる。
ORMとMongoDB ODMで共有するBlameableからTreeまで
ORMとMongoDB ODMの両方に載る拡張は六つある。Blameableは作成、更新、プロパティ変更時に文字列または参照フィールドを、文字列あるいはオブジェクト（例: ユーザ）で更新する。Loggableはオブジェクトの変更と履歴の追跡を助け、バージョン管理も支える。Sluggableは指定フィールドをURL向けの一意なslugへまとめる。Timestampableは作成、更新、プロパティ変更時に日付フィールドを更新する。Translatableはレコードを別言語へ訳す手段を提供し、READMEは「設定は容易、利用はより容易」と自賛する。Treeはツリー操作を自動化し、リポジトリへツリー専用の関数を足す。実装はclosure、nested set、materialized pathである。MongoDB ODMが支えるのはmaterialized pathのみ、と明記されている。
共有拡張でもODM側の制限はTreeに限らない可能性があるが、READMEが明示しているODM制限はTreeのmaterialized pathだけである。NestedSetやclosureをMongoDBで使いたい場合、このパッケージのTreeは対象外になる。Loggableのバージョン管理がどのエンティティ単位で効くか、slugの一意制約をどのカラムに置くかは各doc（/doc/loggable.md、/doc/sluggable.mdなど）側の話であり、README本文にはスキーマ例が無い。
BlameableとTimestampableは「プロパティ変更時」にも動く点が、単なるcreatedAt/updatedAtヘルパとの差になる。どのプロパティ変更がトリガになるかは各拡張の文書を見る必要がある。READMEはイベント接続という枠だけを示し、アノテーション例は載せていない。
IpTraceableとUploadableなどORM専用拡張の境界
ORM専用は四つ。IpTraceableはTimestampableを継承し、時刻の代わりにIPアドレスを書く。SoftDeleteableはレコードを暗黙に削除できるようにする。Sortableは任意のドキュメントまたはエンティティを並べ替え可能にする。Uploadableはエンティティフィールドでのファイルアップロード処理を提供する。MongoDB ODM専用はReferencesとReferenceIntegrityである。前者はEntityとDocumentの相互リンク、後者はODM MongoDBのDocument参照に制約を付ける。
Sortableの説明が「document or entity」と書いてある一方、見出しはORM Onlyである。MongoDBのドキュメントを並べたい場合、この分類と一文が食い違うように読める。採用前に/doc/sortable.mdでODM対応の有無を確認した方がよい。SoftDeleteableの「暗黙の削除」が実際にdeletedAtを立てるのか、クエリフィルタで除外するのかはREADMEに無い。Uploadableがどのストレージ（ローカル、S3）を想定するかも本文には出てこない。
マッピングはAttribute、XML、Annotation（非推奨）を全拡張が支える。追加のマッピングドライバはMapping拡張を使って実装できる、とある。XMLを使う場合、名前空間はhttp://gediminasm.org/schemas/orm/doctrine-extensions-mappingで、ルートはdoctrine-mappingにxmlns:gedmoを足す形になる。XSDはバージョン接尾辞付きでも公開され、最新、2.2.x、2.1.xのURLが並ぶ。
gedmo/doctrine-extensionsの導入と3.xのバージョン互換
導入はcomposer require gedmo/doctrine-extensionsである。アップグレード案内は2.4.xから3.0向けの文書だけがREADMEにリンクされている。3.0以降のマイナー間の破壊的変更表はREADME本文には無い。素材のリリースはv3.22.1（2026-08-01）、v3.22.0（2025-12-13）、v3.21.0（2025-09-22）である。各タグの変更点はリリース名がバージョン番号のみで、READMEから機能差分は読めない。
バージョン互換の表は具体的である。DBALは全拡張で^3.2、Loggable以外の全拡張なら^4.0も可。つまりLoggableを使うならDBAL 4.0は対象外である。ORMは^2.14または^3.0。MongoDB ODMは^2.3。この表は「全部入りで最新Doctrine」とは限らないことを示す。Loggableの履歴を残したいプロジェクトがDBAL 4へ先に上げていると、このパッケージの組み合わせが崩れる。
フレームワーク向け文書があるため、Symfonyバンドルの自動設定を期待する人は/doc/frameworks/symfony.mdを先に開くべきである。素のPHPでEntity Managerを手組みする場合はexample/em.phpが必須ルートになる。READMEはインストール節でcomposer一行の直後にフレームワーク文書へ飛ばしており、リスナー登録のコード断片はREADME本文に無い。
docker compose上のphpunitとexample/bin/console
テスト手順はDocker前提である。Dockerとdocker composeを入れ、プロジェクトルートでdocker compose up -d、docker compose exec php bashでコンテナへ入り、作業ディレクトリは/var/www、そこでcomposer install、vendor/bin/phpunitである。ホストで直接phpunitを回す手順はREADMEに書いていない。CIワークフローとしてcontinuous-integration.yml、qa.yml、coding-standards.ymlへのバッジリンクがある。
サンプルの実行はルートでcomposerを取得し、composer install、example/em.php先頭のデータベース設定を編集する。コンソールはphp example/bin/console。スキーマ作成はphp example/bin/console orm:schema-tool:create。翻訳付きカテゴリツリーを出す例はphp example/bin/console app:print-category-translation-treeである。このコマンド名はTranslatableとTreeを同時に触る例だと読める。DB接続をexample/em.phpで合わせないと、schema-toolもツリー表示も動かない。
貢献者への謝辞があり、新拡張の作成・維持者としてLukas Botsch (lbotsch)、Gustavo Adrian (comfortablynumb)、Boussekeyt Jules (gordonslondon)、Kudryashov Konstantin (everzet)、David Buchmann (dbu)が挙がる。拡張の作者が分散しているため、個別の/doc/*.mdの更新頻度は拡張ごとに差が出うる。READMEはそれを保証していない。
MIT下でAttributeとXMLをDoctrineExtensionsに載せる条件
ライセンスはMITである。再配布と改変はMITの条件に従う。READMEは保証やセキュリティアドバイザリの窓口を書いていない。Annotationマッピングはdeprecatedであり、新規コードはAttributeかXMLへ寄せるのがREADMEの分類と一致する。XMLを選ぶならgedmo名前空間とXSDの版をスキーマファイルに固定する必要がある。古い2.1/2.2のXSD URLが残っていることは、マッピングファイルの互換を版で切り替えられる一方、混在すると検証が壊れることを意味する。
向くのは、Doctrineのflushにslug生成、翻訳行、ツリーパス、作成者名、タイムスタンプを載せたいアプリケーションである。向かないのは、LoggableをDBAL ^4.0と同時に使いたい構成、MongoDB ODMでnested setを回したい構成、example/em.phpを読まずにリスナー未登録のまま拡張だけcomposerへ足す構成である。確認の起点はcomposer require gedmo/doctrine-extensions、example/em.phpの接続、orm:schema-tool:create、app:print-category-translation-treeである。
Treeを使うなら、RDBならclosure / nested set / materialized pathのどれを選ぶか、MongoDBならmaterialized pathしか無い点を先に固定する。UploadableやSoftDeleteableをORMで使うなら、対応する/doc配下のファイルを開き、ファイル保存先と削除の実体を確認してからエンティティに属性を付けること。
編集部の結論
Doctrine 2.14または3.0系のEntityをflushするタイミングでslug、翻訳、ツリー、監査ログを自動更新したいPHPチーム向け。LoggableをDBAL 4.0と組み合わせたい場合や、MongoDB ODMでNestedSetを使いたい場合には向かない。先にcomposer require gedmo/doctrine-extensionsのあとexample/em.phpの接続設定を直し、php example/bin/console orm:schema-tool:createとapp:print-category-translation-treeを通してから採用範囲を決めること。
コミュニティノート