Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:49674
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain nebm.ist.utl.pt from 193.136.128.21 cause and error)
Content-Type: text/plain; charset=iso-8859-15; format=flowed; delsp=yes
To: internals@lists.php.net
References: <39505F13-655A-43AF-941E-77750B7F7201@gmail.com>
 <001601cb543a$d81ebac0$885c3040$@com>
 <AANLkTikxw_xHn2fosykSwTat_qsGA16KriFinqc8Btrq@mail.gmail.com>
 <4C8FC695.2060800@sugarcrm.com>
 <AANLkTimOaicMidzH8oYWcieaCyx2bLefPGkXGQDZPQ6Y@mail.gmail.com>
 <4C8FD72B.1070108@sugarcrm.com>
 <AANLkTimEMdn6Z64O0Jt9KYEdHfDRa0iLt5eh1D16i_st@mail.gmail.com>
 <4C906333.4030204@sugarcrm.com> <7.0.1.0.2.20100915085504.17eab4d8@zend.com>
Date: Wed, 15 Sep 2010 20:24:08 +0100
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Organization: =?iso-8859-15?Q?N=FAcleo_de_Eng=2E_Biom=E9dica_?=
 =?iso-8859-15?Q?do_IST?=
Message-ID: <op.vi29iic1idpuyk@cataphract-old.dulce.lo.geleia.net>
In-Reply-To: <7.0.1.0.2.20100915085504.17eab4d8@zend.com>
User-Agent: Opera Mail/10.61 (Win32)
Subject: Re: [PHP-DEV] Re: Re: PHP Annotations RFC + Patch
From: glopes@nebm.ist.utl.pt ("Gustavo Lopes")

On Wed, 15 Sep 2010 07:55:55 +0100, Zeev Suraski <zeev@zend.com> wrote:

> At 08:09 15/09/2010, Stas Malyshev wrote:
>> Phpdocs aren't "user documentation" only, not for a long time (I mean  
>> the concept, not the particular application called phpDocumentor, of  
>> course). They are being used as metadata in many places. You could  
>> argue that's misguided but you can't ignore the fact that's what people  
>> do. The "goals and usages" of those tags are exactly metadata - and  
>> regardless of the annotations, I'd be happy if Reflection recognized it  
>> finally (by integrating some kind of phpdoc tag parser).
>
> I second that word for word.  FWIW, I don't see it as misguided at all.
>

OK, here's why "doc comments" are insufficient:

1. You have to manually parse them (which is not easy; writing parsers is  
quite error prone). You would also probably need to implement some form of  
annotation inheritance.
2. There's no standardized way to express annotations, so the user will  
have to learn a new syntax for each implementation.
3. Performance issues -- you to have to parse and validate the annotations  
on each request, unless you implement your own caching mechanism. With  
native annotations, you could use opcode caches to do parsing and  
validation only on the first request.
4. Finally, and this is the most significant to me -- since PHP doesn't  
know annotations (it only knows there's a blob a text), you cannot give to  
certain annotations a meaning that would be recognized at an engine. With  
annotations, we could, in the future, implement a special meaning for  
@ReadOnly and @WriteOnly for properties and have stuff like:

@RunBefore("Log::writeMessage")
public LogAnnotation extends ReflectionAnnotation {
	public $value;
}
...

@Log("Enterting method Foo::bar")
@RequiredRole("moderator")
public function bar() { }

without having to run the method through a framework that would recognize  
those annotations in doc blocks. However, the only thing close to this in  
the current implementation is @Inherited.


Finally, a separate issue is the syntactic one. Could we use the current  
implementation but define the annotations in doc blocks instead?

If it comes to that, it'd be better than nothing. However, It would almost  
certainly break BC (and subjectively, it feels wrong to mix annotations,  
which have real impact on the application, with mere comments).

If the annotations were parsed only on request, it would not break BC in  
the sense that whole old applications would stop working; however, when  
upgrading PHP and the framework to a new version that would support  
annotations, it could misinterpret old doc comments that look like  
annotations (or most likely, malformed annotations). More importantly, it  
would break a compelling reason to have annotations (point 4.).


-- 
Gustavo Lopes