[RFC] Annotations

Hey everyone,

I have thought about a new feature for some days now. The initial plan
was to create a new keyword "deprecated" which should simply trigger a
warning when the right error level was set. This could have been
combined with the E_DEPRECATED level from 5.3 (maybe, otherwise
E_STRICT).

The goal was to have a possibility for PHP projects to mark some
functions, classes or methods as no longer recommend to use. The first
step would be to set this new keyword, and after some releases the
developers could remove this item. Just as it is handled in PHP itself.
I know that there is a phpDoc property for this, but when you execute
your code you'll never realize that.

I've talked to some colleagues about this feature and I was told that
e.g. Java has annotations for that. I've tried to get familiar with
this concept, and came to the following idea:

PHP would need a new syntax feature to specify them:
@deprecated public static function test( $params ) {}

With a new function, set_annotation_handler( name, callback )
developers could register there own handler for every type of needed
annotation. I would recommended to register a default handler for
"deprecated", which should trigger just a simple warning.

The first parameter of the callback should contain an array which
looks similar to the one from debug_backtrace. As an addition it
should report which function/method/class contained this annotation.

Parameters should be also possible, like they are in Java. It would
allow e.g.
@deprecated('2.34') public static function test( $params ) {}

and the callback would receive the specified parameters as additional
parameters:

function my_ deprecated_handler( $annotation, $version ) {
trigger_error( 'Will be removed in version ' . $version );
}

I'm sorry, but I think this patch is a far above my possibilities for
developing a patch on my own. Maybe someone else likes the idea, and
has some time to implement it. PHP 5.3 would be really nice ;o)

Thanks for reading, feel free to give me any type of comments

Best Regards
Tobias