====== PHP RFC: Attributes ======
  * Version: 1.0
  * Date: 2016-04-21
  * Author: Dmitry Stogov, dmitry@zend.com
  * Status: Declined
  * First Published at: http://wiki.php.net/rfc/attributes

===== Introduction =====
Attributes (or annotations) are a form of syntactic metadata that can be added to language classes, functions, etc. PHP offers only a single form of such metadata - doc-comments. This is just a string and to keep some structured information, we had to use some pseudo-language. Then we have to parse it to access a particular element of that structure.

Many languages like Java, C#, Hack, etc provide a simpler way. They allow the definition of structured meta-information through small syntax extension.

===== Proposal =====

==== Attribute Syntax ====
<nowiki>An attribute is a specially formatted text enclosed with "<<" and ">>". Attributes may be applied to functions, classes, interfaces, traits, methods, properties and class constants. In the same way as doc-comments, attributes must be placed before the corresponding definition, but it's possible to define more than one attribute on the same declaration.</nowiki>

<code php>
<<...>>
<<...>>
function foo() {}
</code>

Each attribute definition construct may also define one or more named attribute, which may be used with no value, a single value or multiple values. See the EBNF grammar:

<code>
<attribute> ::= "<<" <namespace-name> [ "(" <value> { "," <value> } ")" ]
                { "," <namespace-name> [ "(" <value> { "," <value> } ")" ] } ">>".
<namespace-name>      ::= STRING.
<value>     ::= <php-constant> | <php-expression>.
</code>

And Example:

<code php>
<<WithoutValue, SingleValue(0), FewValues('Hello', 'World')>>
function foo() {}
</code>

It's not possible to use the same attribute name more than once on the same definition, however, it's possible to use multiple attribute values associated with this name.

<code php>
<<test(1),test(2)>> // Error
function foo() {}

<<test(1,2)>> // Works
function foo() {}
</code>

==== Arbitrary PHP Expressions as Attribute Values (AST attributes) ====

Other than simple scalars, attribute values may be represented with any valid PHP expression.

<code php>
<<test($a + $b > 0)>>
function foo($a, $b) {
}
</code>

In this case, internally, the value of the attribute is kept as an Abstract Syntax Tree, and the user will have the ability to read every individual node of this tree separately. This approach implies the usage of the same PHP syntax for meta data and eliminates the need for a separate parser.

The native usage of an AST is not especially necessary. It's also possible to use plain strings and then transform them into AST at user level, through the php-ast extension.

<code php>
<<test("$a + $b > 0")>>
function foo($a, $b) {
}
$r = new ReflectionFunction("foo");
$ast = ast\parse_code($r->getAttributes()["test"][0]);
</code>

==== Reflection ====

Reflection classes are extended with the getAttributes() methods, and return array of attributes.

<code php>
function ReflectionFunction::getAttributes(): array;
function ReflectionClass::getAttributes(): array;
function ReflectionProperty::getAttributes(): array;
function ReflectionClassConstant::getAttributes(): array;
</code>

These functions return empty array if there were no attributes defined. Otherwise, they return an array with attribute names as keys and nested arrays as the corresponding values. Attributes without values represented by empty arrays, attributes with single value by arrays with a single element, etc.

<code php>
<<WithoutValue, SingleValue(0), FewValues('Hello', 'World')>>
function foo() {}
$r = new ReflectionFunction("foo");
var_dump($r->getAttributes());
</code>

<code>
array(3) {
  ["WithoutValue"]=>
  array(0) {
  }
  ["SingleValue"]=>
  array(1) {
    [0]=>
    int(0)
  }
  ["FewValues"]=>
  array(2) {
    [0]=>
    string(5) "Hello"
    [1]=>
    string(5) "World"
  }
}
</code>
==== AST Representation ====

While internally AST is stored in native zend_ast format, Reflection*::getAttributes() methods return the corresponding representation built with objects of \ast\Node and \ast\Node\Decl classes, borrowed from [[https://github.com/nikic/php-ast|php-ast]]. These classes moved onto PHP core may be used even without php-ast extension. However, it also defines useful constants and functions, that would simplify work with AST in PHP.

<code php>
<<test($a + $b > 0)>>
function foo($a, $b) {
}
$r = new ReflectionFunction("foo");
var_dump($r->getAttributes());
</code>

<code>
array(1) {
  ["test"]=>
  array(1) {
    [0]=>
    object(ast\Node)#2 (4) {
      ["kind"]=>
      int(521)
      ["flags"]=>
      int(0)
      ["lineno"]=>
      int(0)
      ["children"]=>
      array(2) {
        [0]=>
        object(ast\Node)#3 (4) {
          ["kind"]=>
          int(520)
          ["flags"]=>
          int(1)
          ["lineno"]=>
          int(0)
          ["children"]=>
          array(2) {
            [0]=>
            object(ast\Node)#4 (4) {
              ["kind"]=>
              int(256)
              ["flags"]=>
              int(0)
              ["lineno"]=>
              int(0)
              ["children"]=>
              array(1) {
                [0]=>
                string(1) "a"
              }
            }
            [1]=>
            object(ast\Node)#5 (4) {
              ["kind"]=>
              int(256)
              ["flags"]=>
              int(0)
              ["lineno"]=>
              int(0)
              ["children"]=>
              array(1) {
                [0]=>
                string(1) "b"
              }
            }
          }
        }
        [1]=>
        int(0)
      }
    }
  }
}
</code>

[[https://github.com/nikic/php-ast|php-ast]] is also going to be included into core PHP distribution, but this is a subject of another RFC.

==== Use Cases ====

With attributes, it's extremely simple to mark some functions with some specific "flag" and then perform checks and special handling in extensions.

<code php>
<<inline>>
function add(int $a, $int $b): int {
  return $a + $b;
}

<<jit>>
function foo() {
  ...
}
</code>

Attributes may be used as a base level for an annotation system similar to Doctrine, where each attribute is represented by an object of corresponding class that perform validation and other actions.

<code php>
<?php
namespace Doctrine\ORM {

	class Entity {
		private $name;
		public function __construct($name) {
			$this->name = $name;
		}
	}

	function GetClassAttributes($class_name) {
		$reflClass = new \ReflectionClass($class_name);
		$attrs = $reflClass->getAttributes();
		foreach ($attrs as $name => &$values) {
			$name = "Doctrine\\" . $name;
			$values = new $name(...$values);
		}
		return $attrs;
	}
}

namespace {
	<<ORM\Entity("user")>>
	class User {}

	var_dump(Doctrine\ORM\GetClassAttributes("User"));
}
?>
</code>

<code>
array(1) {
  ["ORM\Entity"]=>
  object(Doctrine\ORM\Entity)#2 (1) {
    ["name":"Doctrine\ORM\Entity":private]=>
    string(4) "user"
  }
}
</code>

Attributes with AST values may be used to implement "Design by Contract" and other verification paradigms as PHP extensions.

<code php>
<<requires(
    $a >= 0,
    $b >= 0,
    $c >= 0,
    $a <= ($b+$c),
    $b <= ($a+$c),
    $c <= ($a+$b))>>
<<ensures(RET >= 0)>>
function triangleArea($a, $b, $c)
{
  $halfPerimeter = ($a + $b + $c) / 2;
 
  return sqrt($halfPerimeter
	* ($halfPerimeter - $a)
	* ($halfPerimeter - $b)
	* ($halfPerimeter - $c));
}
</code>

==== Special Attributes ====

<nowiki>Attribute names starting with "__" are reserved for internal purpose. Usage of unknown special attributes leads to compile-time error. Currently, no any special attributes are defined.</nowiki>

==== Criticism and Alternative Approaches ====

=== Doc-comments ===

Today we are using single doc-comments for any kind of meta-information, and many people don't see a benefit in the introduction of a special syntax. Everything may be grouped together and formatted using another special language.

<code php>
/**
* Compute area of a triangle
*
* This function computes the area of a triangle using Heron's formula.
*
* @param number $a Length of 1st side
* @requires ($a >= 0)
* @param number $b Length of 2nd side
* @requires ($b >= 0)
* @param number $c Length of 3rd side
* @requires ($c >= 0)
* @requires ($a <= ($b+$c))
* @requires ($b <= ($a+$c))
* @requires ($c <= ($a+$b))
*
* @return number The triangle area
* @ensures (RET >= 0)
*
* @jit
*/
 
function triangleArea($a, $b, $c)
{
  $halfPerimeter = ($a + $b + $c) / 2;
 
  return sqrt($halfPerimeter
	* ($halfPerimeter - $a)
	* ($halfPerimeter - $b)
	* ($halfPerimeter - $c));
}
</code>

This approach works, but PHP itself doesn't have efficient access to pieces of this information.
e.g. to check "jit" attribute, today, we would perform regular expression matching.

It might be possible to make PHP parse existing doc-comments and keep information as structured attributes, but we would need to invoke additional parser for each doc-comment; doc-comment may not conform to context-grammar and we have to decide what to do with grammar errors; finally this is going to be another language inside PHP.

=== Full Featured Annotation System (like Doctrine) ===

This RFC proposes only base PHP attribute functionality. It doesn't define how attributes are validated and used. The full-featured annotation systems may be implemented on top of the base. The following example shows how a real life doc-comment annotation taken from Drupal may be implemented, validated and constructed on top of PHP attributes.

<code php>
/**
  * @Block(
  *   id = "system_branding_block",
  *   admin_label = @Translation("Site branding")
  * )
  */

<<Drupal(@Block([
       "id" => "system_branding_block",
       "admin_label" => @Translation("Site branding")
]))>>
class PageTitleBlock {
} 

function TranslateDrupalAttribute($value) {
  if ($value instanceof \ast\Node) {
    if ($value->kind == 264 && count($value->children) == 1) { // '@'
      $a = $value->children[0];
      if (is_string($a) && class_exists($a)) {
        $value = new $a;
      } else if ($a instanceof \ast\Node &&
                 $a->kind == 515 && // NAME(ARGS)
                 count($a->children) == 2 &&
                 is_string($a->children[0]) &&
                 class_exists($a->children[0]) &&
                 $a->children[1] instanceof \ast\Node &&
                 $a->children[1]->kind == 128 &&
                 count($a->children[1]->children) == 1) {
        $args = $a->children[1]->children[0];
        if ($args instanceof ast\Node && $args->kind == 130) {
          $obj = new $a->children[0];
          foreach ($args->children as $arg) {
            if ($arg instanceof ast\Node &&
                $arg->kind == 525 &&
                count($arg->children) == 2 && 
                is_string($arg->children[1])) {
              $name = $arg->children[1];
              $val = $arg->children[0];
              if ($val instanceof ast\Node) {
                $obj->{$name} = TranslateDrupalAttribute($val);
              } else {
                $obj->{$name} = $val;
              }	
            } else {
              throw DrupalAnnotationError("...");
            }
          }
        } else {
          $name = $a->children[0];
          $obj = new $name($args);
        }
        $value = $obj;
      } else {
        throw DrupalAnnotationError("...");
      }
    } else {
      throw DrupalAnnotationError("...");
    }		
  }
  return $value;
}

function GetDrupalAnnotations($class_name) {
  $reflClass = new \ReflectionClass($class_name);
  $attrs = $reflClass->getAttributes();
  $ret = [];
  foreach ($attrs as $name => $values) {
    if ($name == "Drupal") {
      foreach ($values as &$value) {
        $ret[] = TranslateDrupalAttribute($value);
      }
    }
  }
  return $ret;
}

class Block {}
class Translation {
  public $text;
  function __construct($text) {
    $this->text = $text;
  }
}

var_dump(GetDrupalAnnotations("PageTitleBlock"));
</code>

<code>
array(1) {
  [0]=>
  object(Block)#11 (2) {
    ["id"]=>
    string(21) "system_branding_block"
    ["admin_label"]=>
    object(Translation)#12 (1) {
      ["text"]=>
      string(13) "Site branding"
    }
  }
}
</code>

=== '@' Prefix in Attribute Names ===

'@' symbol may be used in attribute values (as part of PHP expressions) and reused by annotation system for special purpose, but attribute names can't be prefixed with '@' their selves. See the example above.

=== Naming (attributes or annotations) ===

Different programming languages use different terms for similar features. Some use annotation, some attributes. I prefer name "attributes" because it's used in Hack and makes less fragmentation. It also makes less confusion for external high-level annotation systems (Doctrine, etc).

===== Backward Incompatible Changes =====
The RFC doesn't make backward incompatibility changes, however, it makes forward incompatibility change. This means that frameworks that use native attributes won't be able to run on PHP versions lower than 7.1.

===== Proposed PHP Version(s) =====
7.1

===== RFC Impact =====
==== To SAPIs ====
None

==== To Existing Extensions ====
[[https://github.com/nikic/php-ast|php-ast]] will require minor modification, because the patch moved classes "\ast\Node" and "\ast\Node\Decl" into core.

==== To Opcache ====
opcache modifications are parts of the proposed patch.

==== New Constants ====
None. However, we may move some constants from [[https://github.com/nikic/php-ast|php-ast]] into core.

==== php.ini Defaults ====
None.

===== Open Issues =====
  * part of patch related to new AST classes (zend_ast.*) might need to be slightly changed to satisfy need of attributes and php-ast in best way.
  * <del>getAttributes() should return empty array in case of no attributes</del> [INCLUDED]
  * <del>For each defined attribute getArray() should return a numerically indexed array independently of number of associated values. For attributes without values it should return empty arrays.</del> [INCLUDED]
  * <del>Attribute names might be namespace qualified e.g. <nowiki><<\Foo\Bar>></nowiki></del> [INCLUDED]
  * <del>It may be useful to optionally allow some extra special character e.g. <nowiki><<@\Foo\Bar>></nowiki>. This character won't have any special meaning for PHP itself, but higher layer may use this "@" as a flag of special meaning.</del> [ADDED into criticism section]
  * <del>May be we don't need special functionality for AST in attributes. We may store attribute as a simple strings and then get them through getAttributes() and call ast\parse_code() to get AST (if necessary). Both enabling and disabling native AST support make sense with their profs and cons.</del> [ADDITIONAL VOTING QUESTION]
  * <del>Naming: "Attributes" or "Annotation(s)"?</del> [ADDED into criticism section]
  
===== Proposed Voting Choices =====
The voting started on May 10th, 2016 and will close on May 24th, 2016.

<doodle title="Accept PHP Attributes? (2/3+1 majority required)" auth="dmitry" voteType="single" closed="true">
   * Yes
   * No
</doodle>

----

<doodle title="What may be used as attribute value? (simple majority wins)" auth="dmitry" voteType="single" closed="true">
   * valid PHP expression (internally represented as AST)
   * valid PHP constant (number or string)
</doodle>

===== Patches and Tests =====
[[https://github.com/php/php-src/pull/1878|PR 1878]]

===== Implementation =====
After the project is implemented, this section should contain 
  - the version(s) it was merged to
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====
  * [[https://docs.hhvm.com/hack/attributes/introduction|Attributes in Hack]]
  * [[https://en.wikipedia.org/wiki/Java_annotation|Java Annotation]]
  * [[https://wiki.php.net/rfc/annotations|Class Metadata RFC]]
  * [[https://wiki.php.net/rfc/annotations-in-docblock|Annotations in DocBlock RFC]]