Change namespace of attribute classes from `Annotations` to `Attribute` #2933

GromNaN · 2025-11-25T11:31:39Z

Q	A
Type	improvement
BC Break	no (deprecation)
Fixed issues	Related #2931

Summary

Move the classes from Doctrine\ODM\MongoDB\Mapping\Annotations to Doctrine\ODM\MongoDB\Mapping\Attribute. Removing the @Annotation so that they can't be used for legacy annotations.
For the classes in the Annotations namespace, they extend those from the Attribute namespace. Adding the legacy @Annotation for BC.
The EncryptQuery enum is moved to the parent Doctrine\ODM\MongoDB\Mapping namespace
The abstract annotation classes are aliased to the new abstract attribute classes, so that it's not breaking type comparison
Documentation updated

Related initiative in Symfony: symfony/symfony#51381

GromNaN · 2025-11-25T11:37:03Z

This will force users to migrate without offering anything in return, except for consistency in the namespace with other projects (and not yet ORM). ~~We can only do this if ORM also decides to do so.~~

GromNaN · 2025-11-25T14:28:07Z

In fact, ORM don't have this subnamespace (example: Doctrine\ORM\Mapping\Entity). So, we should consider whether we want to keep the namespace or move all the attribute classes to Doctrine\ODM\MongoDB\Mapping.
@alcaeus you had the idea that we should use the attribute classes as model classes for all the class metadata. In that case, that would make sense to remove the subnamespace Attribute.

Copilot

Pull request overview

This PR modernizes the MongoDB ODM library's attribute system by moving attribute classes from the Annotations namespace to the new Attribute namespace. The old Annotations namespace is maintained as a deprecated alias to ensure backward compatibility while guiding users toward the new naming convention.

Key Changes:

Introduced new Doctrine\ODM\MongoDB\Mapping\Attribute namespace for all attribute classes
Added deprecation triggers when old Annotations namespace classes are loaded
Updated all test files and internal references to use the new namespace
Maintained backward compatibility through class aliases

Reviewed changes

Copilot reviewed 300 out of 434 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
`src/Mapping/Attribute/*.php`	New attribute classes in the `Attribute` namespace with class aliases to `Annotations` namespace for backward compatibility
`src/Mapping/Annotations/*.php`	Converted to deprecation stubs that trigger warnings and load the new `Attribute` classes
`tests/*/.php`	Updated import statements from `Annotations` to `Attribute` namespace
`src/Mapping/Driver/*.php`	Updated internal references to use new `Attribute` namespace
`src/Mapping/ClassMetadata.php`	Updated type hints to reference `Attribute` namespace
`UPGRADE-2.16.md`	Added migration guide for the namespace change
`phpstan-baseline.neon`	Updated static analysis baseline with new namespace references

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

UPGRADE-2.16.md

src/Mapping/Annotations/File/UploadDate.php

src/Mapping/Annotations/File/Metadata.php

src/Mapping/Annotations/File/Length.php

src/Mapping/Annotations/File/Filename.php

src/Mapping/Attribute/File/UploadDate.php

src/Mapping/Attribute/File/Metadata.php

src/Mapping/Attribute/File/Length.php

src/Mapping/Attribute/File/Filename.php

src/Mapping/Attribute/File/ChunkSize.php

malarzm

I can't quite grasp it, but there's a "class_alias was problematic in the past" dangling in my head. Saying it out loud in case I'd jog somebody's memory with it. Alernative would be to:

Move classes to Attributes (and drop final, leave it as a phpdoc)
Classes in Annotations would extend their counterpart, emit a deprecation in ctor and forward everything
Remove Annotations/* in 3.0 and bring back final in Attribute/*

Also I'd like to see docs updated for 2.16 - folks copying documentation should not be greeted by a deprecation :)

greg0ire · 2025-12-08T14:46:20Z

I can't quite grasp it, but there's a "class_alias was problematic in the past" dangling in my head. Saying it out loud in case I'd jog somebody's memory with it.

@malarzm I wrote an article about that, and @alcaeus wrote a medium article about the aftermath of doing this for doctrine/persistence as well.

malarzm · 2025-12-08T15:08:00Z

@greg0ire ha! Thanks for the links, I tried to look in our blog and google but prolly I was too specific with "orm namespace change" :)

src/Mapping/Annotations/File/ChunkSize.php

UPGRADE-2.16.md

GromNaN · 2025-12-09T21:03:09Z

I updated the PR, including the docs to use inheritance. That way the new classes in the Attribute namespace cannot be used as annotation.

New PR description:

Move the classes from Doctrine\ODM\MongoDB\Mapping\Annotations to Doctrine\ODM\MongoDB\Mapping\Attribute. Removing the @Annotation so that they can't be used for legacy annotations.

For the classes in the Annotations namespace, they extend those from the Attribute namespace. Adding the legacy @Annotation for BC.

The EncryptQuery enum is moved to the parent Doctrine\ODM\MongoDB\Mapping namespace

The abstract annotation classes are aliased to the new abstract attribute classes, so that it's not breaking type comparison

Documentation updated

I've kept the tests unchanged, ensuring full BC of existing code.

Copilot

Pull request overview

Copilot reviewed 125 out of 125 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/Mapping/Annotations/TimeSeries.php

src/Mapping/Annotations/File.php

src/Mapping/Annotations/EmbeddedDocument.php

src/Mapping/Annotations/Document.php

src/Mapping/Annotations/HasLifecycleCallbacks.php

src/Mapping/Annotations/MappedSuperclass.php

UPGRADE-2.16.md

src/Mapping/Attribute/Document.php

alcaeus

Not sure how to proceed with the missing Annotation interface on the attribute class aliases. Found one issue where annotation classes were used in the attribute reader.

src/Mapping/Annotations/File/ChunkSize.php

alcaeus · 2025-12-12T13:18:01Z

src/Mapping/Attribute/AbstractDocument.php

+}
+
+// @phpstan-ignore class.notFound
+class_alias(AbstractDocument::class, \Doctrine\ODM\MongoDB\Mapping\Annotations\AbstractDocument::class);


Noted that this works in conjunction with the class_exists call in the AbstractDocument annotation file.

Exact, having the class_alias in the same file as the class declaration ensure we always have both declared, even if the attribute is used first.
And the class_exists only triggers the autoloader.

src/Mapping/Annotations/AbstractDocument.php

src/Mapping/Driver/AttributeDriver.php

alcaeus · 2025-12-12T13:23:11Z

src/Mapping/Driver/AttributeDriver.php

+use function array_any;
+use function array_find;


I like the use of array_any and array_find in this class 👏

alcaeus · 2025-12-12T13:24:31Z

src/Mapping/Driver/AttributeReader.php

-            // Make sure we only get Doctrine Annotations
-            if (! is_subclass_of($attributeName, Annotation::class)) {
+            // Make sure we only get MongoDB ODM attribute classes
+            if (! is_subclass_of($attributeName, MappingAttribute::class)) {


Noted that this doesn't change existing behaviour, as all annotations extend the attribute classes.

GromNaN

Not sure how to proceed with the missing Annotation interface on the attribute class aliases. Found one issue where annotation classes were used in the attribute reader.

Do you have an example, I don't see the issue.

src/Mapping/Driver/AttributeDriver.php

src/Mapping/Annotations/File/ChunkSize.php

src/Mapping/Annotations/AbstractDocument.php

…namespace

This classes are never loaded

The Attribute classes cannot be used as Annotation Move QueryType enum to the Mapping namespace Keep the tests on the Annotations namespace

GromNaN · 2025-12-16T11:54:36Z

Before merging, we need to update the bundle:
https://github.com/doctrine/DoctrineMongoDBBundle/blob/9c2ccf08a08fcf739d346810adbbd322ed9c0781/src/DependencyInjection/DoctrineMongoDBExtension.php#L535-L552

Copilot

Pull request overview

Copilot reviewed 125 out of 125 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

GromNaN mentioned this pull request Nov 25, 2025

[3.x] Remove support for Doctrine Annotations #2931

Merged

GromNaN added this to the 2.16.0 milestone Nov 25, 2025

IonBazan requested review from alcaeus, Copilot, franmomu and malarzm November 30, 2025 04:04

Copilot AI reviewed Nov 30, 2025

View reviewed changes

GromNaN force-pushed the attribute-namespace branch from 71eff05 to 5e39484 Compare November 30, 2025 17:01

malarzm reviewed Dec 8, 2025

View reviewed changes

GromNaN force-pushed the attribute-namespace branch from 5e39484 to 4ae6e4d Compare December 8, 2025 20:44

IonBazan reviewed Dec 9, 2025

View reviewed changes

src/Mapping/Annotations/File/ChunkSize.php Outdated Show resolved Hide resolved

GromNaN commented Dec 9, 2025

View reviewed changes

UPGRADE-2.16.md Outdated Show resolved Hide resolved

GromNaN force-pushed the attribute-namespace branch 4 times, most recently from fd80856 to 90f1565 Compare December 9, 2025 20:56

GromNaN requested a review from Copilot December 9, 2025 21:03

Copilot AI reviewed Dec 9, 2025

View reviewed changes

GromNaN force-pushed the attribute-namespace branch from 90f1565 to 7c7544d Compare December 9, 2025 21:09

IonBazan reviewed Dec 10, 2025

View reviewed changes

src/Mapping/Attribute/Document.php Outdated Show resolved Hide resolved

GromNaN requested a review from IonBazan December 11, 2025 20:38

alcaeus requested changes Dec 12, 2025

View reviewed changes

GromNaN force-pushed the attribute-namespace branch from fcb30bc to 7a756e1 Compare December 12, 2025 15:15

GromNaN commented Dec 12, 2025

View reviewed changes

src/Mapping/Driver/AttributeDriver.php Show resolved Hide resolved

src/Mapping/Annotations/File/ChunkSize.php Outdated Show resolved Hide resolved

src/Mapping/Annotations/AbstractDocument.php Show resolved Hide resolved

alcaeus self-requested a review December 16, 2025 09:13

GromNaN added 6 commits December 16, 2025 10:40

Move attribute classes from Mapping\Annotations to Mapping\Attribute …

ed54d1c

…namespace

Add deprecated aliases for attribute classes in Annotations namespace

7b0bd35

Restore annotation classes for static analysis

74dff33

This classes are never loaded

Make Annotation classes extend the Attribute classes

dc40a06

The Attribute classes cannot be used as Annotation Move QueryType enum to the Mapping namespace Keep the tests on the Annotations namespace

Move MappingAttribute to AbstractDocument

7768e90

Add use statement to Attribute class in Annotation classes

8baa798

GromNaN force-pushed the attribute-namespace branch from 7a756e1 to 416ff17 Compare December 16, 2025 09:59

Document minor BC break

0e9bf0d

GromNaN force-pushed the attribute-namespace branch from 416ff17 to 0e9bf0d Compare December 16, 2025 11:20

alcaeus approved these changes Dec 16, 2025

View reviewed changes

GromNaN mentioned this pull request Dec 16, 2025

Mark the definition with the new Document attribute as excluded doctrine/DoctrineMongoDBBundle#970

Open

GromNaN added Feature Enhancement and removed Feature labels Dec 16, 2025

GromNaN requested a review from Copilot December 16, 2025 17:10

Copilot AI reviewed Dec 16, 2025

View reviewed changes

GromNaN merged commit c14f767 into doctrine:2.16.x Dec 16, 2025
29 checks passed

GromNaN deleted the attribute-namespace branch December 16, 2025 17:12

Uh oh!

Change namespace of attribute classes from Annotations to Attribute #2933

Change namespace of attribute classes from Annotations to Attribute #2933

Conversation

GromNaN commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

GromNaN commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GromNaN commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

malarzm left a comment

Choose a reason for hiding this comment

Uh oh!

greg0ire commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

malarzm commented Dec 8, 2025

Uh oh!

Uh oh!

Uh oh!

GromNaN commented Dec 9, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alcaeus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alcaeus Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

GromNaN Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

alcaeus Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

alcaeus Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

GromNaN left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GromNaN commented Dec 16, 2025

Uh oh!

Copilot AI left a comment

Change namespace of attribute classes from `Annotations` to `Attribute` #2933

Change namespace of attribute classes from `Annotations` to `Attribute` #2933

GromNaN commented Nov 25, 2025 •

edited

Loading

GromNaN commented Nov 25, 2025 •

edited

Loading

GromNaN commented Nov 25, 2025 •

edited

Loading

greg0ire commented Dec 8, 2025 •

edited

Loading