PHP Annotations RFC + Patch

14 years ago by Dmitry Stogov — view source

unread

Hi Pierrick,

I've taken just a quick look into concept and patch. It looks
interesting and might be useful in some areas, but I see several
significant problems:

Have you thought about compatibility with opcode caches? In case I
understood properly, you store annotation as a HashTable of object. But
life-time of objects is restricted by request time, so they won't
persist in opcode cache and will have to be recreated on each request.
It's a huge overhead. I don't have a good solution for this problem
except for using arrays instead of objects.
I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of
corresponding classesm, methods and properties.
I think the annotaton syntax must follow PHP syntax as close as possible

allow leading \ in QualifiedName
use '=>' in arrays

I didn't understand why do we need nested annotations.

The first and second problems are the most important.
I don't like to lose performance of existing applications which don't
use annotations at all. I think the concept must be redesigned a bit.
Also I would like to see an APC patch to check if the implementation
works and doesn't lose performance.

Thanks. Dmitry.

Pierrick Charron wrote:

Hi Dmitry,

As discussed on IRC, here are the RFC and the patch to add Annotation
support in PHP :

RFC : http://wiki.php.net/rfc/annotations

Patch : http://www.adoy.net/php/Annotations.diff

All your feedback and suggestions will be more than welcome.

Thanks again.

Pierrick (or adoy on irc)

14 years ago by Pierrick Charron — view source

unread

Hi Dmitry,

First thanks for having a look at the patch and taking some time to
give your feedback ! It's much appreciated

2010/9/8 Dmitry Stogov dmitry@zend.com:

Hi Pierrick,

I've taken just a quick look into concept and patch. It looks interesting
and might be useful in some areas, but I see several significant problems:

Have you thought about compatibility with opcode caches? In case I
understood properly, you store annotation as a HashTable of object. But
life-time of objects is restricted by request time, so they won't persist in
opcode cache and will have to be recreated on each request. It's a huge
overhead. I don't have a good solution for this problem except for using
arrays instead of objects.

You're right annotations are stored in an HashTable. But this
HashTable doesn't store zval objects directly but zend_annotations.
This is the reflection getAnnotation and getAnnotations method which
are in charge of reading the zend_annotation structures and
instantiating the proper annotation object when needed. The zval named
instance in the zend_annotation structure is there only to point to
the annotation instance at runtime so that the state of the annotation
is kept between two calls to the getAnnotation and getAnnotations on a
same code element (I added this directly into the zend_annotation
structure to make it faster but I can imagine a HashTable like you
mentioned earlier where keys are addresses). I'm not yet quite
familiar with the APC source code but since (and correct me if i'm
wrong) APC save zend_class_entry, etc.. in memory we could modify it
to also save the new HashTable *annotations of those structures (like
you already do for doc_comment) excluding the zval *instance.

I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of corresponding
classesm, methods and properties.

Annotations are metadata related to a code element. IMHO it make sense
to add them in the appropriate code element structures (even
doc_comment is in those structures) so that APC and other cache will
know that this is something part of the code element and it needs to
be cached and so on.

I think the annotaton syntax must follow PHP syntax as close as possible

allow leading \ in QualifiedName

use '=>' in arrays

The actual patch already implement those two points. You can right now
already do

[\My\Own\Annotation(array('foo' => 'bar', 'baz'))]
class FooBar {}

Sorry about that, I just noticed that the EBNF in the RFC was not
updated correctly to reflect those two points. I just made the
modification to replace "=" by "=>" in arrays and allow the optional
leading \ in the QualidifedName

I didn't understand why do we need nested annotations.

Nested annotations could be use for many cases. Doctrine for example
use them a lot to do things like :
[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id", referencedColumnName="id",
unique=true)]
)
)]

The first and second problems are the most important.
I don't like to lose performance of existing applications which don't use
annotations at all. I think the concept must be redesigned a bit.

Right now the only performance decrease is at compile time since the
annotations HashTable are filled by the parser. At runtime you don't
have any performance decrease if you're not using annotations. If you
use them, you'll lose some time when you do getAnnotation() to
instantiate the object, but this instantiation is just done once for
each annotation on a single code element so it make it a little bit
faster if you use them intensively.

Also I would like to see an APC patch to check if the implementation works
and doesn't lose performance.

I will try to work on an APC patch to store the Annotations HashTable
of every code element structure.

Thanks. Dmitry.

Thanks again for your time :)

Pierrick

Pierrick Charron wrote:

Hi Dmitry,

As discussed on IRC, here are the RFC and the patch to add Annotation
support in PHP :

RFC : http://wiki.php.net/rfc/annotations

Patch : http://www.adoy.net/php/Annotations.diff

All your feedback and suggestions will be more than welcome.

Thanks again.

Pierrick (or adoy on irc)

14 years ago by Dmitry Stogov — view source

unread

Pierrick Charron wrote:

Hi Dmitry,

First thanks for having a look at the patch and taking some time to
give your feedback ! It's much appreciated

2010/9/8 Dmitry Stogov dmitry@zend.com:

Hi Pierrick,

I've taken just a quick look into concept and patch. It looks interesting
and might be useful in some areas, but I see several significant problems:

Have you thought about compatibility with opcode caches? In case I
understood properly, you store annotation as a HashTable of object. But
life-time of objects is restricted by request time, so they won't persist in
opcode cache and will have to be recreated on each request. It's a huge
overhead. I don't have a good solution for this problem except for using
arrays instead of objects.

You're right annotations are stored in an HashTable. But this
HashTable doesn't store zval objects directly but zend_annotations.

Then it's not a problem. my mistake.

This is the reflection getAnnotation and getAnnotations method which
are in charge of reading the zend_annotation structures and
instantiating the proper annotation object when needed. The zval named
instance in the zend_annotation structure is there only to point to
the annotation instance at runtime so that the state of the annotation
is kept between two calls to the getAnnotation and getAnnotations on a
same code element (I added this directly into the zend_annotation
structure to make it faster but I can imagine a HashTable like you
mentioned earlier where keys are addresses). I'm not yet quite
familiar with the APC source code but since (and correct me if i'm
wrong) APC save zend_class_entry, etc.. in memory we could modify it
to also save the new HashTable *annotations of those structures (like
you already do for doc_comment) excluding the zval *instance.

I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of corresponding
classesm, methods and properties.

Annotations are metadata related to a code element. IMHO it make sense
to add them in the appropriate code element structures (even
doc_comment is in those structures) so that APC and other cache will
know that this is something part of the code element and it needs to
be cached and so on.

It's easier to keep it in appropriate places, but it's a waste of
memory, because only a few classes will use it. According to doc
comments, in case we accept annotations, I would represent it as a
special kind of annotation.

Separate map(enity -> anotations) would require memory only for defined
annotations. Of course it would be a bit more expensive to read it and
would require special handling in opcode hashes.

I think the annotaton syntax must follow PHP syntax as close as possible

allow leading \ in QualifiedName

use '=>' in arrays

The actual patch already implement those two points. You can right now
already do

[\My\Own\Annotation(array('foo' => 'bar', 'baz'))]
class FooBar {}

Sorry about that, I just noticed that the EBNF in the RFC was not
updated correctly to reflect those two points. I just made the
modification to replace "=" by "=>" in arrays and allow the optional
leading \ in the QualidifedName

great.

I didn't understand why do we need nested annotations.

Nested annotations could be use for many cases. Doctrine for example
use them a lot to do things like :
[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id", referencedColumnName="id",
unique=true)]
)
)]

The first and second problems are the most important.
I don't like to lose performance of existing applications which don't use
annotations at all. I think the concept must be redesigned a bit.

Right now the only performance decrease is at compile time since the
annotations HashTable are filled by the parser.

I assume parser works with near the same speed without annotations. right?

At runtime you don't
have any performance decrease if you're not using annotations. If you
use them, you'll lose some time when you do getAnnotation() to
instantiate the object, but this instantiation is just done once for
each annotation on a single code element so it make it a little bit
faster if you use them intensively.

I see, but assumptions are not always right, often memory consumption
affects performance directly, it's better to check.

Also I would like to see an APC patch to check if the implementation works
and doesn't lose performance.

I will try to work on an APC patch to store the Annotations HashTable
of every code element structure.

In case you have plain C structures (without objects) it shouldn't be a
big problem. I'm more interested to store annotation separately. In this
case APC support would be a bit more difficult.

I could help you with implementation in case the idea accepted in general.

Thanks. Dmitry.

Thanks. Dmitry.

Thanks again for your time :)

Pierrick

Pierrick Charron wrote:

Hi Dmitry,

As discussed on IRC, here are the RFC and the patch to add Annotation
support in PHP :

RFC : http://wiki.php.net/rfc/annotations

Patch : http://www.adoy.net/php/Annotations.diff

All your feedback and suggestions will be more than welcome.

Thanks again.

Pierrick (or adoy on irc)

14 years ago by Guilherme Blanco — view source

unread

Hi Dmitry,

Comments goes inline.

Pierrick Charron wrote:

Hi Dmitry,

First thanks for having a look at the patch and taking some time to
give your feedback ! It's much appreciated

2010/9/8 Dmitry Stogov dmitry@zend.com:

Hi Pierrick,

I've taken just a quick look into concept and patch. It looks interesting
and might be useful in some areas, but I see several significant
problems:

Have you thought about compatibility with opcode caches? In case I
understood properly, you store annotation as a HashTable of object. But
life-time of objects is restricted by request time, so they won't persist
in
opcode cache and will have to be recreated on each request. It's a huge
overhead. I don't have a good solution for this problem except for using
arrays instead of objects.

You're right annotations are stored in an HashTable. But this
HashTable doesn't store zval objects directly but zend_annotations.

Then it's not a problem. my mistake.

This is the reflection getAnnotation and getAnnotations method which
are in charge of reading the zend_annotation structures and
instantiating the proper annotation object when needed. The zval named
instance in the zend_annotation structure is there only to point to
the annotation instance at runtime so that the state of the annotation
is kept between two calls to the getAnnotation and getAnnotations on a
same code element (I added this directly into the zend_annotation
structure to make it faster but I can imagine a HashTable like you
mentioned earlier where keys are addresses). I'm not yet quite
familiar with the APC source code but since (and correct me if i'm
wrong) APC save zend_class_entry, etc.. in memory we could modify it
to also save the new HashTable *annotations of those structures (like
you already do for doc_comment) excluding the zval *instance.

I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of corresponding
classesm, methods and properties.

Annotations are metadata related to a code element. IMHO it make sense
to add them in the appropriate code element structures (even
doc_comment is in those structures) so that APC and other cache will
know that this is something part of the code element and it needs to
be cached and so on.

It's easier to keep it in appropriate places, but it's a waste of memory,
because only a few classes will use it. According to doc comments, in case
we accept annotations, I would represent it as a special kind of annotation.

Separate map(enity -> anotations) would require memory only for defined
annotations. Of course it would be a bit more expensive to read it and would
require special handling in opcode hashes.

Argument is not reasonable IMHO.
You may know that most code around web lack of documentation,
specially docblock, so why not separate the docblocks on a separate
structure too?
Sorry, but your argument is not reasonable.
Each class/property/method should contain all relevant information it
can get, whatever it needs (docblock, annotations, visibility
information, etc). Of course you have a bit of memory overhead, but
it's a pointer, isn't it? So at the end, we will only have overhead
when we have annotations defined.
Also, decomposing the annotation definition and storage adds a level
of dependency and indirection that may get things harder to comprehend
by newer contributors.

I think the annotaton syntax must follow PHP syntax as close as
possible

allow leading \ in QualifiedName

use '=>' in arrays

The actual patch already implement those two points. You can right now
already do

[\My\Own\Annotation(array('foo' => 'bar', 'baz'))]
class FooBar {}

Sorry about that, I just noticed that the EBNF in the RFC was not
updated correctly to reflect those two points. I just made the
modification to replace "=" by "=>" in arrays and allow the optional
leading \ in the QualidifedName

great.

I didn't understand why do we need nested annotations.

Nested annotations could be use for many cases. Doctrine for example
use them a lot to do things like :
[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id", referencedColumnName="id",
unique=true)]
)
)]

I see many use cases of nested annotations. Pierrick gave one, that is
exactly related to the project I contribute for.
Another good example is the implementation of JSR-303 (Bean
Validation) on Symfony 2, that adds automatic validation to POPOs.
Example:

class User {
...

[Validation([Email(checkMX = true)])]
public $email;

}

The first and second problems are the most important.
I don't like to lose performance of existing applications which don't use
annotations at all. I think the concept must be redesigned a bit.

Right now the only performance decrease is at compile time since the
annotations HashTable are filled by the parser.

I assume parser works with near the same speed without annotations. right?

Yes. It is as complex as the addiction of any new feature that
includes new grammar rules, like type hinting checks on method
prototypes.

At runtime you don't
have any performance decrease if you're not using annotations. If you
use them, you'll lose some time when you do getAnnotation() to
instantiate the object, but this instantiation is just done once for
each annotation on a single code element so it make it a little bit
faster if you use them intensively.

I see, but assumptions are not always right, often memory consumption
affects performance directly, it's better to check.

The impact is minimum because it only adds pointers to structs.
The instantiation is done on demand, so only when user asks for
Annotations they are instantiated.

Also I would like to see an APC patch to check if the implementation
works
and doesn't lose performance.

I will try to work on an APC patch to store the Annotations HashTable
of every code element structure.

In case you have plain C structures (without objects) it shouldn't be a big
problem. I'm more interested to store annotation separately. In this case
APC support would be a bit more difficult.

I could help you with implementation in case the idea accepted in general.

Thanks a lot for the offered help. Without help from core developers
it would be very difficult to reach a performant proposed patch.

Thanks. Dmitry.

Thanks. Dmitry.

Thanks again for your time :)

Pierrick

Pierrick Charron wrote:

Hi Dmitry,

As discussed on IRC, here are the RFC and the patch to add Annotation
support in PHP :

RFC : http://wiki.php.net/rfc/annotations

Patch : http://www.adoy.net/php/Annotations.diff

All your feedback and suggestions will be more than welcome.

Thanks again.

Pierrick (or adoy on irc)

--

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by johannes@schlueters.de — view source

unread

Hi,

I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of corresponding
classesm, methods and properties.

Annotations are metadata related to a code element. IMHO it make sense
to add them in the appropriate code element structures (even
doc_comment is in those structures) so that APC and other cache will
know that this is something part of the code element and it needs to
be cached and so on.

It's easier to keep it in appropriate places, but it's a waste of memory,
because only a few classes will use it. According to doc comments, in case
we accept annotations, I would represent it as a special kind of annotation.

Separate map(enity -> anotations) would require memory only for defined
annotations. Of course it would be a bit more expensive to read it and would
require special handling in opcode hashes.

Argument is not reasonable IMHO.
You may know that most code around web lack of documentation,
specially docblock, so why not separate the docblocks on a separate
structure too?
Sorry, but your argument is not reasonable.
Each class/property/method should contain all relevant information it
can get, whatever it needs (docblock, annotations, visibility
information, etc). Of course you have a bit of memory overhead, but
it's a pointer, isn't it? So at the end, we will only have overhead
when we have annotations defined.
Also, decomposing the annotation definition and storage adds a level
of dependency and indirection that may get things harder to comprehend
by newer contributors.

Let's do some math:

A pointer on a 64bit architecture is 8 bytes. A random PHP binary of
mine has 1226 functions. And 133 classes. Each of them has, let's say 10
methods (i guess average is higher, but well).

Then I'm running an application, which has maybe 100 classes with 10
methods each.

This gives 8 * (1226 + 133 + 100 + (133 * 10) + (100 * 10)) bytes =
30.31 kilobytes.

Now I have 100 server children, so this are 3.021 megabytes on the
server.

Oh and that's only for the pointer which could point to annotations
but will most likely point to NULL.

With the approach proposed by Dmitry this memory won't be used but
whenever annotations are accessed a lookup more will be needed.

This calculation is of course completely wrong to many wild guesses and
simplifications in there.

Of course that's not much but your statement shows what will happen
next:

"specially docblock, so why not separate the docblocks"

First of all I claim that there are more docblocks than annotations.

Secondly what about the next pointer, and the next and the next somebody
wants to add, not only in the op array but other global structures, one
pointer in the zval, one in the hash bucket, one ...?

We can still move this over later when annotations are adopted and the
equation memory vs. CPU for this feature is valued differently.

johannes

14 years ago by Guilherme Blanco — view source

unread

Hi Johannes,

Comments inline.

2010/9/8 Johannes Schlüter johannes@schlueters.de:

Hi,

I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of corresponding
classesm, methods and properties.

Annotations are metadata related to a code element. IMHO it make sense
to add them in the appropriate code element structures (even
doc_comment is in those structures) so that APC and other cache will
know that this is something part of the code element and it needs to
be cached and so on.

It's easier to keep it in appropriate places, but it's a waste of memory,
because only a few classes will use it. According to doc comments, in case
we accept annotations, I would represent it as a special kind of annotation.

Separate map(enity -> anotations) would require memory only for defined
annotations. Of course it would be a bit more expensive to read it and would
require special handling in opcode hashes.

Argument is not reasonable IMHO.
You may know that most code around web lack of documentation,
specially docblock, so why not separate the docblocks on a separate
structure too?
Sorry, but your argument is not reasonable.
Each class/property/method should contain all relevant information it
can get, whatever it needs (docblock, annotations, visibility
information, etc). Of course you have a bit of memory overhead, but
it's a pointer, isn't it? So at the end, we will only have overhead
when we have annotations defined.
Also, decomposing the annotation definition and storage adds a level
of dependency and indirection that may get things harder to comprehend
by newer contributors.

Let's do some math:

A pointer on a 64bit architecture is 8 bytes. A random PHP binary of
mine has 1226 functions. And 133 classes. Each of them has, let's say 10
methods (i guess average is higher, but well).

Then I'm running an application, which has maybe 100 classes with 10
methods each.

This gives 8 * (1226 + 133 + 100 + (133 * 10) + (100 * 10)) bytes =
30.31 kilobytes.

Now I have 100 server children, so this are 3.021 megabytes on the
server.

Oh and that's only for the pointer which could point to annotations
but will most likely point to NULL.

With the approach proposed by Dmitry this memory won't be used but
whenever annotations are accessed a lookup more will be needed.

This calculation is of course completely wrong to many wild guesses and
simplifications in there.

Of course that's not much but your statement shows what will happen
next:

"specially docblock, so why not separate the docblocks"

First of all I claim that there are more docblocks than annotations.

Secondly what about the next pointer, and the next and the next somebody
wants to add, not only in the op array but other global structures, one
pointer in the zval, one in the hash bucket, one ...?

You are right. I was thinking strictly to code coupling and containers
by responsability.
I have implemented the support under docblock parsing for Doctrine 2,
and we cache the parsed pieces under the name of ClassMetadata. That's
why I don't feel too much about having it standalone or coupled per
associated piece. I think related to this argument I missed a little
the "eat your own dog food", mainly because I've never done too much
PHP internals.
Anyway, I feel a little uncomfortable when I see localized code using
global resources, it sounds a little like bad architecturing. But I
completely understand the performance reasons. =)

We can still move this over later when annotations are adopted and the
equation memory vs. CPU for this feature is valued differently.

I didn't mean to be rude. I've re-read my email and it really sounded
like harsh... sorry!
I'm just very anxious to see this merged on core... I've bothered
people 2+ years ago to see this alive on 5.3 and now it's back to
discussion and more close to become reality... I just wanna get things
right and "in". =)

johannes

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Stas Malyshev — view source

unread

Hi!

[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id", referencedColumnName="id",
unique=true)]
)
)]
[Validation([Email(checkMX = true)])]

I'm getting a feeling we are developing language inside language here.
We rejected [] syntax for arrays because it makes the intent unclear.
I'd say if that's unclear [Validation([Email(checkMX = true)])] is
super-unclear - what exactly is supposed to happen there? It is very
non-obvious. I think it needs to be radically simplified.
I understand that people that write ORMs etc. want their work to be
easier, but I don't think turning PHP into a mesh of random brackets and
words worth it. If we can't find a model that is easy to comprehend,
ORMs would have to use XML or other outside-of-syntax means.

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

14 years ago by Benjamin Eberlei — view source

unread

Hello Stas,

I agree, using an array like syntax would make the intent much clearer
in the context of PHP, the syntax is just slightly more verbose:

[JoinTable(array(
"name" => "users_phonenumbers",
"joinColumns" => array(
array("name" => "user_id", "referendedColumnName" => "id"),
),
"inverseJoinColumns" => array(
array("name => "phonenumber_id", "referendColumnName" => "id",
"unique" => true),
),
)]

[Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))]

I think that is even possible with the current patch, it just allows
additional [] blocks inside that convert into an object instead of an
array.

Annotations is hardly a feature relevant for ORMs only, its just a very
obvious one to pick. I can find bazzilions of other good examples:

SOAP/XML-RPC - Hint your service/functions for that WSDL generator you
want to use (instead of writing it by hand)
ACLs - Configure an access control layer that wraps around your
service-calls (is Foo allowed to do this?)
Testing - Allow nicer configuration of test-setup, fixtures,
pre-conditions.
Validation - Explain to a validation component what the fields of your
classes are.
Hooks/Event-Systems - Explicit mechanisms to register
classes/methods/functions as plugins, event listener or hooks. No more
writing FrameworkHookListener::add('myMagicCallback')
Frameworks - Leave INI, YAML, XML behind, configuration visible at the
applied context inside PHP is very valuable, instead of having to browse
the source to the configuration directories, see the Routing, Action and
View configuration examples Fabien has posted on Symfony 2 yesterday.
Dependency Injection - Configuring how dependencies should be wired
between objects, so that a DI container can help you bootstrap your
application.
Forms - Tell a form generator how an object property should be
rendered, validated and such.

greetings,
Benjamin

Hi!

[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id",
referencedColumnName="id",
unique=true)]
)
)]
[Validation([Email(checkMX = true)])]

I'm getting a feeling we are developing language inside language
here.
We rejected [] syntax for arrays because it makes the intent unclear.
I'd say if that's unclear [Validation([Email(checkMX = true)])] is
super-unclear - what exactly is supposed to happen there? It is very
non-obvious. I think it needs to be radically simplified.
I understand that people that write ORMs etc. want their work to be
easier, but I don't think turning PHP into a mesh of random brackets
and
words worth it. If we can't find a model that is easy to comprehend,
ORMs would have to use XML or other outside-of-syntax means.

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

On Wed, 2010-09-08 at 11:16 -0700, Stas Malyshev wrote:

Hi!

[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id", referencedColumnName="id",
unique=true)]
)
)]
[Validation([Email(checkMX = true)])]

I'm getting a feeling we are developing language inside language here.
We rejected [] syntax for arrays because it makes the intent unclear.
I'd say if that's unclear [Validation([Email(checkMX = true)])] is
super-unclear - what exactly is supposed to happen there? It is very
non-obvious. I think it needs to be radically simplified.
I understand that people that write ORMs etc. want their work to be
easier, but I don't think turning PHP into a mesh of random brackets and
words worth it. If we can't find a model that is easy to comprehend,
ORMs would have to use XML or other outside-of-syntax means.

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

14 years ago by Dmitry Stogov — view source

unread

Hi Guilherme,

Guilherme Blanco wrote:

Hi Dmitry,

Comments goes inline.

Pierrick Charron wrote:

Hi Dmitry,

First thanks for having a look at the patch and taking some time to
give your feedback ! It's much appreciated

2010/9/8 Dmitry Stogov dmitry@zend.com:

Hi Pierrick,

I've taken just a quick look into concept and patch. It looks interesting
and might be useful in some areas, but I see several significant
problems:

Have you thought about compatibility with opcode caches? In case I
understood properly, you store annotation as a HashTable of object. But
life-time of objects is restricted by request time, so they won't persist
in
opcode cache and will have to be recreated on each request. It's a huge
overhead. I don't have a good solution for this problem except for using
arrays instead of objects.
You're right annotations are stored in an HashTable. But this
HashTable doesn't store zval objects directly but zend_annotations.
Then it's not a problem. my mistake.

This is the reflection getAnnotation and getAnnotations method which
are in charge of reading the zend_annotation structures and
instantiating the proper annotation object when needed. The zval named
instance in the zend_annotation structure is there only to point to
the annotation instance at runtime so that the state of the annotation
is kept between two calls to the getAnnotation and getAnnotations on a
same code element (I added this directly into the zend_annotation
structure to make it faster but I can imagine a HashTable like you
mentioned earlier where keys are addresses). I'm not yet quite
familiar with the APC source code but since (and correct me if i'm
wrong) APC save zend_class_entry, etc.. in memory we could modify it
to also save the new HashTable *annotations of those structures (like
you already do for doc_comment) excluding the zval *instance.

I suppose that usage of annotation would be quite rare case. I don't
think it make sense to extend each op_array, property and class with
additional "annotations" field. I think it's possible to have a separate
CG(annotaions_map) where the keys might be the addresses of corresponding
classesm, methods and properties.
Annotations are metadata related to a code element. IMHO it make sense
to add them in the appropriate code element structures (even
doc_comment is in those structures) so that APC and other cache will
know that this is something part of the code element and it needs to
be cached and so on.
It's easier to keep it in appropriate places, but it's a waste of memory,
because only a few classes will use it. According to doc comments, in case
we accept annotations, I would represent it as a special kind of annotation.

Separate map(enity -> anotations) would require memory only for defined
annotations. Of course it would be a bit more expensive to read it and would
require special handling in opcode hashes.

Argument is not reasonable IMHO.
You may know that most code around web lack of documentation,
specially docblock, so why not separate the docblocks on a separate
structure too?

It would be good to separate it too, as well as different debug
information e.g opline number, filename etc.

Sorry, but your argument is not reasonable.
Each class/property/method should contain all relevant information it
can get, whatever it needs (docblock, annotations, visibility
information, etc). Of course you have a bit of memory overhead, but
it's a pointer, isn't it? So at the end, we will only have overhead
when we have annotations defined.

he pointer takes memory too.

Anyway, I think it's better to make experiment and see how this patch
affects memory consumption. Just load most ZF classes and measure peak
heap usage.

$ USE_ZEND_ALLOC=0 valgrind --tool=massif php zf.php
$ msprintf massif.out.<pid>

Then we may decide if it make sense to separate annotations or not.
(I can do this test and share results when have time).

Also, decomposing the annotation definition and storage adds a level
of dependency and indirection that may get things harder to comprehend
by newer contributors.

Agree.

I think the annotaton syntax must follow PHP syntax as close as
possible

allow leading \ in QualifiedName

use '=>' in arrays
The actual patch already implement those two points. You can right now
already do

[\My\Own\Annotation(array('foo' => 'bar', 'baz'))]
class FooBar {}

Sorry about that, I just noticed that the EBNF in the RFC was not
updated correctly to reflect those two points. I just made the
modification to replace "=" by "=>" in arrays and allow the optional
leading \ in the QualidifedName
great.

I didn't understand why do we need nested annotations.
Nested annotations could be use for many cases. Doctrine for example
use them a lot to do things like :
[JoinTable(
name="users_phonenumbers",
joinColumns=array(
[JoinColumn(name="user_id", referencedColumnName="id")]
),
inverseJoinColumns=array(
[JoinColumn(name="phonenumber_id", referencedColumnName="id",
unique=true)]
)
)]

I see many use cases of nested annotations. Pierrick gave one, that is
exactly related to the project I contribute for.
Another good example is the implementation of JSR-303 (Bean
Validation) on Symfony 2, that adds automatic validation to POPOs.
Example:

class User {
...
[Validation([Email(checkMX = true)])]
public $email;
}

OK. at least I don't see a reason for nested brackets.

[Validation(Email(checkMX=>true))] looks better.

Thanks. Dmitry.

The first and second problems are the most important.
I don't like to lose performance of existing applications which don't use
annotations at all. I think the concept must be redesigned a bit.
Right now the only performance decrease is at compile time since the
annotations HashTable are filled by the parser.
I assume parser works with near the same speed without annotations. right?

Yes. It is as complex as the addiction of any new feature that
includes new grammar rules, like type hinting checks on method
prototypes.

At runtime you don't
have any performance decrease if you're not using annotations. If you
use them, you'll lose some time when you do getAnnotation() to
instantiate the object, but this instantiation is just done once for
each annotation on a single code element so it make it a little bit
faster if you use them intensively.
I see, but assumptions are not always right, often memory consumption
affects performance directly, it's better to check.

The impact is minimum because it only adds pointers to structs.
The instantiation is done on demand, so only when user asks for
Annotations they are instantiated.

Also I would like to see an APC patch to check if the implementation
works
and doesn't lose performance.
I will try to work on an APC patch to store the Annotations HashTable
of every code element structure.
In case you have plain C structures (without objects) it shouldn't be a big
problem. I'm more interested to store annotation separately. In this case
APC support would be a bit more difficult.

I could help you with implementation in case the idea accepted in general.

Thanks a lot for the offered help. Without help from core developers
it would be very difficult to reach a performant proposed patch.

Thanks. Dmitry.

Thanks. Dmitry.
Thanks again for your time :)

Pierrick

Pierrick Charron wrote:

Hi Dmitry,

As discussed on IRC, here are the RFC and the patch to add Annotation
support in PHP :

RFC : http://wiki.php.net/rfc/annotations

Patch : http://www.adoy.net/php/Annotations.diff

All your feedback and suggestions will be more than welcome.

Thanks again.

Pierrick (or adoy on irc)

14 years ago by Pierrick Charron — view source

unread

[Validation(Email(checkMX=>true))] looks better.

Thanks. Dmitry.

Hi Dmitry

The initial syntax proposed in the RFC/Patch is inspired by C#. If you
modify this syntax to remove brackets in nested annotations you will
have some conflicts like this one :

[Validation(Email)]

In this case the parser can't determine if Email is a constant or a
nested annotation. I did a second patch with an other syntax (proposed
by Etienne in the initial thread) which look like this :

%Validation(%Email)

I personally prefer the first one because I like the fact that you
have a start and an end delimiter for each annotations but I can live
with an other one if the majority is more comfortable with it.

Regards,
Pierrick

14 years ago by Stas Malyshev — view source

unread

Hi!

[Validation(Email(checkMX=>true))] looks better.

Even here it's not clear what is happening. What is "Validation", what
is "Email", what is "checkMX" (are they all classes? or only some of
them?), what is happening to them (are these classes being instantiated?
when? what is passed as parameters? What is the scope of that? etc). Why
can we have now two ways to instantiate classes, complete with mix of
[]s and ()s, but having array syntax using [] is still too complex?

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

14 years ago by Pierrick Charron — view source

unread

Hi Stas,

Annotations is a new concept in PHP (even if some framework already
use an user space implementation of them) and I think it is normal
that people will have to read a little bit about this eventually new
feature before using it. This is the same thing for traits, if you
don't know what is a trait you will not know how to use them. But once
you know the concept it's really easy to understand what is an
annotation class, parameter etc...

Is it really the [] Syntax that you don't like for annotations ? I was
personally not against the [] array syntax and I understand that this
annotation syntax will make the future implementation of this [] array
syntax impossible. So I could change it to the syntax proposed by
Etienne in the first thread :

%Annotation(%Email(checkMX = true));

I'm not against any other proposal of syntax so if you have one to
proposition do not hesitate.

Regards,
Pierrick

2010/9/10 Stas Malyshev smalyshev@sugarcrm.com:

Hi!

[Validation(Email(checkMX=>true))] looks better.

Even here it's not clear what is happening. What is "Validation", what is
"Email", what is "checkMX" (are they all classes? or only some of them?),
what is happening to them (are these classes being instantiated? when? what
is passed as parameters? What is the scope of that? etc). Why can we have
now two ways to instantiate classes, complete with mix of []s and ()s, but
having array syntax using [] is still too complex?

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

14 years ago by Christian Kaps — view source

unread

Hi,

%Annotation(%Email(checkMX = true));

at first I thought what for an ugly syntax. But after a time I think it
is regardless of whether the % or @(from Java, which I prefer over all,
if it were possible) syntax is used. It looks very similar. So I prefer
the % syntax so we can use the [] for defining arrays in annotations. Is
it possible to define objects from type stdClass in the form
%Annotation({key: 'value'})?

An other question. Is it necessary to terminate an annotation with a
semicolon, like in your example?

class Compiler {

/**
 * Compile a node into plain PHP.
 *
 * @param Node $node The node to compile.
 */
%Annotation(%Email(checkMX = true))
%ResourceParameter(['key' => 'name', 'value' => 'annotation'])
%Inject('\my\name\space\Class')
%Test
%Annotation({key: 'value'})
public function compile(Node $node) {

}

}

Greetings,
Christian

Am 11.09.2010 02:23, schrieb Pierrick Charron:

Hi Stas,

Annotations is a new concept in PHP (even if some framework already
use an user space implementation of them) and I think it is normal
that people will have to read a little bit about this eventually new
feature before using it. This is the same thing for traits, if you
don't know what is a trait you will not know how to use them. But once
you know the concept it's really easy to understand what is an
annotation class, parameter etc...

Is it really the [] Syntax that you don't like for annotations ? I was
personally not against the [] array syntax and I understand that this
annotation syntax will make the future implementation of this [] array
syntax impossible. So I could change it to the syntax proposed by
Etienne in the first thread :

%Annotation(%Email(checkMX = true));

I'm not against any other proposal of syntax so if you have one to
proposition do not hesitate.

Regards,
Pierrick

2010/9/10 Stas Malyshev smalyshev@sugarcrm.com:

Hi!

[Validation(Email(checkMX=>true))] looks better.
Even here it's not clear what is happening. What is "Validation", what is
"Email", what is "checkMX" (are they all classes? or only some of them?),
what is happening to them (are these classes being instantiated? when? what
is passed as parameters? What is the scope of that? etc). Why can we have
now two ways to instantiate classes, complete with mix of []s and ()s, but
having array syntax using [] is still too complex?

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

14 years ago by Guilherme Blanco — view source

unread

Hi Stas and Christian,

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.

!Author("Guilherme Blanco")
!Validation(!Email(checkMX = true))

@Stas: Explaining the example of class User {
[Validation([Email(checkMX = true)])] public $email; }

class Validation extends \ReflectionAnnotation {}
class Email extends \ReflectionAnnotation {
protected $checkMX;

public function getCheckMX() { return $this->checkMX; }

}

$reflClass = new \ReflectionClass('User');
$reflProp = $reflClass->getProperty('email');

$emailAnnot = $reflProp->getAnnotation('Validation')->getValue();
echo $emailAnnot->getCheckMX(); // true

I hope this helps to explain a little bit.

Cheers,

On Sat, Sep 11, 2010 at 8:00 AM, Christian Kaps
christian.kaps@mohiva.com wrote:

Hi,

%Annotation(%Email(checkMX = true));

at first I thought what for an ugly syntax. But after a time I think it
is regardless of whether the % or @(from Java, which I prefer over all,
if it were possible) syntax is used. It looks very similar. So I prefer
the % syntax so we can use the [] for defining arrays in annotations. Is
it possible to define objects from type stdClass in the form
%Annotation({key: 'value'})?

An other question. Is it necessary to terminate an annotation with a
semicolon, like in your example?

class Compiler {

/**
* Compile a node into plain PHP.
*
* @param Node $node The node to compile.
*/
%Annotation(%Email(checkMX = true))
%ResourceParameter(['key' => 'name', 'value' => 'annotation'])
%Inject('\my\name\space\Class')
%Test
%Annotation({key: 'value'})
public function compile(Node $node) {

}
}

Greetings,
Christian

Am 11.09.2010 02:23, schrieb Pierrick Charron:

Hi Stas,

Annotations is a new concept in PHP (even if some framework already
use an user space implementation of them) and I think it is normal
that people will have to read a little bit about this eventually new
feature before using it. This is the same thing for traits, if you
don't know what is a trait you will not know how to use them. But once
you know the concept it's really easy to understand what is an
annotation class, parameter etc...

Is it really the [] Syntax that you don't like for annotations ? I was
personally not against the [] array syntax and I understand that this
annotation syntax will make the future implementation of this [] array
syntax impossible. So I could change it to the syntax proposed by
Etienne in the first thread :

%Annotation(%Email(checkMX = true));

I'm not against any other proposal of syntax so if you have one to
proposition do not hesitate.

Regards,
Pierrick

2010/9/10 Stas Malyshev smalyshev@sugarcrm.com:

Hi!

[Validation(Email(checkMX=>true))] looks better.
Even here it's not clear what is happening. What is "Validation", what is
"Email", what is "checkMX" (are they all classes? or only some of them?),
what is happening to them (are these classes being instantiated? when? what
is passed as parameters? What is the scope of that? etc). Why can we have
now two ways to instantiate classes, complete with mix of []s and ()s, but
having array syntax using [] is still too complex?

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

--

--

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Stas Malyshev — view source

unread

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. We have rejected much cleaner
syntax proposals because it was not clean enough, though only thing it
did was to drop one keyword, and this one rolls a bunch of pretty
unobvious code into a couple of symbols. I think we should choose either
never do it or allow it, but not be random about it.

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

14 years ago by Pierre Joye — view source

unread

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.

Cheers,

Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

14 years ago by Benjamin Eberlei — view source

unread

Hey everyone,

I want to re-drop my proposal onto the table that is just a shortcut
notation for php class instantiation inside that brackets (omiting the
new keyword):

annotation := [className(classArgs*)]
classArgs := array | string | int | float | ...

Re-pasting my examples (this time from simple to complex):

[ExpectedException("InvalidArgumentException")]
[ExpectedException("InvalidArgumentException", "Expected message", 40")]

[Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))]

The only thing new here would be the brackets [] and the implicit class
instantiation through omitting the new keyword.

i.e. [Foo("bar")] would essentially mean new Foo("bar") when
$refl->getAnnotation() is called.

greetings,
Benjamin

On Sat, 2010-09-11 at 20:24 +0200, Pierre Joye 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.

Cheers,

Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

14 years ago by Stas Malyshev — view source

unread

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.

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

14 years ago by Christian Kaps — view source

unread

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.

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.

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.
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.

14 years ago by Stas Malyshev — view source

unread

Hi!

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.

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

14 years ago by Nick Pope — view source

unread

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:

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

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

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) { ... }
}

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.

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.

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.

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.

14 years ago by Sebastian Bergmann — view source

unread

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.

Annotations are part of the code and code is not only automatically
parsed but also read by humans.

--
Sebastian Bergmann Co-Founder and Principal Consultant
http://sebastian-bergmann.de/ http://thePHP.cc/

14 years ago by Pierre Joye — view source

unread

Hello Sebastian.

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.

Annotations are part of the code and code is not only automatically
parsed but also read by humans.

Obviously as they write it. However the primary goal of annotations is
not to be read by human, that's why docs' exist (APIs, inline, etc.).
To make the syntax a pain to parse and make it way too different from
existing annotations syntaxes would not be good.

Cheers,

Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

14 years ago by Zeev Suraski — view source

unread

At 20:24 11/09/2010, Pierre Joye 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

14 years ago by Sebastian Bergmann — view source

unread

I for one don't see the huge gain annotations bring on top of PHPDoc.

Same here, I am satisfied with the way that annotations work, for
instance, in PHPUnit.

--
Sebastian Bergmann Co-Founder and Principal Consultant
http://sebastian-bergmann.de/ http://thePHP.cc/

14 years ago by Pierre Joye — view source

unread

hi,

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.

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

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

--
Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

14 years ago by Zeev Suraski — view source

unread

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

14 years ago by Benjamin Eberlei — view source

unread

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.

This only applies to the weird suggestions of % or ! for the operator and
new syntax constructs for arrays and such. Are there any objections to
implementing them to actually look like PHP code?

The only new syntantic sugar would be the [] and the implicit "new"
keyword in the "annotClassName".

annotation := [annotClassName(classArgs*)]
classArgs := array | string | int | float | ...

[ExpectedException("InvalidArgumentException")]
[ExpectedException("InvalidArgumentException", "Expected message", 40")]
[Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))]

new ExpectedException("InvlaidArgumentException")
new Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))

given this syntax (which the current patch nearly implements) i don't get
the "whole new syntax" argument, this looks very much like PHP.

greetings,
Benjamin

14 years ago by Zeev Suraski — view source

unread

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

This only applies to the weird suggestions of % or ! for the operator and
new syntax constructs for arrays and such. Are there any objections to
implementing them to actually look like PHP code?

Yep. It's a whole new branch of syntax even w/o the weird operators,
and introduces a whole new set of concepts.

Zeev

14 years ago by Stas Malyshev — view source

unread

Hi!

[ExpectedException("InvalidArgumentException")]
[ExpectedException("InvalidArgumentException", "Expected message", 40")]
[Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))]

This doesn't look like PHP code. In PHP code, nether [] by itself, nor
[ClassName('string')] mean anything. It's new sytnax.

new ExpectedException("InvlaidArgumentException")
new Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))

This one is not very clear either - when is this "new" executed? What it
is being assigned to? What you can and can't use there? It's all new
concepts - which I'm not sure worth introducing.

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

14 years ago by Gustavo Lopes — view source

unread

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.

Rare use case? Have you seen any recent Java framework? Or Java EE 6? Or
design by contract in C#? A declarative programming style can be very
handy.

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.

The fact that PHP is not C# or Java doesn't mean we shouldn't look for
useful features in those languages, so it's not an argument. What you have
to say is why you think annotations, while possibly making sense in C# or
Java (depending on your position on that), do not make sense in PHP.

I also think you are overestimating the complexity introduced by this
feature. The patch is not particularly complex. We have doubtfully useful
features such as LSB which are more complex not only in implementation,
but also in usage.

I though adding support for this was more or less consensual, and it was
just a matter of tuning important but secondary details.

--
Gustavo Lopes

14 years ago by Zeev Suraski — view source

unread

At 17:51 13/09/2010, Gustavo Lopes wrote:

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.

Rare use case? Have you seen any recent Java framework? Or Java EE 6? Or
design by contract in C#? A declarative programming style can be very
handy.

Framework code (as in code that actually goes into a framework, not
code that uses a framework) represents a tiny percentage of the PHP
codebase at large. Most of it is application code.

I think great frameworks can be created in PHP w/o annotations (there
are numerous live examples attesting to that) - and the bang/buck of
introducing this whole new concept and the associated complexity to
everyone is not high.

Zeev

14 years ago by Gustavo Lopes — view source

unread

At 17:51 13/09/2010, Gustavo Lopes wrote:

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.

Rare use case? Have you seen any recent Java framework? Or Java EE 6? Or
design by contract in C#? A declarative programming style can be very
handy.

Framework code (as in code that actually goes into a framework, not code
that uses a framework) represents a tiny percentage of the PHP codebase
at large. Most of it is application code.

You misunderstood me. When I say the frameworks use annotation I don't
mean they use annotations in their own implementation (that's not
particularly relevant for the reason you present).

What I mean is that the frameworks recognize annotations the application
code has so that the framework user can do stuff like injecting objects,
run methods in transactions or check post-conditions in a declarative
fashion, by adding annotations.

By the way, you ignored the rest of the e-mail.

How do you evaluate the complexity/return of features such as annotations
with that of e.g. LSB? Why are they not adequate for PHP, but may be for
other languages?

--
Gustavo Lopes

14 years ago by Pierre Joye — view source

unread

I think great frameworks can be created in PHP w/o annotations (there are
numerous live examples attesting to that) - and the bang/buck of introducing
this whole new concept and the associated complexity to everyone is not
high.

To quote a similar discussion, more than a decade ago:

'Great applications can be created in PHP w/o OO'

That's true, but who will argue about the OO addition today? Time to
slightly change our vision(s) in my opinion.

I'm not saying that having annotation is a dead critical feature, but
it is definitively something that helps framework a lot, especially
when it comes to interop, to port other solutions to PHP.

Cheers,

Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

14 years ago by Zeev Suraski — view source

unread

At 17:51 13/09/2010, Gustavo Lopes wrote:

The fact that PHP is not C# or Java doesn't mean we shouldn't look for
useful features in those languages,

Right.

so it's not an argument.

I think it is very much an argument - the fact a feature is useful in
another language doesn't mean it also belongs in PHP (even if it's
useful, see below).

What you have
to say is why you think annotations, while possibly making sense in C# or
Java (depending on your position on that), do not make sense in PHP.

I'm not and haven't said at any point that annotations aren't
useful. They're certainly useful for certain purposes. They also
bring about complexity to the language in the form of new language
concepts that new users have to learn, new syntax, new classes of
bugs, etc.. When I (as well as many others) say that PHP is not
Java, it means that our considerations for introducing a feature to
the language are different, and what's useful in Java - to the point
that it's worth the added complexity - may not be worth it for
PHP. Annotations fall in that category, IMHO.

I think it's safe to assume that (almost) every feature ever added to
any programming language was useful to some degree. That in itself
should make it clear that usefulness is certainly not the only
criterion for introducing a new feature into a language. Consistency
with the language's theme, complexity and compatibility - to name a
few - all play major roles too.

I also think you are overestimating the complexity introduced by this
feature. The patch is not particularly complex. We have doubtfully useful
features such as LSB which are more complex not only in implementation,
but also in usage.

I wasn't talking about the patch, I was talking about the need of end
users to understand yet another new concept and syntax. PHP used to
be a language one could pick up over a weekend. I'm happy it didn't
stagnate and stay where it was 10 years ago, but considering PHP is
already a mature language, I think we should be much more picky in
the features we introduce to the language core.

Zeev

14 years ago by Gustavo Lopes — view source

unread

I wasn't talking about the patch, I was talking about the need of end
users to understand yet another new concept and syntax. PHP used to be
a language one could pick up over a weekend. I'm happy it didn't
stagnate and stay where it was 10 years ago, but considering PHP is
already a mature language, I think we should be much more picky in the
features we introduce to the language core.

OK, so let's compare it other concepts:

LSB. Can you explain from the top of your head when when the called
scope is reset or not (e.g. with parent::, self::, className::, possibly
in non-static contexts) in a function call? I can't.
Namespaces. It takes a while to memorize the resolution rules.
References. Need I say more? You almost need to know the implementation
to understand them. Being called "references" doesn't help either.

The proposed annotations are basically object instances that are returned
when you call getAnnotations. There are no itemized lists of rules. I
don't see how this is complex.

--
Gustavo Lopes

14 years ago by Stas Malyshev — view source

unread

Hi!

LSB. Can you explain from the top of your head when when the called
scope is reset or not (e.g. with parent::, self::, className::, possibly
in non-static contexts) in a function call? I can't.

It's not that hard. Keywords forward, classnames don't.

Namespaces. It takes a while to memorize the resolution rules.

For classes, there's essentially one rule - not fully qualified names
use import or current NS. For functions there's a fallback to global
scope above resolution brings nothing. That's it - how hard is that?

References. Need I say more? You almost need to know the implementation
to understand them. Being called "references" doesn't help either.

You very rarely need to use references, and actually most of its use
follow from the mistake (as we see now) of making array a primitive type
like the others. It should have worked like objects work. However it is
true that references are an ugly part of PHP. How it's the reason to add
more ugliness?

The proposed annotations are basically object instances that are returned
when you call getAnnotations. There are no itemized lists of rules. I
don't see how this is complex.

They aren't just object instances, since they also have separate syntax
to create them - unlike the syntax to create all other objects. And it
wouldn't be a problem if it would be something trivial - like just class
name - but we have here whole new syntax complete with nesting, named
parameters, validation logic and what not.

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

14 years ago by Gustavo Lopes — view source

unread

On Mon, 13 Sep 2010 19:20:31 +0100, Stas Malyshev smalyshev@sugarcrm.com
wrote:

The proposed annotations are basically object instances that are
returned when you call getAnnotations. There are no itemized lists of
rules. I
don't see how this is complex.

They aren't just object instances, since they also have separate syntax
to create them - unlike the syntax to create all other objects. And it
wouldn't be a problem if it would be something trivial - like just class
name - but we have here whole new syntax complete with nesting, named
parameters, validation logic and what not.

I share some of these concerns. But a new feature like this would always
require new syntax.

The best (in the sense of "most similar to what we have today") syntax I
can think of is to define annotations exactly the same way was you'd
define arrays, but replace "array" with the annotation name (plus a
prefix). I think this looks like PHP:

%JoinTable(
"name" => "users_phonenumbers",
"joinColumns" => array(
%JoinColumn("name" => "user_id", "referencedColumnName" => "id")
),
"inverseJoinColumns" => array(
%JoinColumn("name" => "phonenumber_id", "referencedColumnName" =>
"id", unique => true)
)
)

The named parameters could be replaced by directly setting the fields
(basically like the ReflectionAnnotation::__construct already does) and
marking the constructor final. If validation logic is really necessary, we
could add a validate() method to ReflectionAnnotation (with an empty
default implementation) that subclasses could override to provide their
validation logic.

Off-topic stuff follows:

LSB. Can you explain from the top of your head when when the called
scope is reset or not (e.g. with parent::, self::, className::, possibly
in non-static contexts) in a function call? I can't.

It's not that hard. Keywords forward, classnames don't.

Fair enough, though I find surprising that "parent" forwards. But you'll
find that most users don't see LSB as a "scope that is forwarded" but
instead as some kind of inheritance mechanism. It also exposed the odd
behavior of keeping subclass copies of static properties in the same
reference set as the parent by default, which causes confusion.

--
Gustavo Lopes

14 years ago by Stas Malyshev — view source

unread

Hi!

The best (in the sense of "most similar to what we have today") syntax I
can think of is to define annotations exactly the same way was you'd
define arrays, but replace "array" with the annotation name (plus a
prefix). I think this looks like PHP:

We have here at least two non-PHP constructs - %Name meaning "new Name"
and array syntax for parameters.

could add a validate() method to ReflectionAnnotation (with an empty
default implementation) that subclasses could override to provide their
validation logic.

When this validation logic will be called? On getAnnotation()? Then it
would be extremely wasteful - the annotation never changes but each time
is re-validated anew.

Fair enough, though I find surprising that "parent" forwards. But you'll
find that most users don't see LSB as a "scope that is forwarded" but
instead as some kind of inheritance mechanism. It also exposed the odd

I don't know how you found out what "most users" of PHP's multi-million
user base think - how many millions of people did you ask? - but whoever
has wrong preconceptions about how it works should correct them by
reading the actual docs. Provided that the actual rule can easily fit on
a bumper sticker, I don't think it's too complex.

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

14 years ago by Gustavo Lopes — view source

unread

On Mon, 13 Sep 2010 21:02:34 +0100, Stas Malyshev smalyshev@sugarcrm.com
wrote:

Hi!

The best (in the sense of "most similar to what we have today") syntax I
can think of is to define annotations exactly the same way was you'd
define arrays, but replace "array" with the annotation name (plus a
prefix). I think this looks like PHP:

We have here at least two non-PHP constructs - %Name meaning "new Name"
and array syntax for parameters.

It's not an array syntax for parameters. Those would not be passed to a
function, merely used to fill the fields of the annotation, like (object)
array("a"=>1) creates a stdClass object with a field named "a" and value

The difference would be we wouldn't be creating dynamic fields, but
only filling defined ones.

could add a validate() method to ReflectionAnnotation (with an empty
default implementation) that subclasses could override to provide their
validation logic.

When this validation logic will be called? On getAnnotation()? Then it
would be extremely wasteful - the annotation never changes but each time
is re-validated anew.

If I'm not mistaken, the current implementation instantiates an object
each time getAnnotation() is called, but it was proposed to change this
into a lazy-loading mechanism with the same instance returned every time
for each annotation. In that case, we'd only need to validate that one
time.

Fair enough, though I find surprising that "parent" forwards. But you'll
find that most users don't see LSB as a "scope that is forwarded" but
instead as some kind of inheritance mechanism. It also exposed the odd

I don't know how you found out what "most users" of PHP's multi-million
user base think - how many millions of people did you ask? - but whoever
has wrong preconceptions about how it works should correct them by
reading the actual docs. Provided that the actual rule can easily fit on
a bumper sticker, I don't think it's too complex.

http://en.wikipedia.org/wiki/Sampling_(statistics)

In any case, the manual page could be improved. It has a vague statement
"static:: does not work like $this for static methods! $this-> follows the
rules of inheritance while static:: doesn't. This difference is detailed
later on this manual page" followed only by examples.

--
Gustavo Lopes

14 years ago by Stas Malyshev — view source

unread

Hi!

If I'm not mistaken, the current implementation instantiates an object
each time getAnnotation() is called, but it was proposed to change this
into a lazy-loading mechanism with the same instance returned every time
for each annotation. In that case, we'd only need to validate that one
time.

Object instances can't be bytecode-cached, so when are they
instantiated? Does it mean it's stateful and mutable?

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

14 years ago by Gustavo Lopes — view source

unread

On Mon, 13 Sep 2010 21:51:32 +0100, Stas Malyshev smalyshev@sugarcrm.com
wrote:

If I'm not mistaken, the current implementation instantiates an object
each time getAnnotation() is called, but it was proposed to change this
into a lazy-loading mechanism with the same instance returned every time
for each annotation. In that case, we'd only need to validate that one
time.

(What I describe as "proposed" is actually the implemented behavior)

Object instances can't be bytecode-cached, so when are they
instantiated? Does it mean it's stateful and mutable?

You're confusing multiple calls to the script to multiple calls to
getAnnotation().
You're right in that one cannot keep objects between requests. The
annotation will have to be regenerated, and possibly validated, on each
script call. It's indeed unfortunate, but we could add the possibility of
turning off these verifications in production or add a hook that
extensions could use so they could cache the result of the validation.
It's not a show-stopper.

However, this does not equal instantiations for each call to
getAnnotation(). This only creates one object:

class A extends ReflectionAnnotation {}

[A]
class H { }

$refH = new ReflectionClass("H");
$refH->getAnnotations();
$refH->getAnnotations();

--
Gustavo Lopes

14 years ago by Zeev Suraski — view source

unread

At 19:25 13/09/2010, Gustavo Lopes wrote:

I wasn't talking about the patch, I was talking about the need of end
users to understand yet another new concept and syntax. PHP used to be
a language one could pick up over a weekend. I'm happy it didn't
stagnate and stay where it was 10 years ago, but considering PHP is
already a mature language, I think we should be much more picky in the
features we introduce to the language core.

OK, so let's compare it other concepts:

LSB. Can you explain from the top of your head when when the called
scope is reset or not (e.g. with parent::, self::, className::, possibly
in non-static contexts) in a function call? I can't.

Namespaces. It takes a while to memorize the resolution rules.

References. Need I say more? You almost need to know the implementation
to understand them. Being called "references" doesn't help either.

The proposed annotations are basically object instances that are returned
when you call getAnnotations. There are no itemized lists of rules. I
don't see how this is complex.

The fact we have complex components in PHP is no excuse to add more
complexity to the language. It's not a binary state, with PHP
"already being complex", so we can add as much complexity as we
want. Complexity accumulates.

Zeev

14 years ago by Benjamin Eberlei — view source

unread

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:

Developers should expect to be able to delete a comment/docblock
without altering the code-path.
Errors in the Doc-Blocks "expected formatting" are left for the
userland developer to detect. IDEs or the PHP Parser simply don't care.
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.
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

14 years ago by Zeev Suraski — view source

unread

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:

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

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

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.

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

14 years ago by Guilherme Blanco — view source

unread

Hi 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.

Do not consider it as a rude comment, it's a rather reflective one.
What about goto; was it needed? You added worse support into PHP for much less.
I constantly see every attempt to make PHP a better language is turned
into endless discussions. Am I wrong? I can highlight more than 10
since I started to follow internals ML.

As of goto, I see only one usage to it: parsers.

Annotations have much more usage than you imagine.
You can control class access, validate the classes through a Service
(or an ortoghonal Aspect using an extension that already exists), unit
test, turn into a persistent class, document for a tool (like phpDoc).
Frameworks can use it to determine controller (instead of keeping
users to extend an abstract class or interface), etc.

I tend to agree the syntax may not be ideal, but that's why we opened
the patch for review and polish.
Years ago I poked a lot of people to join forces and let this support
IN for PHP 5.3, without success. Of course I completely understand
that people have other obligations and that's why I sadly saw PHP 5.3
out of the box without a lot fo support I expected. What I highlight
on RFCs are support that not only me, but tons of developers have
troubles daily and do not know the ways to reach PHP core to suggest
changes.

I eat PHP's dog food daily and I clearly know every single deficiency it has.

Cheers,

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:

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

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

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.

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

--

--

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Benjamin Eberlei — view source

unread

Strictly speaking yes, you can implement everything you want with PHP
Docblocks. But that argument is comparable to telling a nearly blind man
that his glasses are good enough although a more suited treatment
exists. Just because there exists an approach that stumbles half the way
in a bad way, shouldn't prevent a more suitable concept from being
implemented. Stricly speaking I can even apply it to Traits (developers
can copy paste themselves) or Closures (create_function()) or any other
feature that was implemented after arrays and callbacks already existed
(half-baked objects). I think this feature would make PHP a better more
powerful language.

Developers are clearly not using doc blocks for their static
configuration needs currently, even though the possibility exists. It
just feels wrong.

The comparison of benefits and costs surely leads to a different pro or
con opinion on this (and any other) issue. But as I see it, PHP opted
for object-oriented features (and even extended them alot with new php 5
object model, reflection, late-static-binding, traits).
Annotations/metadata configuration are just another feature that exists
in other object-oriented languages and makes them more awesome.

Sorry that i am not familiar to this, but what was the reason to allow
access to PHP Docblock comments though Reflection at runtime anyways? It
seems this was a compromise attempt to allow annotations-like features.
It couldn't have been neen PHPDocumentor alone, since you could (and
should) implement that with the tokenizer extension. If we agree that
using docblocks for runtime configuration is bad (because comments are
not code).

Why don't you think it is useful to allow a strict mechanism to describe
metadata to other parts of your code or libraries? Object-wireing is
done daily by PHP programmers, however they have to use inferior
approaches that frameworks and libraries currently have to provide.

Imho anotations have the same potential as traits for OO-decoupling.
Just that traits are for executable code being shared and annotations
help to describe relationships between objects.

On Mon, 2010-09-13 at 17:44 +0200, Zeev Suraski wrote:

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:

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

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

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.

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

14 years ago by Lars Schultz — view source

unread

Am 13.09.2010 20:35, schrieb Benjamin Eberlei:

Developers are clearly not using doc blocks for their static
configuration needs currently, even though the possibility exists. It
just feels wrong.

incidentally, I do;)

14 years ago by Christian Kaps — view source

unread

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:

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

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

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.

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

14 years ago by Rasmus Lerdorf — view source

unread

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

14 years ago by Benjamin Eberlei — view source

unread

Hello Rasmus,

Isn't any configuration by xml or ini files runtime configuration? Any
configuration that is not resulting in code being generated or code
being op-code cached will be-executed on every single request. That
applies to almost any configuration mechanism used in PHP applications.

Sure there are use-cases with PHP that can't afford any runtime
configuration for performance reasons, but that is not the kind of php
code were annotations are very helpful anyways, since they only have
little integration into libraries or frameworks that require
configuration.

Talking performance: Annotations as implemented by the patch would be
better than file-based configuration mechanisms, because they are
evaluted at parse time, only once - making their internal datastructure
cachable by APC. No stat calls for external files required.

The code being executed to actually bring the information inside the
annotations surely creates overhead, but so does every other "runtime"
generation of datastructures that could potentially be static through
written code.

greetings,
Benjamin

On Mon, 2010-09-13 at 10:01 -0700, Rasmus Lerdorf wrote:

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

14 years ago by Stas Malyshev — view source

unread

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?

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.

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.

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?

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

14 years ago by Derick Rethans — view source

unread

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 is even a tokenizing extension for it in PECL:
http://pecl.php.net/docblock

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.

cheers,
Derick

--
http://derickrethans.nl | http://xdebug.org
Like Xdebug? Consider a donation: http://xdebug.org/donate.php
twitter: @derickr and @xdebug

14 years ago by Gustavo Lopes — view source

unread

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

14 years ago by Guilherme Blanco — view source

unread

Hi Derick,

Again, we should not consider docblock mainly because I think
adding/removing comments of your code should NEVER modify the overall
functionality of your application.
That said, docblock is no option. Now PLEASE let's stop arguing for
nothing and vote?
I'd recommend that since syntax is not ideal, we should not vote for
the complete patch but vote for the functionality.

So the question to be answered is: Should PHP support Annotations?

I'm +1.

Cheers,

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

--

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Christian Kaps — view source

unread

So the question to be answered is: Should PHP support Annotations?

I'm +1.

Greetings,
Christian

14 years ago by Chad Fulton — view source

unread

For me, the syntax, or at least the complexity, is important. I like
the idea of metadata, but what I found attractive about the docBlock
parsing was that it only allowed key/value pairs of meta-data.

-1 for annotations in which the engine instantiates arbitrary
annotation objects.

On Thu, Sep 16, 2010 at 7:58 AM, Christian Kaps
christian.kaps@mohiva.com wrote:

So the question to be answered is: Should PHP support Annotations?

I'm +1.

+1

Greetings,
Christian

14 years ago by Zeev Suraski — view source

unread

At 16:34 16/09/2010, Guilherme Blanco wrote:

So the question to be answered is: Should PHP support Annotations?

-1 for introducing a new Annotations concept and associated syntax

+1 for adding APIs to parse doc blocks

14 years ago by Wim Godden — view source

unread

I'm going to say exactly the same thing :

-1 for introducing a new Annotations concept and associated syntax
+1 for adding APIs to parse doc blocks

Zeev Suraski wrote:

At 16:34 16/09/2010, Guilherme Blanco wrote:

So the question to be answered is: Should PHP support Annotations?

-1 for introducing a new Annotations concept and associated syntax

+1 for adding APIs to parse doc blocks

14 years ago by Lars Schultz — view source

unread

+1 for adding APIs to parse doc blocks
-1 for introducing a new Annotations concept and associated syntax

Am 16.09.2010 18:36, schrieb Wim Godden:

I'm going to say exactly the same thing :

-1 for introducing a new Annotations concept and associated syntax
+1 for adding APIs to parse doc blocks

Zeev Suraski wrote:

At 16:34 16/09/2010, Guilherme Blanco wrote:

So the question to be answered is: Should PHP support Annotations?

-1 for introducing a new Annotations concept and associated syntax

+1 for adding APIs to parse doc blocks

14 years ago by Jonathan Bond-Caron — view source

unread

-1 for the proposed Annotations concept and associated syntax

+1 for adding APIs to parse doc blocks, minor note: should not be not called
"getAnnotations"

+1 for adding APIs to parse doc blocks
-1 for introducing a new Annotations concept and associated syntax

14 years ago by Bill Salak — view source

unread

-----Original Message-----
From: Zeev Suraski [mailto:zeev@zend.com]
Sent: Thursday, September 16, 2010 9:01 AM
To: Guilherme Blanco
Cc: Gustavo Lopes; Derick Rethans; internals@lists.php.net
Subject: Re: [PHP-DEV] Re: PHP Annotations RFC + Patch

+1 for adding APIs to parse doc blocks

From userland:
+1 for adding APIs to parse doc blocks

On its own I think this has merit and even if it is ultimately rejected in
the context of this Annotations discussion I'd like to see this feature
become available.

14 years ago by Ole Markus With — view source

unread

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

At 16:34 16/09/2010, Guilherme Blanco wrote:

So the question to be answered is: Should PHP support Annotations?

-1 for introducing a new Annotations concept and associated syntax

+1 for adding APIs to parse doc blocks

-1 for introducing a new Annotations concept and associated syntax

+1 for adding APIs to parse doc blocks
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJMklSTAAoJEGurSuXEqSv1PGEIAJfeCrTTXChrsnXduyGke8zV
UL9+Ixjwn/LVNgODDnTpTB7ixLO2ED6on9CptfcBIbpQmDhzpSB1/7EyAQKkF/zT
kQQEKGU/I2zE8Uhi9TZZYsKKL7pyq+4mMMyGDUYuUTS8vvGEpQxTkEMMjx3fc/Sl
9XAlGKh3xPJS1hu9EPWdWAXd7k3IFpSONyA1bzrdm1v7z2sKJOf6+rQBHdumGKUp
2MbakHuV7etKOB+a1OOl+kqatZetey3r91nSHj8EPUke9+ocA78JsnJRqJYM9UGc
loErABG3i6c1qodBrXAgVVAeq4pJRopEPlm2oBwuVofd/yzV1f/phaSjxBxbQUA=
=ZpN3
-----END PGP SIGNATURE

14 years ago by Gustavo Lopes — view source

unread

On Thu, 16 Sep 2010 15:34:05 +0100, Guilherme Blanco
guilhermeblanco@gmail.com wrote:

Hi Derick,

Again, we should not consider docblock mainly because I think
adding/removing comments of your code should NEVER modify the overall
functionality of your application.
That said, docblock is no option. Now PLEASE let's stop arguing for
nothing and vote?
I'd recommend that since syntax is not ideal, we should not vote for
the complete patch but vote for the functionality.

So the question to be answered is: Should PHP support Annotations?

I'm +1.

+1 for annotations.

The syntax is a different matter, but this should be settled first.

--
Gustavo Lopes

14 years ago by Pierrick Charron — view source

unread

+1 for Annotations

2010/9/16 Guilherme Blanco guilhermeblanco@gmail.com

Hi Derick,

Again, we should not consider docblock mainly because I think
adding/removing comments of your code should NEVER modify the overall
functionality of your application.
That said, docblock is no option. Now PLEASE let's stop arguing for
nothing and vote?
I'd recommend that since syntax is not ideal, we should not vote for
the complete patch but vote for the functionality.

So the question to be answered is: Should PHP support Annotations?

I'm +1.

Cheers,

On Thu, Sep 16, 2010 at 11:16 AM, Gustavo Lopes glopes@nebm.ist.utl.pt
wrote:

On Thu, 16 Sep 2010 14:57:01 +0100, Derick Rethans derick@php.net
wrote:

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

--

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Adam Harvey — view source

unread

So the question to be answered is: Should PHP support Annotations?

-1 on annotations.
+0 on new docblock parsing APIs.

Adam

14 years ago by Stas Malyshev — view source

unread

Hi!

Again, we should not consider docblock mainly because I think
adding/removing comments of your code should NEVER modify the overall
functionality of your application.

It's a circular argument - "we can't use docblocks because docblocks
shouldn't be used". They are not "comments" if you don't use them as
comments.

That said, docblock is no option. Now PLEASE let's stop arguing for
nothing and vote?

I do not think we should stop discussing some topic just because
somebody has made up his mind. Voting is fine, but "OK, I have made my
mind, everybody shut up and vote" is not.

I'd recommend that since syntax is not ideal, we should not vote for
the complete patch but vote for the functionality.

So the question to be answered is: Should PHP support Annotations?

WTF is "Annotations"? We didn't define it yet. Should PHP support
Fooblahblations? Sure, I'm +1 on it, let's vote.

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

14 years ago by Guilherme Blanco — view source

unread

Hi Stas,

Hi!

Again, we should not consider docblock mainly because I think
adding/removing comments of your code should NEVER modify the overall
functionality of your application.

It's a circular argument - "we can't use docblocks because docblocks
shouldn't be used". They are not "comments" if you don't use them as
comments.

I mean that any code packer can degrade the the functionality of your
app. Example:

class FakeTest extends \PHPUnit_Framework_TestCase
{
/**
* @expectedException RuntimeException
*/
public function testShouldThrowException()
{
throw new \RuntimeException('FakeTest failed.');
}
}

Would become:

class FakeTest extends \PHPUnit_Framework_TestCase
{
public function testShouldThrowException()
{
throw new \RuntimeException('FakeTest failed.');
}
}

And your test suite has now one failure.
As I said previously, comments are human readable data ONLY and should
not be shared between your code functionality and documentation.
Otherwise, let's rename the concept of docblock (documentation block)
to metadata block.

IMHO, it is conceptually wrong that by removing a comment from your
code may affect how your application works. At most, it should be less
documented, nothing else.

That said, docblock is no option. Now PLEASE let's stop arguing for
nothing and vote?

I do not think we should stop discussing some topic just because somebody
has made up his mind. Voting is fine, but "OK, I have made my mind,
everybody shut up and vote" is not.

I didn't mean we should stop the discussion. I meant that like many
others over the years lead to nowhere if we don't take the correct
action: vote.
We can still continue the thread here, I just wanted people to stop
arguing about nothing (or even deviating the thread from its original
subject) without actually make any clever point.

I'd recommend that since syntax is not ideal, we should not vote for
the complete patch but vote for the functionality.

So the question to be answered is: Should PHP support Annotations?

WTF is "Annotations"? We didn't define it yet. Should PHP support
Fooblahblations? Sure, I'm +1 on it, let's vote.

I would point the wikipedia link, but it contains very weird
description. "In the year 2065, aliens rule the Earth. Why? Because
Noah Katz took over the world with the help of his alien friends. He
calls himself a king, but a warrior among the rebelling people is
about to rise up against the alien empire to reclaim the Earth for the
human race. This warrior is the all-powerful Zeus of Mount Olympus.
The Greek gods are angry, and will not have their world taken by some
people that possibly come from another universe. The end of the alien
empire will soon come."

So I'd recommend (although I didn't like how it was written) the Java
Annotation wikipedia page:
http://en.wikipedia.org/wiki/Java_annotation

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

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Stas Malyshev — view source

unread

Hi!

I mean that any code packer can degrade the the functionality of your
app. Example:

Fix your "code packer" not to do that.

I didn't mean we should stop the discussion. I meant that like many
others over the years lead to nowhere if we don't take the correct
action: vote.

How it's the correct action on this stage? We obviously don't have
consensus on what this feature should be - we are just looking for a
possible solution now. How voting can help? People would just say "yes,
I want Annotations" while meaning totally different things by it (or
without really understanding what they vote for/against). How that's useful?

So I'd recommend (although I didn't like how it was written) the Java
Annotation wikipedia page:
http://en.wikipedia.org/wiki/Java_annotation

So, we are voting to have Java annotations in PHP? And people seriously
voting FOR it? I mean, after reading all 40+ disjoint pages of the
standard describing it in Java, and considering how that would fit PHP,
they make an informed decision that that's exactly what PHP needs right
now, correct?

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

14 years ago by Guilherme Blanco — view source

unread

Hi Stas,

Hi!

I mean that any code packer can degrade the the functionality of your
app. Example:

Fix your "code packer" not to do that.

I didn't mean we should stop the discussion. I meant that like many
others over the years lead to nowhere if we don't take the correct
action: vote.

How it's the correct action on this stage? We obviously don't have consensus
on what this feature should be - we are just looking for a possible solution
now. How voting can help? People would just say "yes, I want Annotations"
while meaning totally different things by it (or without really
understanding what they vote for/against). How that's useful?

Maybe... for those that have an idea about what it is, which would
filter by hundreds the voters, it would work.

So I'd recommend (although I didn't like how it was written) the Java
Annotation wikipedia page:
http://en.wikipedia.org/wiki/Java_annotation

So, we are voting to have Java annotations in PHP? And people seriously
voting FOR it? I mean, after reading all 40+ disjoint pages of the standard
describing it in Java, and considering how that would fit PHP, they make an
informed decision that that's exactly what PHP needs right now, correct?

Again, you change the meanings of something I write.
I do not want Java Annotations on PHP. But I want a clean way to
include metadata mapping on my class/property/method/function.
That said, I asked if PHP should support it as a poll... I'm not
requesting people to vote for Java Annotation, but I'm asking to vote
for metadata mapping that could be easily retrieved at runtime.

Is it understandable now?

It seems we both have strong arguments pro/cons it being included.
I doubt you will convince me at the same time I feel I'll never
convince you. That's another valid argument for a poll.

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

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Stas Malyshev — view source

unread

Hi!

Again, you change the meanings of something I write.
I do not want Java Annotations on PHP. But I want a clean way to
include metadata mapping on my class/property/method/function.

Everybody wants a clean way to include metadata. It's what this way is
where the difference is. So is the vote about having any metadata
retrieval mechanism? Specific proposal exactly as proposed? Some
generalization of the proposal without specifying some details?

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

14 years ago by Guilherme Blanco — view source

unread

Olá!

Hi!

Again, you change the meanings of something I write.
I do not want Java Annotations on PHP. But I want a clean way to
include metadata mapping on my class/property/method/function.

Everybody wants a clean way to include metadata. It's what this way is
where the difference is. So is the vote about having any metadata retrieval
mechanism? Specific proposal exactly as proposed? Some generalization of the
proposal without specifying some details?

The RFC contains all details of proposal.
If the syntax is not ok, then let's discuss the implementation once it
gets accepts or forget about it if not. But overall functionality is
described there.

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

--
Guilherme Blanco
Mobile: +55 (16) 9215-8480
MSN: guilhermeblanco@hotmail.com
São Paulo - SP/Brazil

14 years ago by Matthew Weier O'Phinney — view source

unread

Again, you change the meanings of something I write.
I do not want Java Annotations on PHP. But I want a clean way to
include metadata mapping on my class/property/method/function.

Everybody wants a clean way to include metadata. It's what this way is
where the difference is. So is the vote about having any metadata retrieval
mechanism? Specific proposal exactly as proposed? Some generalization of the
proposal without specifying some details?

The RFC contains all details of proposal.
If the syntax is not ok, then let's discuss the implementation once it
gets accepts or forget about it if not. But overall functionality is
described there.

I think the functionality of annotations needs to be proposed separately from
the syntax of annotations. Right now, the RFC is tying the two together -- I
think it's much more likely that you'll get buy-in for annotations if we can
focus on their purpose within the language first. From there, work on
determining whether it requires language level enhancements, and what those may
be -- the syntax and functionality as expressed in the patch, or another
possibility entirely.

I know I, for one, am not comfortable voting on the current RFC due to
questions on the approach -- though I am generally in favor of the idea of
annotations.

(I'm still not entirely convinced that the same goals could not be achieved via
code written on top of a docblock parser extension.)

--
Matthew Weier O'Phinney
Project Lead | matthew@zend.com
Zend Framework | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

14 years ago by Pierre Joye — view source

unread

hi,

On Thu, Sep 16, 2010 at 10:51 PM, Matthew Weier O'Phinney
weierophinney@php.net wrote:

(I'm still not entirely convinced that the same goals could not be achieved via
code written on top of a docblock parser extension.)

Look at the xdoclet fiasco, that should finish to convince you that
phpdoc has nothing to do with annotations.

Cheers,

Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

14 years ago by Ralph Schindler — view source

unread

I know this is drive-by/chiming in, but we've had this discussion with
the ZF community. While @expectedExcpetion is a feature of PHPUnit that
has been picked up and used by developers over the past few years, it
semantically makes no sense, and we have since outlawed its usage.

Why? B/c a "comment" is now affecting the outcome/execution of a code
block (in this case a unit test), ... particularly the way the PHPUnit
system interprets the outcome of this code block.

We've since removed all @expectedException "annotations" in favor of
$this->setExpectedException() call and try/catch blocks for more
specific usage. It just semantically makes more sense to our group of
developers.

On the other hand, we DO utilize the @group annotation in PHPUnit b/c it
does a fantastic job of grouping tests together. Case in point, @group
does not ever affect the running outcome of tests.

app. Example:

class FakeTest extends \PHPUnit_Framework_TestCase
{
/**
* @expectedException RuntimeException
*/
public function testShouldThrowException()
{
throw new \RuntimeException('FakeTest failed.');
}
}

14 years ago by Paul — view source

unread

Hi!

Again, we should not consider docblock mainly because I think
adding/removing comments of your code should NEVER modify the overall
functionality of your application.

It's a circular argument - "we can't use docblocks because docblocks
shouldn't be used". They are not "comments" if you don't use them as
comments.

Overloading comment syntax to modify application functionality is the
worst idea I've seen suggested on this list. This beats goto by miles.

We would then need a new comment syntax to comment out annotations. Just
for annotations.

Adding/removing/changing comments suddenly has an impact on
functionality. Sometimes. If the comment is really an annotation.
Despite it looking exactly like comments have looked for years.

"Why's my stuff broke? That stack trace leads me through... a
docblock?!? Wait, that comment I updated wasn't really a comment, it
just looked like one? Oh hell, that other comment I added got mistaken
for an annotation? WTF?"

This is supposed to be less confusing for people?

14 years ago by Stas Malyshev — view source

unread

Hi!

Overloading comment syntax to modify application functionality is the
worst idea I've seen suggested on this list. This beats goto by miles.

What you mean "suggested"? It's what happening right now in pretty much
any widely used framework.

"Why's my stuff broke? That stack trace leads me through... a
docblock?!? Wait, that comment I updated wasn't really a comment, it

That's why code annotations are bad idea. Metadata should not be code.
And in Java, for example, annotations are interfaces.

just looked like one? Oh hell, that other comment I added got mistaken
for an annotation? WTF?"

This is supposed to be less confusing for people?

Nothing can un-confuse person that deliberately tries to be confused.
You are fighting a strawman - nobody suggests having active code in
comments. Metadata is not code - it's data. Backtraces can't lead to
data. You can store data in a variety of formats - what is suggested
(and already is widely used) is just yet another format to
store/retrieve data.

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

14 years ago by Jonathan Bond-Caron — view source

unread

WTF is "Annotations"? We didn't define it yet. Should PHP support

http://en.wikipedia.org/wiki/.NET_metadata
http://blogs.msdn.com/b/efdesign/archive/2010/03/30/data-annotations-in-the-entity-framework-and-code-first.aspx

.NET calls this attributes but Sun invented the annotations concept in 2002:
http://www.google.com/patents/about?id=TXZ4AAAAEBAJ

PHP Annotations RFC + Patch

Cheers,

Cheers,

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.

Cheers,

annotation := [annotClassName(classArgs*)] classArgs := array | string | int | float | ...

[ExpectedException("InvalidArgumentException")] [ExpectedException("InvalidArgumentException", "Expected message", 40")] [Validation(array("type" => "EMail", "options" => array("checkMX" => true))]

This one is not very clear either - when is this "new" executed? What it is being assigned to? What you can and can't use there? It's all new concepts - which I'm not sure worth introducing.

Cheers,

Object instances can't be bytecode-cached, so when are they instantiated? Does it mean it's stateful and mutable?

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.

WTF is "Annotations"? We didn't define it yet. Should PHP support Fooblahblations? Sure, I'm +1 on it, let's vote.

So, we are voting to have Java annotations in PHP? And people seriously voting FOR it? I mean, after reading all 40+ disjoint pages of the standard describing it in Java, and considering how that would fit PHP, they make an informed decision that that's exactly what PHP needs right now, correct?

Everybody wants a clean way to include metadata. It's what this way is where the difference is. So is the vote about having any metadata retrieval mechanism? Specific proposal exactly as proposed? Some generalization of the proposal without specifying some details?

Cheers,

It would be useful if, for those unfamiliar with xdoclet history, you would explain why it was a fiasco.

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.

annotation := [annotClassName(classArgs*)]
classArgs := array | string | int | float | ...

[ExpectedException("InvalidArgumentException")]
[ExpectedException("InvalidArgumentException", "Expected message", 40")]
[Validation(array("type" => "EMail", "options" => array("checkMX" =>
true))]

This one is not very clear either - when is this "new" executed? What it
is being assigned to? What you can and can't use there? It's all new
concepts - which I'm not sure worth introducing.

Object instances can't be bytecode-cached, so when are they
instantiated? Does it mean it's stateful and mutable?

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.

WTF is "Annotations"? We didn't define it yet. Should PHP support
Fooblahblations? Sure, I'm +1 on it, let's vote.

So, we are voting to have Java annotations in PHP? And people seriously
voting FOR it? I mean, after reading all 40+ disjoint pages of the
standard describing it in Java, and considering how that would fit PHP,
they make an informed decision that that's exactly what PHP needs right
now, correct?

Everybody wants a clean way to include metadata. It's what this way is
where the difference is. So is the vote about having any metadata
retrieval mechanism? Specific proposal exactly as proposed? Some
generalization of the proposal without specifying some details?

It would be useful if, for those unfamiliar with xdoclet history, you
would explain why it was a fiasco.