[meta] Annotations 2.0 (ng)

[Majkl578]

Annotations 2.0 (ng)

This is a meta issue to track Annotations 2.0 milestones/features and aims. It's also a follow-up of #75 which collected some dust over time.

Backward Compatibility

One of the main goals of the 2.0 version is on minimizing breakages of existing annotations and syntax compatibility with Annotations 1.x. Therefore, when talking about custom annotations and docblocks, most of the user-land stuff should work without any significant effort or none at all. However most of the internal stuff is expected to be changed.

Namespace change

• The namespace will be changed from Doctrine\Common\Annotations to Doctrine\Annotations. [Open 2.0 - PHP 7.2, change namespace #193]

Dropped features

Some features will be dropped:

• SimpleAnnotationReader - support for so-called unqualified references without uses are dropped [Drop SimpleAnnotationReader #199]
• AnnotationRegistry - no more annoying autoloader stuff, annotations are now autoloaded implicitly [Eliminate AnnotationRegistry, rely on autoloading only #205]
• FileCacheReader - dropped in favor of CachedReader (based on doctrine/cache) [Drop deprecated FileCacheReader #202]
• Doctrine\Common\Annotations\Annotation - behavior of this class is redundant with @Annotation and __get()/__set() safety is ouf of scope of this library [Drop base Annotation ancestor #246]
• CachedReader - caching is to be done by consumers when needed [Drop CachedReader #249]
• DocLexer, DocParser and doctrine/lexer dependency - these will be replaced by new AST-based parser

---

New parser

Initial work is split into three different stages and will come as a new code without refactoring existing stuff:

1. Parser - this is the docblock parser
   • PP language - Doctrine Annotations syntax definition
   • Compiler - docblock to AST converter
   • AST structure - rich domain-specicic AST
   • AST builder - internal AST walker that builds rich AST
   • AST walker - interface for traversing AST
   • AST dumper- utility walker to display AST structure
   • Parser parity tests - compatibility testing between old and new parsers
2. Metadata - this represents an @Annotation
   • Annotation and Property metadata - information needed to construct annotation objects [Introduce annotation metadata #247]
   • Property type and enum hiearchy [Type hiearchy for property types and enums #256]
   • AST metadata collector (walker)
   • Scope - holds information about subject (origin), active imports, ignored annotations and nesting level
   • Reference resolver - resolves unqualified annotation references based on given scope and strategy
   • Property type parser - parses @var to constraint value types
3. Assembling
   • Annotation assembler - builds actual annotation objects based on AST and metadata
   • Acceptor - determines whether visited annotation AST node should produce an annotation or be skipped (used to build internal/public or skip ignored annotations)
   • Constraint validator - validates annotation's property values against constraints (i.e. Required, Enum, @var)
   • Constructor - instantiates annotation objects based on chosen strategy (using a constructor or using property hydration)

---

Other problems to likely be resolved (but not guaranteed)

Generally issues marked with 2.0 milestone. Notably:

• Support for unqualified references in @var (DCOM-253: Support use statements for annotations property type #86)
• Supporting compound @var (Assumption about value type causes parsing error #185 + DocParser does not interpret/validate multiple type docblocks correctly on annotation properties. #129)
• FCQN with ::class will not produce leading \ (::class notations with FQCN notation and leading \ causes \ to be part of the produced string value #141)
• Proper support for use in traits ([AnnotationReader] Traits Composed from Traits #81)

---

Any feedback is welcomed, either here or (preferably) on Doctrine Slack in #annotations-ng-dev channel.

[alcaeus]

The namespace will be changed from Doctrine\Common\Annotations to Doctrine\Annotations

This was a hotly contested issue in the last attempt to create 2.0, so I'll just link previous discussion: #75 (comment).

FileCacheReader - dropped in favor of doctrine/cache

If with "dropped in favour of" you mean "implemented generically for any doctrine/cache instance", then I can somewhat live with the change. We should also consider shipping readers that use a PSR-16 or PSR-6 cache given to them.

[stof]

* `FileCacheReader` - _dropped in favor of doctrine/cache_

this should read as dropped in favor of CachedReader instead, as the replacement is CachedReader (which already exists in 1.x)

[Majkl578]

@stof Thanks, updated.

[jaapio]

Why write your own docblock parser if the new phpdocumentor docblock parser is able to cover your back? Would be happy to assist with changes if needed

[stof]

@jaapio doctrine annotation are not the same than phpdoc. The phpdocumentor parser cannot replace the Doctrine annotation parser.

[jaapio]

With the new design of the package we left room for annotations. Don't know if it would make any sense for you guys.

[piotrooo]

What is a current state of this milestones?

[Majkl578]

@piotrooo I've cleaned up master (2.0-dev) where namespace has already been changed and most of the deprecated stuff has been dropped too. Now working on introducing new stuff to prepare for the parser replacement.
I also slightly updated the OP.

[piotrooo]

@Majkl578 have you any tasks to do? I can help with that release.
BTW. Thanks for good work.