Task #33142

Ignore Tags / Annotations in external libraries, find some good solution

Added by Christian Müller over 3 years ago. Updated over 3 years ago.

Status:Resolved Start date:2012-01-12
Priority:Should have Due date:
Assigned To:Karsten Dambekalns % Done:

100%
Category:Reflection
Target version:TYPO3 Flow Base Distribution - 1.1
Sprint: Has patch:No
PHP Version: Complexity:

Description

for now we have the ignore list of tags in Packages/Framework/TYPO3.FLOW3/Classes/Reflection/ReflectionService.php

For external libraries with lots of custom tags this is a problem, of course we can patch master specifically all the time, but maybe we should think about another solution. So a possible way would be to have a core ignore set and allow additions by configuration or just a globally configurable ignore list. Maybe there are other ideas?

Associated revisions

Revision cebbf8e2
Added by Christian Müller over 3 years ago

[FEATURE] Make tag ignores configurable

Makes the list of ignored tags configurable. This can be used to add
tags to the list if needed by your package by simply setting
TYPO3.FLOW3.reflection.ignoredTags to an array of tag names in your
Settings.yaml.

Change-Id: I2e92e506504c049fd139ec0a8f6a19524a0c38f1
Resolves: #33142
Releases: 1.1

History

#1 Updated by Adrian Föder over 3 years ago

Well for now, we have afaik two possibilities how external libraries could get involved:
  1. if it's just a tiny helper library, it's intended to be stored in {PackageRoot}/Resources/PHP/{libraryName} and just included via require. is this suspected by the problem however?
  2. if the FLOW3 package mainly represents the foreing library at all, like it's the case in Imagine or Swift package, the library code is put below {PackageRoot}/Classes directly.

If this is considered common guideline, I suggest we should only allow customized annotation allowance for files below those two kind of directories.

So basically I agree with Christian making the "ignore" list of annotations just configurable via YAML configuration.
Additional idea could be to allow "mapping" of annotations; i.e. 

@date
(which is not an official PhpDoc annotation) could get mapped to 
@My\SooperdooperTool\Annotations\Date
or such.

#2 Updated by Peter Beernink over 3 years ago

Adrian Föder wrote:

If this is considered common guideline, I suggest we should only allow customized annotation allowance for files below those two kind of directories.

So basically I agree with Christian making the "ignore" list of annotations just configurable via YAML configuration.
Additional idea could be to allow "mapping" of annotations; i.e. 

@date

(which is not an official PhpDoc annotation) could get mapped to 
@My\SooperdooperTool\Annotations\Date

or such.

This also make it possible to 'ignore' other tags, when an empty Annotation\Ignore is added.

#3 Updated by Karsten Dambekalns over 3 years ago

  • Project changed from TYPO3 Flow Base Distribution to TYPO3.Flow
  • Status changed from New to Accepted
  • Assigned To changed from Christian Müller to Karsten Dambekalns

#4 Updated by Karsten Dambekalns over 3 years ago

  • Category set to Reflection
  • Target version set to 1.1
  • Has patch set to No

#5 Updated by Gerrit Code Review over 3 years ago

  • Status changed from Accepted to Under Review

Patch set 3 for branch master has been pushed to the review server.
It is available at http://review.typo3.org/7747

#6 Updated by Gerrit Code Review over 3 years ago

Patch set 4 for branch master has been pushed to the review server.
It is available at http://review.typo3.org/7747

#7 Updated by Peter Beernink over 3 years ago

Karsten I haven't tested your code yet, but it looks like a good solution.
However, when I read the code it looks like one has to copy the default list to the Configuration/Settings.yaml in order to add additional tags.

Is this the intended behaviour?
I can imagine that you have multiple (3rd party) packages which all have one or two tags to exclude. You have to manually check each package on which tags should be excluded and compile a complete list in your base Settings.yaml.

Or am I completely wrong here and is the array merged with arrays defined in other packages?

#8 Updated by Bastian Waidelich over 3 years ago

Peter Beernink wrote:

However, when I read the code it looks like one has to copy the default list
to the Configuration/Settings.yaml in order to add additional tags.

Good catch, this wouldn't be easily extensible by 3rd party unless we'd change the syntax to something like

ignoredTags:
  api: y
  package: y
  ...

if I'm correct..

Not very beautiful IMO.
What about adding an AnnotationInterface (that all annotations need to implement) and an (extensible) whitelist that gets all annontations added dynamically?

#9 Updated by Karsten Dambekalns over 3 years ago

Check the configuration in the TYPO3.TcPdf package, it simply adds stuff. Worked for me, so unless I missed something, no need to replicate (which would be stupid).

#10 Updated by Gerrit Code Review over 3 years ago

Patch set 5 for branch master has been pushed to the review server.
It is available at http://review.typo3.org/7747

#11 Updated by Christian Müller over 3 years ago

  • Status changed from Under Review to Resolved
  • % Done changed from 0 to 100

Also available in: Atom PDF