Merge pull request #2498 from franmomu/option_annotations

Make `doctrine/annotations` dependency optional

Author: malarzm

UPGRADE-2.7.md

@@ -8,3 +8,8 @@
 ## doctrine/persistence
 
 * MongoDB ODM 2.7 requires `doctrine/persistence` 3.2 or newer.
+
+## `doctrine/annotations` is optional
+
+ODM no longer requires `doctrine/annotations` to be installed. If you're using
+annotations for mapping, you will need to install `doctrine/annotations`.

composer.json

@@ -23,7 +23,6 @@
     "require": {
         "php": "^8.1",
         "ext-mongodb": "^1.11",
-        "doctrine/annotations": "^1.12 || ^2.0",
         "doctrine/cache": "^1.11 || ^2.0",
         "doctrine/collections": "^1.5 || ^2.0",
         "doctrine/event-manager": "^1.0 || ^2.0",
@@ -39,6 +38,7 @@
     },
     "require-dev": {
         "ext-bcmath": "*",
+        "doctrine/annotations": "^1.12 || ^2.0",
         "doctrine/coding-standard": "^12.0",
         "jmikola/geojson": "^1.0",
         "phpbench/phpbench": "^1.0.0",
@@ -49,7 +49,11 @@
         "symfony/cache": "^5.4 || ^6.0 || ^7.0",
         "vimeo/psalm": "^5.9.0"
     },
+    "conflict": {
+        "doctrine/annotations": "<1.12 || >=3.0"
+    },
     "suggest": {
+        "doctrine/annotations": "For annotation mapping support",
         "ext-bcmath": "Decimal128 type support"
     },
     "autoload": {

docs/en/reference/annotations-reference.rst

@@ -1,6 +1,11 @@
 Annotations Reference
 =====================
 
+.. note::
+
+    To be able to use annotations, you will have to install an extra
+    package called ``doctrine/annotations``.
+
 In this chapter a reference of every Doctrine 2 ODM Annotation is
 given with short explanations on their context and usage.
 

docs/en/reference/basic-mapping.rst

@@ -32,6 +32,11 @@ document mapping metadata:
 Introduction to Docblock Annotations
 ------------------------------------
 
+.. note::
+
+    To be able to use annotations, you will have to install an extra
+    package called ``doctrine/annotations``.
+
 You've probably used docblock annotations in some form already,
 most likely to provide documentation metadata for a tool like
 ``PHPDocumentor`` (@author, @link, ...). Docblock annotations are a
@@ -44,12 +49,15 @@ chances of clashes with other docblock annotations, the Doctrine
 docblock annotations feature an alternative syntax that is heavily
 inspired by the Annotation syntax introduced in Java 5.
 
-The implementation of these enhanced docblock annotations is
-located in the ``Doctrine\Common\Annotations`` namespace and
-therefore part of the Common package. Doctrine docblock annotations
-support namespaces and nested annotations among other things. The
-Doctrine MongoDB ODM defines its own set of docblock annotations
-for supplying object document mapping metadata.
+The implementation of these enhanced docblock annotations is located in
+the ``doctrine/annotations`` package, but in the
+``Doctrine\Common\Annotations`` namespace for backwards compatibility
+reasons. Note that ``doctrine/annotations`` is not required by Doctrine
+MongoDB ODM, and you will need to require that package if you want to use
+annotations. Doctrine MongoDB ODM docblock annotations support namespaces and
+nested annotations among other things. The Doctrine MongoDB ODM defines its
+own set of docblock annotations for supplying object-relational mapping
+metadata.
 
 .. note::
 

docs/en/reference/metadata-drivers.rst

@@ -37,8 +37,9 @@ a document.
 
         $em->getConfiguration()->setMetadataCacheImpl(new ApcCache());
 
-If you want to use one of the included core metadata drivers you
-just need to configure it. All the drivers are in the
+If you want to use one of the included core metadata drivers you need to
+configure it. If you pick the annotation driver, you will additionally
+need to install ``doctrine/annotations``. All the drivers are in the
 ``Doctrine\ODM\MongoDB\Mapping\Driver`` namespace:
 
 .. code-block:: php