<commit_before>RFC 0016: Metadata for PHP4
========================================================================
$Id$

@authors: friebe
@created: Thu Feb 10 22:15:02 CET 2005
@status: discussion, ends Fri Feb 18 19:04:21 CET 2005
@category: <core>

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: 
  <?php #[@test] ?>

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

- Hash key/value pairs:
  An annotation may have a hash map associated to it: Example:
  <?php #[@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:
  <?php #[@inject(type= 'dbconnection', name= 'news'))] ?>

Reflection
~~~~~~~~~~
The reflection API offers the following ways to retrieve these
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):
<pre>
  array(2) {
    ["webmethod"]=>
    NULL
    ["remote"]=>
    array(1) {
      ["role"]=>
      string(5) "admin"
    }
  }
</pre>

- 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

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

Related documents
-----------------<commit_msg>- Add reflection API methods for class annotations<commit_after>RFC 0016: Metadata for PHP4
========================================================================
$Id$

@authors: friebe
@created: Thu Feb 10 22:15:02 CET 2005
@status: discussion, ends Fri Feb 18 19:04:21 CET 2005
@category: <core>

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: 
  <?php #[@test] ?>

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

- Hash key/value pairs:
  An annotation may have a hash map associated to it: Example:
  <?php #[@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:
  <?php #[@inject(type= 'dbconnection', name= 'news'))] ?>

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):
<pre>
  array(2) {
    ["webmethod"]=>
    NULL
    ["remote"]=>
    array(1) {
      ["role"]=>
      string(5) "admin"
    }
  }
</pre>

- 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 method

- 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
-----------------
{'fraction_non_alphanumeric': 0.15273015035610657, 'fraction_numerical': 0.010023740437879188, 'mean_word_length': 3.6294261294261294, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1599446', 'n_tokens_mistral': 2214, 'n_tokens_neox': 2052, 'n_words': 871}