From fa583f6533a4bdc884d169d796e407a3cd87e4a7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Fri, 25 Jun 2021 21:49:27 +0200
Subject: [PATCH] Make doctrine/annotations an optional dependency

First, there are other drivers than the annotations-based one, and
second, one of them is base on attributes, which are basically
annotations native to PHP.

Closes #8785
---
 composer.json                               |  5 ++++-
 docs/en/reference/annotations-reference.rst | 20 ++++++++++++++------
 docs/en/reference/metadata-drivers.rst      |  5 +++--
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/composer.json b/composer.json
index b3166903184..0a4f9f07f2a 100644
--- a/composer.json
+++ b/composer.json
@@ -19,7 +19,6 @@
         "php": "^7.1|^8.0",
         "ext-pdo": "*",
         "composer/package-versions-deprecated": "^1.8",
-        "doctrine/annotations": "^1.13",
         "doctrine/cache": "^1.11.3|^2.0.3",
         "doctrine/collections": "^1.5",
         "doctrine/common": "^3.0.3",
@@ -34,6 +33,7 @@
         "symfony/console": "^3.0|^4.0|^5.0|^6.0"
     },
     "require-dev": {
+        "doctrine/annotations": "^1.13",
         "doctrine/coding-standard": "^9.0",
         "phpstan/phpstan": "^0.12.83",
         "phpunit/phpunit": "^7.5|^8.5|^9.4",
@@ -42,6 +42,9 @@
         "symfony/yaml": "^3.4|^4.0|^5.0|^6.0",
         "vimeo/psalm": "4.7.0"
     },
+    "conflict": {
+        "doctrine/annotations": "<1.13 || >= 2.0"
+    },
     "suggest": {
         "symfony/cache": "Provides cache support for Setup Tool with doctrine/cache 2.0",
         "symfony/yaml": "If you want to use YAML Metadata Mapping Driver"
diff --git a/docs/en/reference/annotations-reference.rst b/docs/en/reference/annotations-reference.rst
index ef49c29ab16..88f78ebb680 100644
--- a/docs/en/reference/annotations-reference.rst
+++ b/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``.
+
 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
@@ -13,12 +18,15 @@ chances of clashes with other docblock annotations, the Doctrine ORM
 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 ORM docblock
-annotations support namespaces and nested annotations among other
-things. The Doctrine ORM ORM defines its own set of docblock
-annotations for supplying object-relational 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
+ORM, and you will need to require that package if you want to use
+annotations. Doctrine ORM docblock annotations support namespaces and
+nested annotations among other things. The Doctrine ORM defines its
+own set of docblock annotations for supplying object-relational mapping
+metadata.
 
 .. note::
 
diff --git a/docs/en/reference/metadata-drivers.rst b/docs/en/reference/metadata-drivers.rst
index 6e52506f5f8..9b0d521db3a 100644
--- a/docs/en/reference/metadata-drivers.rst
+++ b/docs/en/reference/metadata-drivers.rst
@@ -39,8 +39,9 @@ an entity.
         $em->getConfiguration()->setMetadataCacheImpl(new ApcuCache());
 
 
-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\ORM\Mapping\Driver`` namespace:
 
 .. code-block:: php