Change namespace of attribute classes from Annotations to Attribute

[GromNaN]

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
• Add a deprecated alias for old names. The deprecation warning is triggered only when the class in Annotations namespace is loaded using the autoloader.

[GromNaN]

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]

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.

[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:

1. Move classes to Attributes (and drop final, leave it as a phpdoc)
2. Classes in Annotations would extend their counterpart, emit a deprecation in ctor and forward everything
3. 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]

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]

@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" :)