# [RFC] Reflection annotations reader - Thread: https://externals.io/message/64652 - Original archive: https://news-web.php.net/php.internals/64652 - Started by Rasmus Schultz on 2013-01-08T02:50:15+00:00 - Messages: 48 - Page 1 of 2: messages 1 to 25 (25 per page, add `?page=N` to the URL) - Next page: https://externals.io/message/64652.md?page=2 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #64652 — Rasmus Schultz — 2013-01-08T02:50:15+00:00 URL: https://externals.io/message/64652#64652 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. - Rasmus Schultz --- ## #64653 — guilhermeblanco@gmail.com — 2013-01-08T03:42:50+00:00 URL: https://externals.io/message/64652#64653 · In reply to: #64652 Cof... cof... https://wiki.php.net/rfc/annotations Good luck convincing php-src folks. You'd be my hero. > 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. > > - Rasmus Schultz > -- Guilherme Blanco MSN: guilhermeblanco@hotmail.com GTalk: guilhermeblanco Toronto - ON/Canada --- ## #64657 — Rafael Dohms — 2013-01-08T08:52:57+00:00 URL: https://externals.io/message/64652#64657 · In reply to: #64653 I agree with Rasmus on this one. Userland solutions are enough to support a in-docblock solution today, the performance gains from making it SPL are too little to matter. However docblocks are a compromise, and not where these should be. I do suggest we revive Guilherme's RFC and try once more to arrive at a "acceptable" syntax. A lot has happened since the last discussion, maybe this time the usefulness of annotations can be further moved along and we can get this patch into core. That would be: https://wiki.php.net/rfc/annotations Maybe moving more towards the implementation described by Rasmus Schultz. On Tue, Jan 8, 2013 at 4:42 AM, guilhermeblanco@gmail.com < guilhermeblanco@gmail.com> wrote: > Cof... cof... > > https://wiki.php.net/rfc/annotations > > Good luck convincing php-src folks. > You'd be my hero. > > > > > > […] > every > > […] > many > > […] > the > > […] > not > > […] > code, > > […] > defined > > […] > spent > > […] > library > > […] > mainly > > […] > see a > > […] > two, > > […] > > > > -- > Guilherme Blanco > MSN: guilhermeblanco@hotmail.com > GTalk: guilhermeblanco > Toronto - ON/Canada > -- Rafael Dohms PHP Evangelist and Community Leader http://doh.ms http://wwwamsterdamphp.nl --- ## #64658 — Stas Malyshev — 2013-01-08T08:55:10+00:00 URL: https://externals.io/message/64652#64658 · In reply to: #64652 Hi! > 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. > > 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. Since when "it does not satisfy all needs of all users, and some of them may end up not using it" is an argument for not including functionality? And how it's more work for maintainers if they just won't use it? > On the other hand, I would be interested in having support for actual > annotation syntax (not docblocks) added to PHP. Real annotation syntax Can we please not hijack the topic? We discussed annotations many times already, if you have better proposal than current RFCs please create your own RFC (or ask one of the current RFC authors for collaboration) and start a new topic -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227 --- ## #64661 — Mike van Riel — 2013-01-08T09:04:35+00:00 URL: https://externals.io/message/64652#64661 · In reply to: #64658 > > […] > > 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 with Stas on this one; I have noticed that there is a real need to parse the meta-data from a DocBlock (not just tags, descriptions as well). phpDocumentor is an example but other projects benefit from this as well. --- ## #64687 — Pierrick Charron — 2013-01-08T13:46:42+00:00 URL: https://externals.io/message/64652#64687 · In reply to: #64658 > 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, there is a need in this functionality, but all those userland implementations were at the first place made because this functionality was not part of the language. I think docblocks is not the solution, doc blocks are just comments, and I would expect any code to work the same way if I remove my comments. Pierrick --- ## #64694 — Yahav Gindi Bar — 2013-01-08T17:19:33+00:00 URL: https://externals.io/message/64652#64694 · In reply to: #64687 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: > > > 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 > > […] > > 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. --- ## #64697 — Stas Malyshev — 2013-01-08T18:28:57+00:00 URL: https://externals.io/message/64652#64697 · In reply to: #64687 Hi! > I agree, there is a need in this functionality, but all those userland > implementations were at the first place made because this > functionality was not part of the language. I think docblocks is not > the solution, doc blocks are just comments, and I would expect any > code to work the same way if I remove my comments. So you never used PHPUnit and never will in the future, right? Maybe so, but thousands of other people do, and have no problem with directives in the comments. I think it is time to lay this red herring to rest - nobody who had any encounter with any of the most popular PHP tools really expects it. -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227 --- ## #64698 — Pierrick Charron — 2013-01-08T18:58:16+00:00 URL: https://externals.io/message/64652#64698 · In reply to: #64697 I do use PHP Unit and also Doctrine which uses annotations. And I know that today because there is no native annotations, the implementation use docblocks so I can not remove them :) But still if I did not know anything about PHP and that someone was talking to me about comments, I would expect my code to work even without them. Pierrick > Hi! > > > […] > > So you never used PHPUnit and never will in the future, right? Maybe so, > but thousands of other people do, and have no problem with directives in > the comments. I think it is time to lay this red herring to rest - > nobody who had any encounter with any of the most popular PHP tools > really expects it. > -- > Stanislav Malyshev, Software Architect > SugarCRM: http://www.sugarcrm.com/ > (408)454-6900 ext. 227 --- ## #64699 — Pierre Joye — 2013-01-08T20:10:08+00:00 URL: https://externals.io/message/64652#64699 · In reply to: #64697 hi Stas, > Hi! > > > […] > > So you never used PHPUnit and never will in the future, right? Maybe so, > but thousands of other people do, and have no problem with directives in > the comments. I think it is time to lay this red herring to rest - > nobody who had any encounter with any of the most popular PHP tools > really expects it. Everyone I talked to who implemented annotations in docblocks did it as hack because there is no native support. This is not something that belongs to docblocks. It would be nice if you could take a look at the c# doc, there are really good concepts there. Cheers, -- Pierre @pierrejoye | http://blog.thepimp.net | http://www.libgd.org --- ## #64700 — Vladislav Veselinov — 2013-01-08T20:29:22+00:00 URL: https://externals.io/message/64652#64700 · In reply to: #64699 Exactly. Annotations just don't belong there. Short syntax for arrays got shut a few times but it finally made it to core. I hope native support will be revisited at some point. > hi Stas, > > On Tue, Jan 8, 2013 at 7:28 PM, Stas Malyshev > > wrote: > > […] > > > Everyone I talked to who implemented annotations in docblocks did it > as hack because there is no native support. This is not something that > belongs to docblocks. It would be nice if you could take a look at the > c# doc, there are really good concepts there. > > Cheers, > -- > Pierre > > @pierrejoye | http://blog.thepimp.net | http://www.libgd.org --- ## #64701 — Benjamin Eberlei — 2013-01-08T20:52:35+00:00 URL: https://externals.io/message/64652#64701 · In reply to: #64687 I agree with this very much. In Doctrine we used Docblocks only because its the only means of implementing something that closely resembles native annotation support. I would be happy if we would have a Docblock parser in SPL, so that all libraries can agree on using its syntax, however ultimately its just missing the point that language level annotations would still be very handy. greetings, Benjamin On Tue, Jan 8, 2013 at 2:46 PM, Pierrick Charron wrote: > > > […] > > I agree, there is a need in this functionality, but all those userland > implementations were at the first place made because this > functionality was not part of the language. I think docblocks is not > the solution, doc blocks are just comments, and I would expect any > code to work the same way if I remove my comments. > > Pierrick --- ## #64703 — Mike van Riel — 2013-01-08T21:17:59+00:00 URL: https://externals.io/message/64652#64703 · In reply to: #64694 > 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. If I read this thread correctly then almost everyone agrees that PHPUnit, Symfony, ZF, Doctrine, etc, all use annotations in the DocBlock because there is no available alternative that enables them to use annotations. As far as I am concerned I'd separate this topic into a DocBlock parser (that might take into account the current state of affairs with DocBlock Annotations) and actual Annotation support. Which ever way the annotation discussion goes; fact is that a lot of libraries already use a form of annotations and I believe a DocBlock parser should at least take this into account to facilitate existing projects. > Yahav and all, > > […] > > > 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... I disagree with the above, documentation generators are _unable_ to use the Reflection library of PHP due to issues with Dynamic Reflection and the processing of a large amount of files (report on request) with it. To phpDocumentor and related projects it would be imperative that a DocBlock parser is available without having to use the Reflection extension. --- ## #64704 — Stas Malyshev — 2013-01-08T21:37:00+00:00 URL: https://externals.io/message/64652#64704 · In reply to: #64699 Hi! > Everyone I talked to who implemented annotations in docblocks did it > as hack because there is no native support. This is not something that > belongs to docblocks. It would be nice if you could take a look at the > c# doc, there are really good concepts there. I know why they did it, and we already discussed that stuff in the last annotation discussion. What I mean here is that presenting it as if the notion of meaningful comments is completely unheard of in PHP and nobody expects it is just wrong. Maybe it was so years ago, but it is definitely not true now - de-facto meaningful comments *are* the standard now, and have a lot of use, and nobody with any experience is surprised by them. Regardless of *why* is it so, it is a fact. -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227 --- ## #64705 — Rafael Dohms — 2013-01-08T21:51:08+00:00 URL: https://externals.io/message/64652#64705 · In reply to: #64704 On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev wrote: > Hi! > > > […] > > I know why they did it, and we already discussed that stuff in the last > annotation discussion. What I mean here is that presenting it as if the > notion of meaningful comments is completely unheard of in PHP and nobody > expects it is just wrong. Maybe it was so years ago, but it is > definitely not true now - de-facto meaningful comments *are* the > standard now, and have a lot of use, and nobody with any experience is > surprised by them. Regardless of *why* is it so, it is a fact. > > Stas, That still does not make it the right place. Annotations went into docblocks because it was the only place reflection could provide the needed information at runtime. Just because we now treat docblocks as 1st class citizens does not mean annotations should be there. Does that mean that annotations should be in docblocks and not in core for the reason of "we all know docblocks exist". I would seriously expect at the very least a stronger reason. These were some of the ones i heard before: 1. The syntax is crap: this is solvable, let's find the right syntax 2. PHP does not need it: i think we have proven the use already, every major FW has a implementation of this, there is clearly demand. So if we are going to get anywhere with this discussion I suggest getting back to the original RFC and working on solving the issues instead of discussing developer folklore. -- Rafael Dohms PHP Evangelist and Community Leader http://doh.ms http://wwwamsterdamphp.nl --- ## #64707 — Yahav Gindi Bar — 2013-01-08T22:42:36+00:00 URL: https://externals.io/message/64652#64707 · In reply to: #64705 > If I read this thread correctly then almost everyone agrees that PHPUnit, > Symfony, ZF, Doctrine, etc, all use annotations in the DocBlock because > there > is no available alternative that enables them to use annotations. > Yes, I understood that too. As far as I am concerned I'd separate this topic into a DocBlock parser (that might take into account the current state of affairs with DocBlock Annotations) and actual Annotation support. I agree. I disagree with the above, documentation generators are _unable_ to use the > Reflection library of PHP due to issues with Dynamic Reflection and the > processing of a large amount of files (report on request) with it. > > To phpDocumentor and related projects it would be imperative that a > DocBlock parser is available without having to use the Reflection > extension. > Even so, I think that a pointer to that function should be present in the Reflection, so even if we got SPL parser, one could access it using Reflection since it's the obvious way he/she would look for that. On Tue, Jan 8, 2013 at 11:51 PM, Rafael Dohms wrote: > On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev > […] > > > […] > > That still does not make it the right place. Annotations went into > docblocks > because it was the only place reflection could provide the needed > information at > runtime. Just because we now treat docblocks as 1st class citizens does not > mean annotations should be there. > > Does that mean that annotations should be in docblocks and not in core > for the reason of "we all know docblocks exist". I would seriously expect > at the very least a stronger reason. These were some of the ones i heard > before: > > 1. The syntax is crap: this is solvable, let's find the right syntax > 2. PHP does not need it: i think we have proven the use already, every > major FW has a > implementation of this, there is clearly demand. > > So if we are going to get anywhere with this discussion I suggest getting > back to > the original RFC and working on solving the issues instead of discussing > developer folklore. > > -- > Rafael Dohms > PHP Evangelist and Community Leader > http://doh.ms > http://wwwamsterdamphp.nl > I, too, think that we should re-consider using Annotation. This feature proved itself as usable My opinion is that we should separate this discussion into two fields which will get their own RFC: - We should recreate / reconsider the Annotation feature. It proved itself as something that developers wish to get, and they mix between abilities (the ability to write documentation in userland) just to achieve that because we didn't provided that. - A doc-block parser (in SPL, core or whatever) that can analyze the doc-comment and separate it. I think that we should still implement this even if we'll have Annotation because this is a usable feature in PHP that can give information for writing API's and such. However, in case Annotations will be implemented - I understand that you may say that my argument is weak. --- ## #64706 — Pierre Joye — 2013-01-08T22:42:46+00:00 URL: https://externals.io/message/64652#64706 · In reply to: #64704 > Hi! > > > […] > > I know why they did it, and we already discussed that stuff in the last > annotation discussion. What I mean here is that presenting it as if the > notion of meaningful comments is completely unheard of in PHP and nobody > expects it is just wrong. Maybe it was so years ago, but it is > definitely not true now - de-facto meaningful comments *are* the > standard now, and have a lot of use, and nobody with any experience is > surprised by them. Regardless of *why* is it so, it is a fact. Just like any feature not implemented and created using php scripts. That does not mean we have to use the same hacks to provide native annotations support. Really not. -- Pierre @pierrejoye | http://blog.thepimp.net | http://www.libgd.org --- ## #64710 — guilhermeblanco@gmail.com — 2013-01-09T00:11:07+00:00 URL: https://externals.io/message/64652#64710 · In reply to: #64707 Hi internals, Just like before, people are confusing documentation support with behavioral support. No matter what people say, documentation is documentation and code still behaves the same with and without the comment docblock. When talking about behavioral marks, removing that piece makes your code crash. While creating Doctrine Common Annotations, I was forced to add them in the docblock because there was no way in the language to not place it there. This is not an excuse to tell everyone now that only because different tools used docblocks (because of the lack of support), this is now the standard. It is a hack using the documentation support to add behavioral support, point made. Of course it does not invalidate the documentation. Docblocks should still have a way to be parsed, but that information is static. I really pushed hard annotations in the past, mainly because I was foreseeing that many tools would start adopting behavioral support. Behaviors can be declared by other ways, like XML, YAML or even PHP. But the fact of bringing things together under different perspectives (read as aspects) turns a certain piece of code more powerful and informative than ever. I wanted to use the term aspects on purpose because that is another subject that people normally bring in about highly coupled classes. This is conceptually wrong because if I only want to populate class properties, I don't even touch other aspects like validation and filtering, so there's no coupling, since code is used/dependent elsewhere. Another point that got mentioned in the past was the lack of standardization of annotations, which would lead different projects a good portion of time to refactor to accommodate possible new support. Currently, the status is quite different from 2010. Now, except phpunit, almost all major projects are pointing to Doctrine Common Annotations. Some examples are Doctrine itself, Symfony, Zend Framework, Drupal, PPI, Flow3 and many others that I can bring here. It does seem to me that language requires this functionality like 2 years ago, and everyone is paying the price by using a hacked solution that now people claim it's the standard. No, it's not the standard and it will never be. What happened is that annotations indeed became a standard in PHP using a hack due to the lack of support in core and it seems more and more we delay the inclusion it will get worse to remove this hack because of this "standardization". I wonder if that was the idea back in 2010, or maybe if it was due to the lack of knowledge, interest or willingness. For those still wondering how it could be applied, here are some links: http://drupal.org/node/1882526 http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/annotations.html https://packages.zendframework.com/docs/latest/manual/en/modules/zend.form.quick-start.html#using-annotations http://symfony.com/doc/master/book/validation.html I think we should split this discussion to 2 points. One that details Annotations support for the language and a second one, as a PECL extension that add Docblock parsong support. For Annotations, I recommend that you guys that a look at RFC I created back in 2010: https://wiki.php.net/rfc/annotations The docblock one (https://wiki.php.net/rfc/annotations-in-docblock) was abandoned because I faced different problems that couldn't fix without requiring a more powerful solution. So, do you guys wanna discuss again this possible inclusion? > > […] > > Yes, I understood that too. > > > As far as I am concerned I'd separate this topic into a DocBlock parser > (that > might take into account the current state of affairs with DocBlock > Annotations) > and actual Annotation support. > > I agree. > > > I disagree with the above, documentation generators are _unable_ to use the > > […] > > Even so, I think that a pointer to that function should be present in the > Reflection, so even if we got SPL parser, one could access it using > Reflection since it's the obvious way he/she would look for that. > > > > > On Tue, Jan 8, 2013 at 11:51 PM, Rafael Dohms > […] > > > […] > that > > […] > the > > […] > nobody > > […] > not > > […] > > I, too, think that we should re-consider using Annotation. This feature > proved itself as usable > My opinion is that we should separate this discussion into two fields which > will get their own RFC: > - We should recreate / reconsider the Annotation feature. It proved itself > as something that developers wish to get, and they mix between abilities > (the ability to write documentation in userland) just to achieve that > because we didn't provided that. > - A doc-block parser (in SPL, core or whatever) that can analyze the > doc-comment and separate it. I think that we should still implement this > even if we'll have Annotation because this is a usable feature in PHP that > can give information for writing API's and such. However, in case > Annotations will be implemented - I understand that you may say that my > argument is weak. > -- Guilherme Blanco MSN: guilhermeblanco@hotmail.com GTalk: guilhermeblanco Toronto - ON/Canada --- ## #64711 — Rasmus Schultz — 2013-01-09T01:08:47+00:00 URL: https://externals.io/message/64652#64711 I've started working on a new proposal, but I'm getting hung up on the syntax - if we can't use angle brackets anymore, what can we use? Virtually every symbol on a standard US keyword is an operator of some sort, does that mean those are all out of the question? e.g. thinking of concrete possible basic syntax, neither of the following delimiters would work: [Foo('bar')] {Foo('bar')} And presumably none of the following would work either: ~Foo('bar') @Foo('bar') ^Foo('bar') *Foo('bar') &Foo('bar') :Foo('bar') Can you think of anything that would work? On Tue, Jan 8, 2013 at 3:57 AM, Vladislav Veselinov wrote: > Assume that you have this class with your proposed syntax: > > [SomeAnnotation('somevalue')] > class Test { > > } > > This conflicts with the short array syntax. It looks like an array > containing the result of the function 'SomeAnnotation' invoked with > the parameter 'somevalue'. > The only difference is the missing ";" but relying on this to > determine whether this is an annotation or not would be insane. > I'd support such a decision but with other syntax. > > I like Guilherme's RFC. I just don't think that the syntax is very PHPish. --- ## #64712 — Rasmus Schultz — 2013-01-09T01:38:43+00:00 URL: https://externals.io/message/64652#64712 · In reply to: #64658 To summarize: A native implementation of PHP-DOC block parser for run-time purposes (annotation libraries) is already available in the Reflection API, and already goes as deep as it needs to - going beyond simply finding and extracting the docblocks would make little sense, as every annotation library has it's own individual syntax, behaviors and features. There may be a some libraries that could use a native implementation if it happens to fit their needs, but they most likely won't use it, because (A) they won't win anything by doing so, and (B) these libraries would become incompatible with anything other than bleeding-edge PHP. A native implementation of PHP-DOC parser for offline purposes (documentation generators) is already available in userland, does the job fine, and does not rely on the Reflection API (as someone mentioned) because loading every class in a large codebase is not feasible. If you provide a separate PHP-DOC parser, these projects most likely won't use it, because (A) see above and (B) see above. Who else would need to parse PHP-DOC blocks and why? Bottom line, who is this feature for, what will they do with it, and most importantly, why would they use it? On Tue, Jan 8, 2013 at 3:55 AM, Stas Malyshev wrote: > Hi! > > > […] > > 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. > > > […] > every > > […] > > Since when "it does not satisfy all needs of all users, and some of them > may end up not using it" is an argument for not including functionality? > And how it's more work for maintainers if they just won't use it? > > > […] > > Can we please not hijack the topic? We discussed annotations many times > already, if you have better proposal than current RFCs please create > your own RFC (or ask one of the current RFC authors for collaboration) > and start a new topic > > -- > Stanislav Malyshev, Software Architect > SugarCRM: http://www.sugarcrm.com/ > (408)454-6900 ext. 227 --- ## #64713 — Clint Priest — 2013-01-09T02:06:33+00:00 URL: https://externals.io/message/64652#64713 · In reply to: #64712 If we had true annotations, its certainly something the engine could put to use... See my previous post in this thread. -Clint > To summarize: > > A native implementation of PHP-DOC block parser for run-time purposes > (annotation libraries) is already available in the Reflection API, and > already goes as deep as it needs to - going beyond simply finding and > extracting the docblocks would make little sense, as every annotation > library has it's own individual syntax, behaviors and features. There may > be a some libraries that could use a native implementation if it happens to > fit their needs, but they most likely won't use it, because (A) they won't > win anything by doing so, and (B) these libraries would become incompatible > with anything other than bleeding-edge PHP. > > A native implementation of PHP-DOC parser for offline purposes > (documentation generators) is already available in userland, does the job > fine, and does not rely on the Reflection API (as someone mentioned) > because loading every class in a large codebase is not feasible. If you > provide a separate PHP-DOC parser, these projects most likely won't use it, > because (A) see above and (B) see above. > > Who else would need to parse PHP-DOC blocks and why? > > Bottom line, who is this feature for, what will they do with it, and most > importantly, why would they use it? > > > On Tue, Jan 8, 2013 at 3:55 AM, Stas Malyshev wrote: > > > […] --- ## #64714 — guilhermeblanco@gmail.com — 2013-01-09T02:10:17+00:00 URL: https://externals.io/message/64652#64714 · In reply to: #64711 Hi, At the time Pierrick and I worked on annotations patch, we couldn't use some of the operators due to many different reasons: @ = error supressing [] = short array syntax {} = scopr creation : = all sorts of problems you can imagine & = array referencing We actually found that <> was allowed, so we used this one. Now that short array syntax has evolved a lot from original patch, maybe [] is supported again. > I've started working on a new proposal, but I'm getting hung up on the > syntax - if we can't use angle brackets anymore, what can we use? Virtually > every symbol on a standard US keyword is an operator of some sort, does > that mean those are all out of the question? > > e.g. thinking of concrete possible basic syntax, neither of the following > delimiters would work: > > [Foo('bar')] > > > > {Foo('bar')} > > And presumably none of the following would work either: > > ~Foo('bar') > @Foo('bar') > ^Foo('bar') > *Foo('bar') > &Foo('bar') > :Foo('bar') > > Can you think of anything that would work? > > > On Tue, Jan 8, 2013 at 3:57 AM, Vladislav Veselinov > wrote: > > > […] > PHPish. > > […] > -- Guilherme Blanco MSN: guilhermeblanco@hotmail.com GTalk: guilhermeblanco Toronto - ON/Canada --- ## #64715 — Pierrick Charron — 2013-01-09T05:38:52+00:00 URL: https://externals.io/message/64652#64715 · In reply to: #64714 Unfortunately [] is still not usable because it will introduce syntax ambiguity with short array syntax. The patch we've done for annotations would require some small change to work on the new master version but I can take some time to do it if I see some interest in the proposal. If someone want to try it how everything would work, a patched version of the old master (from may) can be founded here : https://github.com/adoy/php-src/tree/annotations-v3 (tests are in tests/annotations). Pierrick On 8 January 2013 21:10, guilhermeblanco@gmail.com wrote: > Hi, > > At the time Pierrick and I worked on annotations patch, we couldn't use > some of the operators due to many different reasons: > @ = error supressing > [] = short array syntax > {} = scopr creation > : = all sorts of problems you can imagine > & = array referencing > > We actually found that <> was allowed, so we used this one. > Now that short array syntax has evolved a lot from original patch, maybe [] > is supported again. > > > > > > […] > > > > -- > Guilherme Blanco > MSN: guilhermeblanco@hotmail.com > GTalk: guilhermeblanco > Toronto - ON/Canada --- ## #64716 — Mike van Riel — 2013-01-09T06:01:56+00:00 URL: https://externals.io/message/64652#64716 · In reply to: #64712 > A native implementation of PHP-DOC block parser for run-time purposes > (annotation libraries) is already available in the Reflection API, There is no DocBlock parser in the Reflection API; you can merely retrieve the `T_DOC_COMMENT` token. > and > already goes as deep as it needs to - going beyond simply finding and > extracting the docblocks would make little sense, as every annotation > library has it's own individual syntax, behaviors and features. There are other types of project that benefit from the parsing of the actual DocBlock without any support for Annotations. Examples follow below. > There may > be a some libraries that could use a native implementation if it > happens to > fit their needs, but they most likely won't use it, because (A) they > won't > win anything by doing so, and (B) these libraries would become > incompatible > with anything other than bleeding-edge PHP. I disagree with this, A) Said applications and libraries win in the terms of performance and standardization; this will offer a baseline for IDEs to offer proper support for descriptions and tags and even more advanced features. B) This issue arises with _any_ new feature that substitutes or empowers a userland functionality and I thus consider it a non-argument. I am Lead Developer of phpDocumentor and I promise you, I'd use this. > A native implementation of PHP-DOC parser for offline purposes > (documentation generators) is already available in userland, does the > job > fine, and does not rely on the Reflection API (as someone mentioned) > because loading every class in a large codebase is not feasible. If > you > provide a separate PHP-DOC parser, these projects most likely won't > use it, > because (A) see above and (B) see above. Performance is key with documentation generators. Since DocBlocks are the most prevalent thing in a code base they could win with a core implementation. Also, as provided earlier, would standardization benefit the whole community that consumes DocBlocks and IDE vendors. > Who else would need to parse PHP-DOC blocks and why? * WSDL Generators to extract descriptions and type information * REST API documentation generators for the same reason * HATEOAS libraries could benefit from the reading of the @uses tag * Command Line Application frameworks could use the Command class' description for their help screen. And more uses that I cannot think of within a few seconds. --- ## #64717 — guilhermeblanco@gmail.com — 2013-01-09T06:16:38+00:00 URL: https://externals.io/message/64652#64717 · In reply to: #64716 But I can add more. Filtering Validation Form declaration Database mapping Joinpoint definitions (AOP) Service Injection (look at FLOW3) Testing etc Basically everything can define constraints or usage of an element, behavior, process or nature of an element. Let me give some individual examples: Constraints: @MinLength, @NotNull Behavior: @Transactional, @Inject Process: @Column, @XmlElement, @OneToOne Nature: @Entity, @Table, @WebService, @TestCase Makes more sense now? On Wed, Jan 9, 2013 at 1:01 AM, Mike van Riel wrote: > > > > […] > > There is no DocBlock parser in the Reflection API; you can merely > retrieve the `T_DOC_COMMENT` token. > > > and > > […] > > There are other types of project that benefit from the parsing of the > actual DocBlock without any support for Annotations. Examples follow below. > > > There may > > […] > > I disagree with this, > > A) Said applications and libraries win in the terms of performance and > standardization; this will offer a baseline for IDEs to offer proper > support for descriptions and tags and even more advanced features. > B) This issue arises with _any_ new feature that substitutes or empowers > a userland functionality and I thus consider it a non-argument. > I am Lead Developer of phpDocumentor and I promise you, I'd use this. > > > A native implementation of PHP-DOC parser for offline purposes > > […] > > Performance is key with documentation generators. Since DocBlocks are the > most prevalent thing in a code base they could win with a core > implementation. > Also, as provided earlier, would standardization benefit the whole > community > that consumes DocBlocks and IDE vendors. > > > Who else would need to parse PHP-DOC blocks and why? > > […] > > * WSDL Generators to extract descriptions and type information > * REST API documentation generators for the same reason > * HATEOAS libraries could benefit from the reading of the @uses tag > * Command Line Application frameworks could use the Command class' > description > for their help screen. > > And more uses that I cannot think of within a few seconds. > > > > -- > > > > -- Guilherme Blanco MSN: guilhermeblanco@hotmail.com GTalk: guilhermeblanco Toronto - ON/Canada --- Next page: https://externals.io/message/64652.md?page=2