Description
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
#[@webservice(name= 'Customer')]
class CustomerHandler extends Object {
#[@webmethod]
function getByCustomerId($customerId) {
// ...
}
#[@webmethod, @restricted(role= 'admin')]
function sendMessage($customerId, &$message) {
// ...
}
}
?>Example #2: Unit test API
<?php
class ParserTest extends TestCase {
#[@test]
function tokenOrder() {
// ...
}
}
?>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 Extensions to PHP5 core #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