PHP Annotations RFC + Patch

Hi!

1. In Java annotations are a special type of an interface. But due the
   lack of type hinting for scalar values we cannot use this construct,
   because we cannot put some validation logic in an interface. My proposal

I'm not sure I understand - what scalar type hints have to do with it?
Anyway, annotation can't be interface since you'd have to instantiate it
to get the values. Interface can't have values.

is to create a new "annotation" type. This type should have the same
rules as a class and should contain all features proposed in the
ReflectionAnnotation class. With this construct it should be possible to
use named or unnamed parameters for an annotation.

I think this is very bad idea - to have language construct that is
exactly like class but has different set of features. If named
parameters are needed in PHP, let's add named parameters in PHP. But if
we decide they are not needed in PHP, they shouldn't be in one
particular corner of a particular syntax construct and nowhere else.
This makes the language hard to learn and hard to understand - you never
know what surprise the next syntax construct will bring you. I'm very
strongly against only one construct in the language having named
parameters syntax while other places don't.

2. The syntax for arrays should be the same as in PHP. So we can use the
   [] as annotation separator. When we allow expressions in the form
   Annotation(array('value' => 4 %2)) or Annotation(array('value' =>
   !MY_CONSTANT)) which I think is a valid construct, then we cannot use
   the ! or % as annotation separator.

Where this expression would be evaluated, in which context? Where would
the variable values be stored? What happens if they change?

I think with this changes we have a separate language construct like
traits, which does allow a new syntax.

Separate language construct doesn't mean separate rules. We are still in
the same language, so we can't just randomly put arbitrary set of
features together and call it a new construct. There should be some
commonality between different language constructs within the same language.

Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227

Hi All,

There seems to be a lot of discussion as to syntax for annotations at
the moment. Firstly I'd like to say that I've never delved into PHP
internals so may not understand some of the reasons why some of my
suggestions may not work, so please don't give me a hard time about it!
I also have no experience with using annotations in any language per
se. This is just the viewpoints of an observer of this discussion.

There seem to be the following concerns:

1. Use of ! or % as a an annotation separator would conflict.
2. Use of [] would prevent the use of them as a shorthand for array()
3. Many other languages use @, but that is the PHP silence operator.
4. Annotations need their own construct and phpdoc won't suit.

I had a few options to try and address all of these:

1. Use a comment-like syntax. phpdoc uses /** /, so perhaps trying
   something like /! / or /@ */ could be answer. If this special
   comment was parsed and treated differently to a standard comment then
   you could also use any syntax you'd like to define for annotations
   without worrying about conflicts with PHP. (I realise that PHP does not
   know anything about phpdoc tags.) The above are suitable if annotations
   will be allowed to span multiple lines. Otherwise some other single
   line comment syntax could be suitable: //@ or #@. One complaint about
   this might be the confusion of excess comments.

An advantage is that if annotations are disabled PHP will just skip over
a comment while parsing, or, if an older version of PHP is in use, this
is backward-compatible code. A disadvantage is that people don't think
of comments as being able to affect code.

class DatabaseObject {
/**
* A function that does something to the database object...
/
/!
* JoinTable(array(
* 'name' => 'users_phonenumbers',
* 'joinColumns' => array(
* array('name' => 'user_id', 'referencedColumnName' => 'id'),
* ),
* 'inverseJoinColumns' => array(
* array('name' => 'phonenumber_id', 'referencedColumnName' => 'id',
* 'unique' => true),
* ))
*/
public function something() { ... }
}

class Mailer {
/**
* Send e-mail to a single e-mail address.
*
* @param string $email An e-mail address.
*/
#@ EmailValidation(array('options' => array('checkMX' => true))
public function sendEmail($email) { ... }
}

2. If there is a problem with it being a comment, why not just tweak the
   delimiters slightly? Surely if /* */ can be used for comments something
   like /+ +/ can't be any more awkward? Same advantage in that you could
   switch to a different parsing context and perhaps we can leave [] in the
   eventuality they get implemented as a shorthand for array().
   Alternatively why not try /[ ]/?

class Mailer {
/**
* Send e-mail to a single e-mail address.
*
* @param string $email An e-mail address.
*/
/+
+ EmailValidation(array('options' => array('checkMX' => true))
+/
public function sendEmail($email) { ... }
}

class Mailer {
/**
* Send e-mail to a single e-mail address.
*
* @param string $email An e-mail address.
*/
/[ EmailValidation(array('options' => array('checkMX' => true)) ]/
public function sendEmail($email) { ... }
}

Anyway. Just some thoughts.

Cheers,

Nick

Hi Stas,

this type of annotations cannot be used as PHPDoc annotations due its
different syntax. In other languages like Java, C# or AS3 annotations
are an independent language construct and I think in PHP it should be
the same. I dont know how many non-performant user-land
implementations(hacks), with different syntaxes and concepts, exists in
the meantime. So I think it is time for a consistent syntax in the PHP
core.

I see your concerns about the inconsistency in the syntax, so here are
my thoughts how we can avoid this.

1. In Java annotations are a special type of an interface. But due the
   lack of type hinting for scalar values we cannot use this construct,
   because we cannot put some validation logic in an interface. My proposal
   is to create a new "annotation" type. This type should have the same
   rules as a class and should contain all features proposed in the
   ReflectionAnnotation class. With this construct it should be possible to
   use named or unnamed parameters for an annotation.

annotation URL {

 public $url;
 public $title;
 public $target;

 public function __construct($url, $title, $target = 'self') {

 }

}

[URL('http://www.php.net',http://www.php.net%27, 'PHP', 'blank')] or
[URL('http://www.php.net',http://www.php.net%27, 'PHP')] or
[URL('url' = 'http://www.php.net',http://www.php.net%27, 'name' = 'PHP', 'target' = 'blank')]

With this new type there exists a new language construct which doesn't
overlap with the class construct. So it is possible to use its own
instantiation syntax.

2. The syntax for arrays should be the same as in PHP. So we can use the
   [] as annotation separator. When we allow expressions in the form
   Annotation(array('value' => 4 %2)) or Annotation(array('value' =>
   !MY_CONSTANT)) which I think is a valid construct, then we cannot use
   the ! or % as annotation separator.

3. For the consistency with named parameters there exists 2
   possibilities. Either we implement named parameters in the PHP core or
   named parameters are an exception for annotations.

I think with this changes we have a separate language construct like
traits, which does allow a new syntax.

Greetings,
Christian

Am 12.09.2010 00:48, schrieb Stas Malyshev:

Hi!

It seems that there is a misunderstanding about the goals of the
annotations. They are not meant to be read by human being
(javadoc/phpdoc/etc. are) but to be parsed automatically to be used
for services.

If it's for services/phpdoc, why can't it be part of phpdoc?

I see here a whole new language syntax being invented, complete with
nested constructs, new instantiation syntax, new argument parsing
rules and what not. All that while tiniest attempts on introducing
syntax sugar were consistently rejected. But here we have sub-section
of language with totally different rules - PHP has no named
parameters, but annotations have them, PHP has no array/instantiation
shortcut syntax, but annotations have it, etc. Please understand, I'm
not objecting to a particular detail of syntax - I'm objecting to the
fact that the design of the language appears to be guided by a random
whim.

At 16:39 13/09/2010, Pierre Joye wrote:

You are not serioulsy suggesting to use phpdoc for runtime annotation
support? Are you?

I actually am (either that or get what you want done in some other
way). It's a rare enough use case that I think it's a very
reasonable compromise. The disadvantages of adding a whole new
branch of syntax, for this rare use case, far outweigh its advantages - IMHO.

Besides that, did you look at the other languages annotation support
and how and why they are used?

I have but I think we've hashed this many times in the past - PHP is
PHP, not C# or Java. There's a serious cost in complexity with every
new feature we add - especially a complicated syntax-rich feature
like that - which I believe we all too often fail to factor into our
discussions.

Zeev

Benjamin,

Strictly speaking annotations are not needed. They simply aren't -
you can do anything and everything you might want to do without
them. You can argue that the value they bring is very important, and
that it outweighs the complexity they bring upon to the language - in
which case we can agree to disagree.

Zeev

At 17:38 13/09/2010, Benjamin Eberlei wrote:

I strongly disagree!

PHPDocs are for what their name suggests, for comments, not for runtime
code information. They allow arbitrary characters, their intent is for
human-readible documentation only.

Yet they are used for service description (Zend_Soap_Autodiscover,
Zend_XmlRpc), metadata mapping or phpunits "annotations", just because
there is nothing better suited.

Primary difference of Annotations, they are not only human- but also
enforced to be machine-readable. Annotations are runtime configuration or
metadata, throwing compile time parse errors when not followed correctly.
That has nothing to do with documentation, it is an very elegant way to
extend classes, methods and properties with metadata information,
configuration and code right next to each other.

The primary target for annotations are framework and library integrations:
validation, forms, metadata mapping, static mvc configuration such as
routing, view selection or acls. Why do these features not exist with
current php libraries yet? Because developers see php doc blocks for what
they are: Comments!

With Doctrine2 and Symfony2 we see some early experiments with annotations
in PHP Docs, but they only highlight the drawbacks:

1. Developers should expect to be able to delete a comment/docblock
   without altering the code-path.
2. Errors in the Doc-Blocks "expected formatting" are left for the
   userland developer to detect. IDEs or the PHP Parser simply don't care.
3. There is no real difference for a human only readable doclbock starting
   with /** or /, however PHP just doesnt publish the / docblocks to the
   userland, leading to countless errors when that single star is missing.
4. every IDE or code-highlighting prints them in light grey, making them
   sort of invisible.

That is why annotations are needed, they make metadata a language level
construct, not a hack that is possible, because Reflection allows us to
access the comments of methods, functions, classes, ...

greetings,
Benjamin

At 20:24 11/09/2010, Pierre Joye wrote:

On Sat, Sep 11, 2010 at 8:19 PM, Stas Malyshev smalyshev@sugarcrm.com
wrote:

Hi!

The separator never was a problem... but I definately don't want to
see another 6 months just to define what would the separator be.
If we need to drop [] in favor of array support, I vote for ! as
separator.

The separator is not a problem (even though 1-char one produces much
less
clutter). The cryptic syntax is.

It seems that there is a misunderstanding about the goals of the
annotations. They are not meant to be read by human being
(javadoc/phpdoc/etc. are) but to be parsed automatically to be used
for services.

In that sense, to have a syntax closed to one of the best (or less
worst, if you are on the opposed side ;-) syntax out there (c#/.net)
may be a good thing to do, instead of re einventing the php wheel.

I'm not sure we've seen a good reason to add annotations instead of
using PHPDoc. Sure, PHPDoc isn't a perfect fit for certain purposes,
but I think it certainly falls in the good-enough fit for most
purposes. It's also both machine and human readable, and best of all

• it's already there.
  There should be overwhelmingly strong reasons to add a whole new
  branch of syntax to PHP, I for one don't see the huge gain
  annotations bring on top of PHPDoc.

Zeev

Hi Benjamin,

I agree with you 100 percent.

Greetings,
Christian

On Mon, 13 Sep 2010 17:38:37 +0200, Benjamin Eberlei
kontakt@beberlei.de wrote:

I strongly disagree!

PHPDocs are for what their name suggests, for comments, not for runtime
code information. They allow arbitrary characters, their intent is for
human-readible documentation only.

Yet they are used for service description (Zend_Soap_Autodiscover,
Zend_XmlRpc), metadata mapping or phpunits "annotations", just because
there is nothing better suited.

Primary difference of Annotations, they are not only human- but also
enforced to be machine-readable. Annotations are runtime configuration or
metadata, throwing compile time parse errors when not followed correctly.
That has nothing to do with documentation, it is an very elegant way to
extend classes, methods and properties with metadata information,
configuration and code right next to each other.

The primary target for annotations are framework and library integrations:
validation, forms, metadata mapping, static mvc configuration such as
routing, view selection or acls. Why do these features not exist with
current php libraries yet? Because developers see php doc blocks for what
they are: Comments!

With Doctrine2 and Symfony2 we see some early experiments with annotations
in PHP Docs, but they only highlight the drawbacks:

1. Developers should expect to be able to delete a comment/docblock
   without altering the code-path.
2. Errors in the Doc-Blocks "expected formatting" are left for the
   userland developer to detect. IDEs or the PHP Parser simply don't care.
3. There is no real difference for a human only readable doclbock starting
   with /** or /, however PHP just doesnt publish the / docblocks to the
   userland, leading to countless errors when that single star is missing.
4. every IDE or code-highlighting prints them in light grey, making them
   sort of invisible.

That is why annotations are needed, they make metadata a language level
construct, not a hack that is possible, because Reflection allows us to
access the comments of methods, functions, classes, ...

greetings,
Benjamin

At 20:24 11/09/2010, Pierre Joye wrote:

On Sat, Sep 11, 2010 at 8:19 PM, Stas Malyshev smalyshev@sugarcrm.com
wrote:

Hi!

The separator never was a problem... but I definately don't want to
see another 6 months just to define what would the separator be.
If we need to drop [] in favor of array support, I vote for ! as
separator.

The separator is not a problem (even though 1-char one produces much
less
clutter). The cryptic syntax is.

It seems that there is a misunderstanding about the goals of the
annotations. They are not meant to be read by human being
(javadoc/phpdoc/etc. are) but to be parsed automatically to be used
for services.

In that sense, to have a syntax closed to one of the best (or less
worst, if you are on the opposed side ;-) syntax out there (c#/.net)
may be a good thing to do, instead of re einventing the php wheel.

I'm not sure we've seen a good reason to add annotations instead of
using PHPDoc. Sure, PHPDoc isn't a perfect fit for certain purposes,
but I think it certainly falls in the good-enough fit for most
purposes. It's also both machine and human readable, and best of all

• it's already there.
  There should be overwhelmingly strong reasons to add a whole new
  branch of syntax to PHP, I for one don't see the huge gain
  annotations bring on top of PHPDoc.

Zeev

The primary target for annotations are framework and library integrations:
validation, forms, metadata mapping, static mvc configuration such as
routing, view selection or acls. Why do these features not exist with
current php libraries yet? Because developers see php doc blocks for what
they are: Comments!

I think my main issue with these use cases is that I fundamentally don't
believe they should be done at runtime. These are all things that are
not going to change from one request to the next and as such should not
be evaluated on every single request.

-Rasmus

Hi!

PHPDocs are for what their name suggests, for comments, not for runtime
code information. They allow arbitrary characters, their intent is for
human-readible documentation only.

Nothing prevents us from using phpdocs for non-human-reading purposes.
Actually, there is quite a lot of code that already does it
successfully. I don't see anything heretical in having phpdoc tag parser
in reflection and using it for metadata purposes - after all, phpdoc
currently IS being used as metadata and actually it was its intent from
the start.

Primary difference of Annotations, they are not only human- but also
enforced to be machine-readable. Annotations are runtime configuration or

phpdoc tags are enforced to be machine readable as well.

metadata, throwing compile time parse errors when not followed correctly.

There's no such thing as compile time in PHP. Practically everything in
PHP is runtime. And as I see, people want validation logic in their
annotations - which makes it even more runtime.

That has nothing to do with documentation, it is an very elegant way to
extend classes, methods and properties with metadata information,
configuration and code right next to each other.

What prevents you from using plain old way of adding information to
classes? I understand that new syntax is much cooler than boring old one

• but besides that?

1. Developers should expect to be able to delete a comment/docblock
   without altering the code-path.

It's circular argument. If phpdoc is used for metadata, they can't.

2. Errors in the Doc-Blocks "expected formatting" are left for the
   userland developer to detect. IDEs or the PHP Parser simply don't care.

How it's a bad thing? IDEs can do whatever they want, and PHP parser
shouldn't be broken by metadata.

3. There is no real difference for a human only readable doclbock starting
   with /** or /, however PHP just doesnt publish the / docblocks to the
   userland, leading to countless errors when that single star is missing.

If you miss single dollar, comma or = sign, there could be errors too. So?

4. every IDE or code-highlighting prints them in light grey, making them
   sort of invisible.

Fix your IDE. My IDE knows about what phpdoc tags are :) Some IDEs
lagging behind is not an argument in language design. IDEs can be fixed.

Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227

There should be overwhelmingly strong reasons to add a whole new branch
of syntax to PHP, I for one don't see the huge gain annotations bring
on top of PHPDoc.

The only thing I can think of is added the storing of docblock data for
class methods and class properties. Right now I think they're not being
stored in the oparrays? In any case, I am also not for adding more
syntax just to do annotations.

Have you read my e-mail?

http://news.php.net/php.internals/49674

I don't understand whether you're against annotations per se or if using
doc comments to implement annotations would be okay.

As I said, doc comments as they are now are insufficient.

--
Gustavo Lopes