Metadata for PHP4

[thekid]

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

[thekid]

The reflection API will need to tokenize the class file in order to
read the annotations. This is slow but already done there.

friebe, Thu, 10 Feb 2005 22:34:14 +0100

[thekid]

In future versions, we might want to support annotations for classes,
too.

friebe, Sat, 12 Feb 2005 12:49:25 +0100