Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:64703
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain naenius.com designates 83.96.159.14 as permitted sender)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 7bit
Date: Tue, 08 Jan 2013 22:17:59 +0100
To: Yahav Gindi Bar <g.b.yahav@gmail.com>
Cc: Pierrick Charron <pierrick@webstart.fr>, Stas Malyshev
 <smalyshev@sugarcrm.com>, Rasmus Schultz <rasmus@mindplay.dk>,
 <internals@lists.php.net>
In-Reply-To: <CANVTSm7D8RQWB80o5GD3MCZNKn6DPwfOH-ydYy7ksW2syZpyTg@mail.gmail.com>
References: <CADqTB_h4eh4mPi89uRps6vZWXjDEhUtcBopL7jmO-UgRuyf19w@mail.gmail.com>
 <50EBDEEE.8070605@sugarcrm.com>
 <CAOfKkdQXh53oxpCQ59R_hcws4Pd=q+O_VMOZ=tS+F2_7qof3RA@mail.gmail.com>
 <CANVTSm7D8RQWB80o5GD3MCZNKn6DPwfOH-ydYy7ksW2syZpyTg@mail.gmail.com>
Message-ID: <7710f59e26e95f23a7f6aff8892b881a@naenius.com>
User-Agent: Web-Oke Webmail/0.7.1
Subject: Re: [PHP-DEV] [RFC] Reflection annotations reader
From: mike.vanriel@naenius.com (Mike van Riel)

On 08.01.2013 18:19, Yahav Gindi Bar wrote:
> 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,
>> 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...

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.