Added package name collector

[ariddlestone]

Closes #1190

[patrickkusebauch]

I would rather see extending the FileReferenceVisitor to add a property to ClassLikeReference and you then checking against that property, rather than trying to re-parse the file again in the collector.

[patrickkusebauch]

This is very expensive - it forces every class-like to be loaded and parsed at least twice during the program runtime.

[patrickkusebauch]

And also forces the second parsing to be again stored in memory.

[patrickkusebauch]

Limiting this only to class-likes seems half done looking at the docs for that annotation: https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/package.html#description

[patrickkusebauch]

I don't like the concept of mixing Ast Parsing (done in AST module) and collectors (done in Layer module). They are separate concerns and should be done in their respective places.

[dbrumann]

I agree. The collector should not be aware of the parser. I think this should be an extractor instead, which can then emit a reference. I am not sure, if it should be a class reference or maybe something else/new.

[ariddlestone]

At the moment the TokenReferenceInterface only handles the Token and its filepath - could we add a more generic array of meta information, which we can then search later in collectors?

For example, if there was a new TokenReferenceMetaInterface, with an array of those in each TokenReferenceInterface, we could store a new PackageAnnotationMeta object in that array when we find the @package annotation, and then search for it in collectors.

This would prevent the TokenReferenceInterface gradually having more fields as more meta data is attached to it (if more collectors come along in the future).

The extractor you suggest could then add a TokenReferenceMeta to the TokenReference.

Sorry - I don't think I've explained this very well - I'll see if I can start to build it so you can see what I mean.

[patrickkusebauch]

Can the test be done on some fixture class file instead of this synthetic doc-block? Those test then can serve as a documentation reference as well to show case how it should be used as well.

[ariddlestone]

I've made a number of changes:

• Added ReferenceBuilder::$metaData so that we can store arbitrary details there and inject them into the references created
• Created a PackageName class, which is added to ReferenceBuilder::$metaData in FileReferenceVisitor - I can't use an extractor as the $referenceBuilder is a FileReferenceBuilder by the time the extractors are called for class-like nodes
• Modified PackageNameCollector to look for PackageNames in TokenReferenceInterface::getMetaData() to determine package names
• Modified parser tests to use a fixture, and added collector test

Some other notes:

I can't make use of file-level @package annotations, as nikic/php-parser doesn't support them. For now I'm therefore only handling class-like and function docblocks.

The recent work on pulling the docblock parsing into a separate method in FileReferenceVisitor::processClassLikeDocs() was nice. I wonder if it might be worth later looking at separating the various data-gathering processes there into their own registered classes, like extractors are currently.

[ariddlestone]

Just re-read https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/package.html#description and thinking I should remove package name handling from global functions. They're only mentioned if the annotation is at the file-level docblock (which we can't handle).

[gennadigennadigennadi]

Please update the git origin for development to https://github.com/qossmic/deptrac-src and reopen the PR.
Thank you very much!