Annotation PHP 7 View as Markdown

Hi,

As one of the original authors of both Doctrine Annotations and previous
RFC of native Annotations in PHP, I can go thoroughly on every specific
detail about challenges of design decisions to make.

Primarily, I do not see docblocks as the right place to store class'
metadata information. Metadata != Comments.
This brings the next piece of the puzzle. We have to update lexical and
semantical understanding of PHP. Taking Java's approach (@) does not work
in PHP, because it conflicts with error supression. Same thing happened for
{}. When Pierrick and I wrote the RFC, [] was not supported, so likely
it'll break parsing too now, but at that point, we got [] to work.
Ultimately, we chose <> to avoid headaches.

After that, we entered on how we could semantically validate arguments. We
could easily create an array declaration (as Benjamin suggested), but that
would become near to impossible for a large system to figure it out where
it was the problem, the small made typo. The solution was to instantiate
classes (or what we folded during development, a special class type,
annotation), because we could validate semantically not only classes, but
also properties. We could also implement annotation targets (something can
only be used in a method or at the class level).
This is a valid thing to consider... more effort to the language means less
efforts from end-users (consumers). Bringing annotation targeting,
semantical validation was a great addiction to the RFC, because it makes
easier to developers find bugs, but it exposed another set of problems (and
their solutions):

1- How to instantiate them?

We dropped "new" necessity under that scope and used <>. Again, it made
more sense to specialize class definition into a new type (annotation), but
we kept same implementation for simplicity.

2- How to consume on Reflection?

We decided to use it by fetching based on class name. This added the
enforcement of only having 1 instance of a class per annotation context.

3- How to partially attribute class properties while others rely on
convention over configuration?

We had to bring named parameters to fix this.

4- How to deal with nested Annotations?

When we dropped "new", it became easy to support them by using <>.

Despite any decision, inheritance is also a problem to solve. Should it
clear everything out if a method is overwritten? Should a class require
redeclaration of everything? This adds complexity and error-prone
situations.
What if everything gets inherited by default? Well, then we need a way to
remove other previously declared items. We came up with the solution to
just clear them until we got into further discussion. We had an Override
patch that would inherit everything by default and with Override it would
clear any previously declared Annotations too based on discussion's result.

I hope that gives a but more insight on how RFC Annotations reached that
level of maturity.

Cheers,

For python-style decorators, at least the way they work in Python, we'd
need to organize our function tables differently, as Python just
replaces the function with another one while decorating, and I'm not
sure it'd be as easy to do with PHP.

Are you sure this would be difficult? We could create a closure of the
class method (trivial to do), pass it to a userland function upon creating
the class (the former is easy, the “upon creating the class” is the issue),
and use the closure it returns as the class method. There’d be issue with
autoloading to iron out, but I don’t think it’d be a problem.

You'd have to convert all such functions to closures (or something that
can be both, maybe) and have the engine be aware that function table now
can store closures. And, also, inheritance may get a bit weird there. It
would be very powerful, but it may not be very simple to do.

A closure is just a normal function, actually. The Closure class just
wraps a zend_function and a this pointer. There’s no reason you couldn’t
substitute here. I believe you could literally just copy the zend_function
across, though there’d obviously be some complications.

Not sure about inheritance.

Also, it is a major overkill for what annotations are commonly used -
attaching a piece of data to an entity. In Python, decorators are very
powerful for modifying function behavior (i.e., attaching pre/post
conditions to functions or doing some things phpunit does is really
easy) but it is too much for just attaching data.

This is useful for merely attaching data as well (just return the function
passed), but it also enables manipulating the function. It could replace
some cases of merely attaching data, too, by making the function do
something itself, rather than having something else do something if a
function has a certain annotation, when calling that function (if that
makes any sense).

--
Andrea Faulds
http://ajf.me/

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

In Python, decorators are very
powerful for modifying function behavior (i.e., attaching pre/post
conditions to functions or doing some things phpunit does is really
easy) but it is too much for just attaching data.

FWIW (and I apologize if this is just adding to the noise), one of the most powerful things about decorators in Python is that the decorator can do different things in different contexts.

For example, in the web-app context @app.task might cause a function’s execution be deferred, and return quickly so the actual work can be carried out by another process.

In a worker context, @app.task could be used to define the work that should actually be carried out by the current worker.

Reference for those interested in a practical example: http://celery.readthedocs.org/en/latest/userguide/tasks.html

S