Add PHP 8.0 Attribute mapping support (#2344)

* Add AttributeDriver

* remove Validation tests because behavior changed

* revise annotations and attributes constructors

Co-authored-by: Fran Moreno <[email protected]>

* update Indexes annotations

* Hardcode file column names

Co-authored-by: Fran Moreno <[email protected]>

* add upgrading notes

* allow Index on properties

Co-authored-by: Fran Moreno <[email protected]>

UPGRADE-2.3.md

@@ -12,3 +12,13 @@ fetch metadata for the class and read the class using `$metadata->getName()`.
 The metadata layer is aware of these proxy namespace changes and how to resolve
 them, so users should always go through the metadata layer to retrieve mapped
 class names.
+
+## Annotation Mapping
+
+In order to make annotations usable as PHP 8 attributes, their classes no 
+longer extend `Doctrine\Common\Annotations\Annotation` class and are now using 
+`@NamedArgumentConstructor` which provides more type safety. 
+This does not apply to `@Indexes` which is deprecated and can't be used as 
+Attribute. Use `@Index` and `@UniqueIndex` instead.
+
+`@Inheritance` annotation has been removed as it was never used.

docs/en/reference/basic-mapping.rst

@@ -12,6 +12,7 @@ Doctrine provides several different ways for specifying object
 document mapping metadata:
 
 -  Docblock Annotations
+-  Attributes
 -  XML
 -  Raw PHP Code
 

docs/en/reference/metadata-drivers.rst

@@ -13,6 +13,7 @@ metadata:
 
 -  **XML files** (XmlDriver)
 -  **Class DocBlock Annotations** (AnnotationDriver)
+-  **Attributes** (AttributeDriver)
 -  **PHP Code in files or static functions** (PhpDriver)
 
 Something important to note about the above drivers is they are all

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

@@ -4,8 +4,6 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
-
-abstract class AbstractDocument extends Annotation
+abstract class AbstractDocument implements Annotation
 {
 }

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

@@ -4,25 +4,39 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
-
-abstract class AbstractField extends Annotation
+abstract class AbstractField implements Annotation
 {
-    /** @var string */
+    /** @var string|null */
     public $name;
 
-    /** @var string */
-    public $type = 'string';
+    /** @var string|null */
+    public $type;
 
     /** @var bool */
-    public $nullable = false;
+    public $nullable;
 
     /** @var mixed[] */
-    public $options = [];
+    public $options;
 
     /** @var string|null */
     public $strategy;
 
     /** @var bool */
-    public $notSaved = false;
+    public $notSaved;
+
+    public function __construct(
+        ?string $name = null,
+        ?string $type = 'string',
+        bool $nullable = false,
+        array $options = [],
+        ?string $strategy = null,
+        bool $notSaved = false
+    ) {
+        $this->name     = $name;
+        $this->type     = $type;
+        $this->nullable = $nullable;
+        $this->options  = $options;
+        $this->strategy = $strategy;
+        $this->notSaved = $notSaved;
+    }
 }

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

@@ -4,14 +4,12 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
-
-abstract class AbstractIndex extends Annotation
+abstract class AbstractIndex implements Annotation
 {
     /** @var string[] */
-    public $keys = [];
+    public $keys;
 
-    /** @var string */
+    /** @var string|null */
     public $name;
 
     /** @var bool|null */
@@ -24,14 +22,36 @@ abstract class AbstractIndex extends Annotation
     public $order;
 
     /** @var bool */
-    public $unique = false;
+    public $unique;
 
     /** @var bool */
-    public $sparse = false;
+    public $sparse;
 
     /** @var mixed[] */
-    public $options = [];
+    public $options;
 
     /** @var array */
-    public $partialFilterExpression = [];
+    public $partialFilterExpression;
+
+    public function __construct(
+        array $keys = [],
+        ?string $name = null,
+        ?bool $background = null,
+        ?int $expireAfterSeconds = null,
+        $order = null,
+        bool $unique = false,
+        bool $sparse = false,
+        array $options = [],
+        array $partialFilterExpression = []
+    ) {
+        $this->keys                    = $keys;
+        $this->name                    = $name;
+        $this->background              = $background;
+        $this->expireAfterSeconds      = $expireAfterSeconds;
+        $this->order                   = $order;
+        $this->unique                  = $unique;
+        $this->sparse                  = $sparse;
+        $this->options                 = $options;
+        $this->partialFilterExpression = $partialFilterExpression;
+    }
 }

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

@@ -4,15 +4,30 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 
 /**
  * Loads data from a different field if the original field is not set
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
-final class AlsoLoad extends Annotation
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_METHOD)]
+final class AlsoLoad implements Annotation
 {
-    /** @var string */
+    /** @var string|string[] */
+    public $value;
+
+    /** @var string|null */
     public $name;
+
+    /**
+     * @param string|string[] $value
+     */
+    public function __construct($value, ?string $name = null)
+    {
+        $this->value = $value;
+        $this->name  = $name;
+    }
 }

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

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
+
+interface Annotation
+{
+}

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

@@ -4,13 +4,23 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 
 /**
  * Specifies the change tracking policy for a document
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
-final class ChangeTrackingPolicy extends Annotation
+#[Attribute(Attribute::TARGET_CLASS)]
+final class ChangeTrackingPolicy implements Annotation
 {
+    /** @var string */
+    public $value;
+
+    public function __construct(string $value)
+    {
+        $this->value = $value;
+    }
 }

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

@@ -4,14 +4,24 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 
 /**
  * Specifies a default discriminator value to be used when the discriminator
  * field is not set in a document
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
-final class DefaultDiscriminatorValue extends Annotation
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY)]
+final class DefaultDiscriminatorValue implements Annotation
 {
+    /** @var string */
+    public $value;
+
+    public function __construct(string $value)
+    {
+        $this->value = $value;
+    }
 }

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

@@ -4,13 +4,23 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 
 /**
  * Specify a field name to store a discriminator value
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
-final class DiscriminatorField extends Annotation
+#[Attribute(Attribute::TARGET_CLASS)]
+final class DiscriminatorField implements Annotation
 {
+    /** @var string */
+    public $value;
+
+    public function __construct(string $value)
+    {
+        $this->value = $value;
+    }
 }

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

@@ -4,13 +4,23 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 
 /**
  * Specify a map of discriminator values and classes
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
-final class DiscriminatorMap extends Annotation
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY)]
+final class DiscriminatorMap implements Annotation
 {
+    /** @var array<string, class-string> */
+    public $value;
+
+    public function __construct(array $value)
+    {
+        $this->value = $value;
+    }
 }

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

@@ -4,13 +4,23 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-use Doctrine\Common\Annotations\Annotation;
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 
 /**
  * Use the specified discriminator for this class
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
-final class DiscriminatorValue extends Annotation
+#[Attribute(Attribute::TARGET_CLASS)]
+final class DiscriminatorValue implements Annotation
 {
+    /** @var string */
+    public $value;
+
+    public function __construct(string $value)
+    {
+        $this->value = $value;
+    }
 }

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

@@ -4,31 +4,59 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
+
 /**
  * Identifies a class as a document that can be stored in the database
  *
  * @Annotation
+ * @NamedArgumentConstructor
  */
+#[Attribute(Attribute::TARGET_CLASS)]
 final class Document extends AbstractDocument
 {
     /** @var string|null */
     public $db;
 
-    /** @var string|null */
+    /** @var string|array|null */
     public $collection;
 
     /** @var string|null */
     public $repositoryClass;
 
     /** @var Index[] */
-    public $indexes = [];
+    public $indexes;
 
     /** @var bool */
-    public $readOnly = false;
+    public $readOnly;
 
     /** @var string|null */
     public $shardKey;
 
     /** @var string|int|null */
     public $writeConcern;
+
+    /**
+     * @param string|array|null $collection
+     * @param Index[]           $indexes
+     * @param int|string|null   $writeConcern
+     */
+    public function __construct(
+        ?string $db = null,
+        $collection = null,
+        ?string $repositoryClass = null,
+        array $indexes = [],
+        bool $readOnly = false,
+        ?string $shardKey = null,
+        $writeConcern = null
+    ) {
+        $this->db              = $db;
+        $this->collection      = $collection;
+        $this->repositoryClass = $repositoryClass;
+        $this->indexes         = $indexes;
+        $this->readOnly        = $readOnly;
+        $this->shardKey        = $shardKey;
+        $this->writeConcern    = $writeConcern;
+    }
 }