Change namespace of attribute classes from Annotations to Attribute

UPGRADE-2.16.md

@@ -1,5 +1,30 @@
 # UPGRADE FROM 2.15 to 2.16
 
+## Attribute namespaces
+
+Doctrine annotations are already deprecated in favor of PHP attributes.
+As of MongoDB ODM 2.16, the namespace of attribute classes has been changed from
+`Doctrine\ODM\MongoDB\Mapping\Annotations` to `Doctrine\ODM\MongoDB\Mapping\Attribute`.
+The old classes continue to work, but they are deprecated and will be removed in 3.0.
+
+```diff
+- use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
++ use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
+
+  #[ODM\Document]
+  class User
+  {
+      #[ODM\Id]
+      private string $id;
+
+      #[ODM\Field]
+      public string $name;
+  }
+```
+
+The enum `Doctrine\ODM\MongoDB\Mapping\Annotations\EncryptQuery` has been moved to
+`Doctrine\ODM\MongoDB\Mapping\Attribute\EncryptQuery`.
+
 ## Package `doctrine/cache` no longer required
 
 If you use `Doctrine\ODM\MongoDB\Configuration::getMetadataCacheImpl()`,

composer.json

@@ -38,6 +38,7 @@
         "psr/cache": "^1.0 || ^2.0 || ^3.0",
         "symfony/console": "^5.4 || ^6.4 || ^7.0 || ^8.0",
         "symfony/deprecation-contracts": "^2.2 || ^3.0",
+        "symfony/polyfill-php84": "^1.33",
         "symfony/var-dumper": "^5.4 || ^6.4 || ^7.0 || ^8.0",
         "symfony/var-exporter": "^6.4.1 || ^7.0 || ^8.0"
     },

docs/en/cookbook/mapping-classes-to-orm-and-odm.rst

@@ -113,7 +113,7 @@ Now map the same class to the Doctrine MongoDB ODM:
         namespace Documents\Blog;
 
         use Documents\Blog\Repository\ODM\BlogPostRepository;
-        use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
         #[ODM\Document(repositoryClass: BlogPostRepository::class)]
         class BlogPost

docs/en/cookbook/queryable-encryption.rst

@@ -47,9 +47,8 @@ fields that require encryption.
 
     namespace Documents;
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Encrypt;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\EncryptQuery;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
+    use Doctrine\ODM\MongoDB\Mapping\EncryptQuery;
 
     #[ODM\Document]
     class Patient
@@ -69,15 +68,15 @@ fields that require encryption.
          * This allows us to find a patient by their exact SSN.
          */
         #[ODM\Field(type: 'string')]
-        #[Encrypt(queryType: EncryptQuery::Equality)]
+        #[ODM\Encrypt(queryType: EncryptQuery::Equality)]
         public string $ssn;
 
         /**
          * The entire embedded document is encrypted as an object.
          * By not specifying a queryType, we make it non-queryable.
          */
         #[ODM\EmbedOne(targetDocument: Billing::class)]
-        #[Encrypt]
+        #[ODM\Encrypt]
         public Billing $billing;
 
         /**

docs/en/cookbook/time-series-data.rst

@@ -47,7 +47,7 @@ First, we define the model for our data:
     <?php
 
     use DateTimeImmutable;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
     use MongoDB\BSON\ObjectId;
 
     #[ODM\Document]

docs/en/cookbook/validation-of-documents.rst

@@ -175,7 +175,7 @@ the ``odm:schema:create`` or ``odm:schema:update`` command.
 
         namespace Documents;
 
-        use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
         use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 
         #[ODM\Document]

docs/en/cookbook/vector-search.rst

@@ -36,7 +36,7 @@ return the same result because Voyage AI uses normalized vectors to length 1.
 
 .. code-block:: php
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
     use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
     use Doctrine\ODM\MongoDB\Types\Type;
     use Symfony\AI\Platform\Vector\Vector;

docs/en/reference/annotations-reference.rst

@@ -25,7 +25,7 @@ Replace the ``@ODM\Document`` annotations with the ``#[ODM\Document]`` attribute
 
 .. code-block:: diff
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
     - /**
     -  * @ODM\Document

docs/en/reference/attributes-reference.rst

@@ -368,14 +368,14 @@ Example:
 
     <?php
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Encrypt;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\EncryptQuery;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
+    use Doctrine\ODM\MongoDB\Mapping\EncryptQuery;
 
-    #[Document]
+    #[ODM\Document]
     class Client
     {
-        #[Field]
-        #[Encrypt(queryType: EncryptQuery::Equality)]
+        #[ODM\Field]
+        #[ODM\Encrypt(queryType: EncryptQuery::Equality)]
         public string $name;
     }
 
@@ -390,23 +390,23 @@ value in the parent document.
 
     <?php
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Encrypt;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-    #[Encrypt]
-    #[EmbeddedDocument]
+    #[ODM\Encrypt]
+    #[ODM\EmbeddedDocument]
     class CreditCard
     {
-        #[Field]
+        #[ODM\Field]
         public string $number;
 
-        #[Field]
+        #[ODM\Field]
         public string $expiryDate;
     }
 
-    #[Document]
+    #[ODM\Document]
     class User
     {
-        #[EmbedOne(targetDocument: CreditCard::class)]
+        #[ODM\EmbedOne(targetDocument: CreditCard::class)]
         public CreditCard $creditCard;
     }
 
@@ -1476,15 +1476,12 @@ Example:
 .. code-block:: php
 
     <?php
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Field;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Id;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\VectorSearchIndex;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
     use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
     use Doctrine\ODM\MongoDB\Types\Type;
 
-    #[Document(collection: 'vector_embeddings')]
-    #[VectorSearchIndex(
+    #[ODM\Document(collection: 'vector_embeddings')]
+    #[ODM\VectorSearchIndex(
         fields: [
             [
                 'type' => 'vector',
@@ -1501,14 +1498,14 @@ Example:
     )]
     class VectorEmbedding
     {
-        #[Id]
+        #[ODM\Id]
         public ?string $id = null;
 
         /** @var list<float> */
-        #[Field(type: Type::COLLECTION)]
+        #[ODM\Field(type: Type::COLLECTION)]
         public array $plotEmbeddingVoyage3Large = [];
 
-        #[Field]
+        #[ODM\Field]
         public string $category;
     }
 

docs/en/reference/basic-mapping.rst

@@ -57,9 +57,9 @@ to be designated as a document. This can be done through the
 
         namespace Documents;
 
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-        #[Document]
+        #[ODM\Document]
         class User
         {
         }
@@ -88,9 +88,9 @@ option as follows:
 
         namespace Documents;
 
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-        #[Document(db: 'my_db', collection: 'users')]
+        #[ODM\Document(db: 'my_db', collection: 'users')]
         class User
         {
         }
@@ -257,13 +257,12 @@ Here is an example:
 
         namespace Documents;
 
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Id;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-        #[Document]
+        #[ODM\Document]
         class User
         {
-            #[Id]
+            #[ODM\Id]
             public string $id;
         }
 
@@ -309,13 +308,12 @@ Here is an example how to manually set a string identifier for your documents:
 
         namespace Documents;
 
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Id;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-        #[Document]
+        #[ODM\Document]
         class MyPersistentClass
         {
-            #[Id(strategy: 'NONE', type: 'string')]
+            #[ODM\Id(strategy: 'NONE', type: 'string')]
             public string $id;
 
             //...
@@ -430,15 +428,14 @@ Example:
 
         namespace Documents;
 
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
-        use Doctrine\ODM\MongoDB\Mapping\Annotations\Field;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-        #[Document]
+        #[ODM\Document]
         class User
         {
             // ...
 
-            #[Field]
+            #[ODM\Field]
             public string $username;
         }
 

docs/en/reference/introduction.rst

@@ -46,7 +46,7 @@ the features.
     use DateTimeImmutable;
     use Doctrine\Common\Collections\ArrayCollection;
     use Doctrine\Common\Collections\Collection;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
     #[ODM\MappedSuperclass]
     abstract class BaseEmployee

docs/en/reference/storing-files-with-gridfs.rst

@@ -41,28 +41,27 @@ Mapping documents as GridFS files
 
     namespace Documents;
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\File;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Id;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
     #[File(bucketName: 'image')]
     class Image
     {
-        #[Id]
+        #[ODM\Id]
         private ?string $id;
 
-        #[File\Filename]
+        #[ODM\File\Filename]
         private ?string $name;
 
-        #[File\UploadDate]
+        #[ODM\File\UploadDate]
         private \DateTimeInterface $uploadDate;
 
-        #[File\Length]
+        #[ODM\File\Length]
         private ?int $length;
 
-        #[File\ChunkSize]
+        #[ODM\File\ChunkSize]
         private ?int $chunkSize;
 
-        #[File\Metadata(targetDocument: ImageMetadata::class)]
+        #[ODM\File\Metadata(targetDocument: ImageMetadata::class)]
         private ImageMetadata $metadata;
 
         public function getId(): ?string
@@ -131,13 +130,12 @@ The ``ImageMetadata`` class must be an embedded document:
 
     namespace Documents;
 
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\EmbeddedDocument;
-    use Doctrine\ODM\MongoDB\Mapping\Annotations\Field;
+    use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
-    #[EmbeddedDocument]
+    #[ODM\EmbeddedDocument]
     class ImageMetadata
     {
-        #[Field(type: 'string')]
+        #[ODM\Field(type: 'string')]
         private string $contentType;
 
         public function __construct(string $contentType)

docs/en/tutorials/getting-started.rst

@@ -86,7 +86,7 @@ You can provide your mapping information in Attribute or XML:
         use DateTimeImmutable;
         use Doctrine\Common\Collections\ArrayCollection;
         use Doctrine\Common\Collections\Collection;
-        use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+        use Doctrine\ODM\MongoDB\Mapping\Attribute as ODM;
 
         #[ODM\Document]
         class User

phpstan-baseline.neon

@@ -373,10 +373,10 @@ parameters:
 			path: src/Iterator/IterableResult.php
 
 		-
-			message: '#^Method Doctrine\\ODM\\MongoDB\\Mapping\\Annotations\\SearchIndex\:\:__construct\(\) has parameter \$fields with no value type specified in iterable type array\.$#'
+			message: '#^Method Doctrine\\ODM\\MongoDB\\Mapping\\Attribute\\SearchIndex\:\:__construct\(\) has parameter \$fields with no value type specified in iterable type array\.$#'
 			identifier: missingType.iterableValue
 			count: 1
-			path: src/Mapping/Annotations/SearchIndex.php
+			path: src/Mapping/Attribute/SearchIndex.php
 
 		-
 			message: '#^Method Doctrine\\ODM\\MongoDB\\Mapping\\ClassMetadata\:\:addInheritedAssociationMapping\(\) has Doctrine\\ODM\\MongoDB\\Mapping\\MappingException in PHPDoc @throws tag but it''s not thrown\.$#'
@@ -475,7 +475,7 @@ parameters:
 			path: src/Mapping/Driver/XmlDriver.php
 
 		-
-			message: '#^Parameter \#2 \$mapping of method Doctrine\\ODM\\MongoDB\\Mapping\\Driver\\XmlDriver\:\:addFieldMapping\(\) expects array\{type\?\: string, fieldName\?\: string, name\?\: string, strategy\?\: string, association\?\: int, id\?\: bool, isOwningSide\?\: bool, collectionClass\?\: class\-string, \.\.\.\}, array\<string, array\<''contention''\|''max''\|''min''\|''precision''\|''queryType''\|''sparsity''\|''trimFactor''\|int\<0, max\>, Doctrine\\ODM\\MongoDB\\Mapping\\Annotations\\EncryptQuery\|float\|int\|MongoDB\\BSON\\Decimal128\|MongoDB\\BSON\\Int64\|MongoDB\\BSON\\UTCDateTime\|string\|null\>\|bool\|string\> given\.$#'
+			message: '#^Parameter \#2 \$mapping of method Doctrine\\ODM\\MongoDB\\Mapping\\Driver\\XmlDriver\:\:addFieldMapping\(\) expects array\{type\?\: string, fieldName\?\: string, name\?\: string, strategy\?\: string, association\?\: int, id\?\: bool, isOwningSide\?\: bool, collectionClass\?\: class\-string, \.\.\.\}, array\<string, array\<''contention''\|''max''\|''min''\|''precision''\|''queryType''\|''sparsity''\|''trimFactor''\|int\<0, max\>, Doctrine\\ODM\\MongoDB\\Mapping\\EncryptQuery\|float\|int\|MongoDB\\BSON\\Decimal128\|MongoDB\\BSON\\Int64\|MongoDB\\BSON\\UTCDateTime\|string\|null\>\|bool\|string\> given\.$#'
 			identifier: argument.type
 			count: 1
 			path: src/Mapping/Driver/XmlDriver.php

phpstan.neon.dist

@@ -54,6 +54,10 @@ parameters:
       - message: '#MongoDB\\BSON\\VectorType#'
       - message: '#MongoDB\\BSON\\Binary\:\:(TYPE_VECTOR|getVectorType|toArray|fromVector)#'
 
+      - message: '#^Class Doctrine\\ODM\\MongoDB\\Mapping\\([a-zA-Z0-9\\]+) extends @final class Doctrine\\ODM\\MongoDB\\Mapping\\Attribute\\([a-zA-Z0-9\\]+)\.$#'
+        identifier: class.extendsFinalByPhpDoc
+        path: src/Mapping/Annotations/
+
   # To be removed when reaching phpstan level 6
   checkMissingVarTagTypehint: true
   checkMissingTypehints: true

src/Mapping/Annotations/AbstractDocument.php

@@ -4,6 +4,14 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
-abstract class AbstractDocument implements Annotation
-{
+use function class_exists;
+
+class_exists(\Doctrine\ODM\MongoDB\Mapping\Attribute\AbstractDocument::class);
+
+// @phpstan-ignore-next-line if.alwaysFalse
+if (false) {
+    /** @deprecated Use \Doctrine\ODM\MongoDB\Mapping\Attribute\AbstractDocument instead */
+    abstract class AbstractDocument extends \Doctrine\ODM\MongoDB\Mapping\Attribute\AbstractDocument
+    {
+    }
 }