Document class-level Index annotations

UPGRADE-2.2.md

@@ -8,3 +8,10 @@ to the `Query` class.
 
 The `Doctrine\ODM\MongoDB\Aggregation\Builder::execute()` method was deprecated
 and will be removed in ODM 3.0.
+
+## Document indexes (annotations)
+
+Using `@Index` annotation(s) on a class level is a preferred way for defining
+indexes for documents. Using `@Index` in the `@Indexes` annotation or an `indexes`
+property of other annotations was deprecated and will be removed in ODM 3.0.
+

docs/en/reference/annotations-reference.rst

@@ -154,7 +154,8 @@ Optional attributes:
 -
    ``repositoryClass`` - Specifies a custom repository class to use.
 -
-   ``indexes`` - Specifies an array of indexes for this document.
+   ``indexes`` - Specifies an array of indexes for this document (deprecated,
+   specify all ``@Index`` annotations on a class level).
 -
    ``readOnly`` - Prevents document from being updated: it can only be inserted,
    upserted or removed.
@@ -340,7 +341,8 @@ Optional attributes:
 
 -
    ``indexes`` - Specifies an array of indexes for this embedded document, to be
-   included in the schemas of any embedding documents.
+   included in the schemas of any embedding documents (deprecated, specify all
+   ``@Index`` annotations on a class level).
 
 @Field
 ------
@@ -409,7 +411,8 @@ Optional attributes:
    must extend the ``Doctrine\ODM\MongoDB\Repository\GridFSRepository``
    interface.
 -
-   ``indexes`` - Specifies an array of indexes for this document.
+   ``indexes`` - Specifies an array of indexes for this document (deprecated,
+   specify all ``@Index`` annotations on a class level).
 -
    ``readOnly`` - Prevents the file from being updated: it can only be inserted,
    upserted or removed.
@@ -512,8 +515,7 @@ customize this via the :ref:`strategy <basic_mapping_identifiers>` attribute.
 @Index
 ------
 
-This annotation is used inside of the class-level `@Document`_ or
-`@EmbeddedDocument`_ annotations to specify indexes to be created on the
+This annotation is used  to specify indexes to be created on the
 collection (or embedding document's collection in the case of
 `@EmbeddedDocument`_). It may also be used at the property-level to define
 single-field indexes.
@@ -539,11 +541,8 @@ ODM allows mapped field names (i.e. PHP property names) to be used when defining
     <?php
 
     /**
-     * @Document(
-     *   indexes={
-     *     @Index(keys={"username"="desc"}, options={"unique"=true})
-     *   }
-     * )
+     * @Document
+     * @Index(keys={"username"="desc"}, options={"unique"=true})
      */
     class User
     {
@@ -572,9 +571,13 @@ If you are creating a single-field index, you can simply specify an `@Index`_ or
 @Indexes
 --------
 
+.. note::
+    The ``@Indexes`` annotation was deprecated in 2.2 and will be removed in 3.0.
+    Please move all nested ``@Index`` annotations to a class level.
+
 This annotation may be used at the class level to specify an array of `@Index`_
-annotations. It is functionally equivalent to using the ``indexes`` option for
-the `@Document`_ or `@EmbeddedDocument`_ annotations.
+annotations. It is functionally equivalent to specifying multiple ``@Index``
+annotations on a class level.
 
 .. code-block:: php
 

lib/Doctrine/ODM/MongoDB/Mapping/Annotations/Indexes.php

@@ -9,6 +9,8 @@
 /**
  * Specifies a list of indexes for a document
  *
+ * @deprecated class was deprecated in doctrine/mongodb-odm 2.2 and will be removed in 3.0. Specify all Index and UniqueIndex annotations on a class level.
+ *
  * @Annotation
  */
 final class Indexes extends Annotation

lib/Doctrine/ODM/MongoDB/Mapping/Driver/AnnotationDriver.php

@@ -20,9 +20,11 @@
 use function assert;
 use function class_exists;
 use function constant;
+use function count;
 use function get_class;
 use function interface_exists;
 use function is_array;
+use function sprintf;
 use function trigger_error;
 
 /**
@@ -69,8 +71,13 @@ public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\C
                 $this->addIndex($class, $annot);
             }
             if ($annot instanceof ODM\Indexes) {
-                // Setting the type to mixed is a workaround until https://github.com/doctrine/annotations/pull/209 is released.
-                /** @var mixed $value */
+                @trigger_error(
+                    sprintf(
+                        'Indexes annotation used in %s was deprecated in doctrine/mongodb-odm 2.2 and will be removed in 3.0. Specify all Index and UniqueIndex annotations on a class level.',
+                        $className
+                    ),
+                    E_USER_DEPRECATED
+                );
                 $value = $annot->value;
                 foreach (is_array($value) ? $value : [$value] as $index) {
                     $this->addIndex($class, $index);
@@ -141,7 +148,15 @@ public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\C
         if (isset($documentAnnot->writeConcern)) {
             $class->setWriteConcern($documentAnnot->writeConcern);
         }
-        if (isset($documentAnnot->indexes)) {
+        if (isset($documentAnnot->indexes) && count($documentAnnot->indexes)) {
+            @trigger_error(
+                sprintf(
+                    'Indexes parameter used in %s\'s %s was deprecated in doctrine/mongodb-odm 2.2 and will be removed in 3.0. Specify all Index and UniqueIndex annotations on a class level.',
+                    $className,
+                    get_class($documentAnnot)
+                ),
+                E_USER_DEPRECATED
+            );
             foreach ($documentAnnot->indexes as $index) {
                 $this->addIndex($class, $index);
             }

tests/Doctrine/ODM/MongoDB/Tests/Functional/IndexesTest.php

@@ -79,6 +79,28 @@ public function testDiscriminatorIndexes()
         $this->assertEquals(1, $indexes[0]['keys']['type']);
     }
 
+    public function testMultipleIndexAnnotations()
+    {
+        $class   = $this->dm->getClassMetadata(DocumentWithMultipleIndexAnnotations::class);
+        $sm      = $this->dm->getSchemaManager();
+        $indexes = $sm->getDocumentIndexes($class->name);
+
+        $this->assertCount(3, $indexes);
+
+        $this->assertTrue(isset($indexes[0]['keys']['name']));
+        $this->assertEquals(1, $indexes[0]['keys']['name']);
+
+        $this->assertTrue(isset($indexes[1]['keys']['name']));
+        $this->assertEquals(-1, $indexes[1]['keys']['name']);
+
+        $this->assertTrue(isset($indexes[2]['keys']['name']));
+        $this->assertEquals(1, $indexes[2]['keys']['name']);
+        $this->assertTrue(isset($indexes[2]['options']['unique']));
+        $this->assertEquals(true, $indexes[2]['options']['unique']);
+        $this->assertTrue(isset($indexes[2]['options']['sparse']));
+        $this->assertEquals(true, $indexes[2]['options']['sparse']);
+    }
+
     public function testIndexDefinitions()
     {
         $class   = $this->dm->getClassMetadata(UniqueOnFieldTest::class);
@@ -377,6 +399,21 @@ class DocumentWithDiscriminatorIndex
     public $id;
 }
 
+/**
+ * @ODM\Document
+ * @ODM\Index(keys={"name"="asc"})
+ * @ODM\Index(keys={"name"="desc"})
+ * @ODM\UniqueIndex(keys={"name"="asc"}, options={"sparse"=true})
+ */
+class DocumentWithMultipleIndexAnnotations
+{
+    /** @ODM\Id */
+    public $id;
+
+    /** @ODM\Field(type="string") */
+    public $name;
+}
+
 /** @ODM\EmbeddedDocument */
 class EmbeddedDocumentWithIndexes
 {