thekid/rfc — Issue #16: RFC 0016: Metadata for PHP4
Author: thekid
Created: 2011-10-09 14:09:24+00:00
State: open
Labels: implemented, rfc

Scope of Change
====
Annotations (metadata) may be embedded within the sourcecode using
the @ sign to prefix them.

Rationale
====
This feature will be useful to mark test methods in the Unit Test API
(instead of relying on the "test" prefix), the webservices APIs (XML-RPC
and SOAP) for marking methods as remotely callable as well as the new
and yet unimplemented application server (using annotations there
instead of implementing marker interfaces such as "SessionBean" or
"EntityBean" - see also the EJB 3.0 specs).

Functionality
====
The syntax will be almost the same as in the patched PHP (see related
documents below for definitions) but will make use of the "#" sign (so
that effectively, the annotations are comments).

Example #1: Webservices API
----

```php

```

Example #2: Unit test API
----

```php

```

Syntax definitions
----
- All annotations begin with the hash sign ("#") (so that the PHP4 parser
ignores them) and are then enclosed in square brackets ("[" and "]").

- Annotation tag names may be made up of any character from a-z and A-Z
and the underscore ("_").

- Annotation tag names are case-sensitive.

- Simple definition:
In the simple annotation only a simple annotation tag exists. Example:
#[@test]

- String value:
An annotation may have a string value associated to it. Example:
#[@deprecated('Use foo() instead')]

- Hash key/value pairs:
An annotation may have a hash map associated to it: Example:
#[@fromxml(xpath= '/root/element[position() = 3]/@id')]

Hash keys may consist of any character from a-z and A-Z and the
underscore ("_"). Key names are case sensitive.

Multiple elements in a hash are separated by commas. Example:
#[@inject(type= 'dbconnection', name= 'news'))]

Values may have an array associated with them:
#[@restricted(roles = array('admin', 'root'))]

Reflection
----
The reflection API offers the following ways to retrieve these
annotations:

Method annotations
----
- bool lang.reflect.Method::hasAnnotations()
Allows you to check whether any annotation exists for this method

- array lang.reflect.Method::getAnnotations()
Returns an associative array of annotation names and their
values.

Example (for CustomerHandler::sendMessage):

```
array(2) {
["webmethod"]=>
NULL
["remote"]=>
array(1) {
["role"]=>
string(5) "admin"
}
}

```

- mixed lang.reflect.Method::getAnnotation($name [, $key])
Returns the annotation's value specified by name. Throws a
lang.ElementNotFoundException in case the annotation is not found

- bool lang.reflect.Method::hasAnnotation($name [, $key])
Allows you to check if a annotation exists

Class annotations
----
- bool lang.XPClass::hasAnnotations()
Allows you to check whether any annotation exists for this class

- array lang.XPClass::getAnnotations()
Returns an associative array of annotation names and their
values.

- mixed lang.XPClass::getAnnotation($name [, $key])
Returns the annotation's value specified by name. Throws a
lang.ElementNotFoundException in case the annotation is not found

- bool lang.XPClass::hasAnnotation($name [, $key])
Allows you to check if a annotation exists

Dependencies
====
The APIdoc parser and the reflection API will need to be changed to
recognize these comments.

Related documents
====
- xp-framework/rfc #8: Patches to the Zend Engine
http://xp-framework.net/rfc/0008.rfc.html

- PHP5 patch
http://experiments.xp-framework.net/?arena,php5

- The patch showcase: Mapping Objects to XML Files using Annotations
http://xp-framework.info/xml/xp.en_US/news/view?10

- Example script using annotations
http://xp-framework.net/downloads/metadata_xml.phps

- Annotations in Tiger, Part 1: Add metadata to Java code
http://www-106.ibm.com/developerworks/library/j-annotate1/?ca=dnt-535

- Patch that adds this functionality
http://xp-framework.net/downloads/rfc0016.diff

Comments
====
- friebe, Thu Feb 10 22:34:14 CET 2005
The reflection API will need to tokenize the class file in order to
read the annotations. This is slow but already done there.

- friebe, Sat Feb 12 12:49:25 CET 2005
In future versions, we might want to support annotations for classes,
too.