Hi, Firstly - many apologizes for not follwoing along, couldn't be near my mail yesterday (university...). Many apologizes for the long response too ;).
> . > There is already a similar RFC here :) Maybe it could be good to start > from this one so that we don't have any duplicated RFC ? > > https://wiki.php.net/rfc/annotations-in-docblock Didn't saw this RFC, it's describes better the idea, yeah. I think that we should collect the argument we've said in this discussion and merge between these RFC's. I can do that, in case you dont mind :). At phpDocumentor we have been working on formalizing the PHPDoc Standard for > quite some time now and I would ask you to take a look at that and use it > as > basis for the parsing of DocBlocks. > > You can find the document here: > https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md > Personally, I think that a built-in parser should cover that. (I'll state my opinion in this mail). What about repeated keys? i.e: > > @param int $a > @param string $b > > Let's make this clear immediately: an associative array as output is not > useful. > That would make it impossible to nest annotations. For example, something > like following wouldn't work if the output is just arrays: > You right, so we can use the ReflectionAnnotation class proposed in the other RFC (that I missed), which contains key and value. Even sounds more OO for me. Annotations have nothing to do with user land documentation, please > don't go down this discussion again as it will be of no help for this > topic. > That's true. But I wish to state my opinion now: the current annotations that Doctorine etc. use is a hack. They took the original doc-block style comments and use them for storing metadata. that's the reason I think that in case we'll implement some sort of a parser - it should support the documentation. Yahav and all, > Why does this need to be part of Reflection? Seems a rather odd place for > it IMHO, since it basically hard-codes the functionality into part of the > core that's not trivially extendable (at least $class->getMethods() is hard > to override)... > > Instead, what about adding a SPL class to parse the comment. Something like > > class SplAnnotationParser { > const PARSE_DEFAULT = 1; > const PARSE_FUNCTION = 2; > public function __construct($rules = self::PARSE_DEFAULT); > > /** > * @param string $comment The comment to parse > * @returns array An array of parsed annotations, pursuant to the > ruleset used > public function parseAnnotations($comment); > } > > That way, you'd do: > > $parser = new SplAnnotationParser(SplAnnotationParser::PARE_FUNCTION); > foreach ($class->getMethods() as $method) { > $annotations = $parser->parseAnnotations($method->getDocComment()); > } > > It decouples the implementation, and allows for people to polymorphically > substitute different parsers for different needs. > > Thoughts? I don't think it should be implemented as SPL feature since it uses the doc-comment of a specific function. Since we got getDocComment() in the Reflection extension, it just feel obvious for me that I'd have the annotations accessors in the related classes too. In addition, in order to parse a doc-block you should have either the doc-block as string or the class/method/function etc. In case you wish to perform it from the class/method etc. - the logic is already well-known for users that they can reflect their classes using Reflection, so I don't see the reason to add another layer. In case you wish to use the doc-comment - it's possible , but the user most likely need to initialize a Reflection object anyway to get this doc-comment string... Hey everybody, > > I've been following this list for a while (1-2 years) and this is the > first message I'm sending. > In my oppinion, annotations in docblocks are a bit(a lot) hacky and > making it even worse by adding them to core is not the best idea. > > This is how I think annotations have to look like if implemented in > core (I've taken on of the annotation classes in Doctrine and > transformed it). > > Declaration: > > namespace Doctrine\ORM\Mapping; > > use SplAnnotation, SplAnnotationInterface; > > @Target({'PROPERTY', 'ANNOTATION'}) > class JoinColumn implements SplAnnotation > { > @SplAnnotation\String > private $name; > > @SplAnnotation\Boolean > private $unique; > > @SplAnnotation\Mixed > private $onDelete; > > @SplAnnotation\String > private $referencedColumn = 'id'; > } > > Usage: > > <?php > > use Lib\Mapping\ORM as ORM; > > @ORM\Table() > @ORM\Entity() > class User { > > @ORM\Column(name="name", type="string") > private $name; > > @ORM\OneToMany(targetEntity=" > Group", mappedBy="user") > @ORM\JoinColumn(onDelete="CASCADE") > private $groups; > } > > Of course the syntax and interfaces are just an example for you to get > the concept. > > I'm not very familiar with the internals of the language, so if this > is hard(not really possible) to implement, just ignore it. > However, I think that parsing annotations as a part of the syntax of > the language would be much faster (and less of a mess) and reliable > than > parsing strings in docblocks. > > Bottomline, my idea is: > A native syntax outside docblocks that doesn't suck :) > > Cheers, > Vladislav > On parsing annotations in docblocks: please don't. > > First of all, there are already plenty of established userland > implementations - so there is really no need for this. > > Whatever you decide on in terms of syntax, most likely won't satisfy every > the needs of every userland annotation library, so at least some of them > most likely won't use it. You'd be creating more work for the maintainers > of these frameworks, and they don't standard to gain anything from that > work. > > In terms of performance, there is nothing significant to gain here - any > good annotation engine/framework already caches parsed annotations. > > On the other hand, I would be interested in having support for actual > annotation syntax (not docblocks) added to PHP. Real annotation syntax > could have benefits over parsing docblocks, starting with the fact that > most of what's currently in docblocks is documentation, and thus not very > interesting at run-time for anything other than documentation generators. > (again, documentation generators already have working parsers, and don't > stand to gain anything significant from switching to a native docblock > parser.) - also mind the fact that docblocks are a loose standard with many > more variations since annotation libraries came around. > > The only real downside (in terms of run-time) to adding custom syntax, is > that existing useful annotations (such as @var for property-types) would > not be useful - but in another sense, that's a good thing, because (for the > most part) in existing codebases, these were written as documentation, not > intended for run-time consumption. IDEs and documentation tools can add > support for new annotation syntax, and treat these consistently and code, > which itself can be documented using phpdoc blocks. > > I would support and encourage a C# style syntax and behavior, e.g.: > > use my\lib\DataType; > > [DataType('datetime')] > public $published_date; > > In other words, DataType is a class, implementing an interface for > initialization - everything between the parentheses is interpreted > basically the same way as in an array() statement, and is passed to the > annotation instance after construction via an initialization method defined > by the interface. > > I could elaborate tons more on this subject, as it's something I have spent > a lot of time researching in different languages, prior to writing my own > annotation library. > > It may strike you as odd that someone who implemented an annotation library > based on docblocks is actually against annotations in docblocks - I mainly > chose that option because it was the best option at the time. I'm not a C > programmer, and I do believe that docblocks are the best approach for a > native PHP implementation. For a native implementation, I'd prefer to see a > clear separation between non-functional documentation metadata and > functional annotation objects. While there is some overlap between the two, > much of what is currently written as documentation (for example @var > annotations) could be written as functional annotations when these have a > meaningful purpose. After all, existing code with phpdoc-annotations most > likely was not written with the intent of consuming that metadata at > runtime, unless written for use with an annotation library. > > I would be happy to involve myself deeper in this, if others agree and > would like to work on a new RFC. > You're proposing annotations as C# Attributes. I do think that they should be implemented - but their RFC was declined. I, too, don't think that the documentations should be used for metadata storage - this is not the reason it as created for. You do see that though that many well-known and professional FW and software use it - so I do think that it should be re-considered (I'd vote for that, but I didn't got the opportunity to contribute to PHP since almost all RFCs come with a path :( ). Cof... cof... > > https://wiki.php.net/rfc/annotations > > Good luck convincing php-src folks. > You'd be my hero. > Mine too ;) > First of all, there are already plenty of established userland > > implementations - so there is really no need for this. > > On the contrary, plenty of implementations means there's a need in this > functionality, and it might be a good idea to have one standard > implementation if it can cover like 80% of use cases. > I agree - I think that the implementation should be abstract enough to allow most implementation to just hook in and add their syntax to them.
