rfc:simple-annotations

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

rfc:simple-annotations [2016/05/14 11:46]
mindplay
rfc:simple-annotations [2017/09/22 13:28]
Line 1: Line 1:
-====== PHP RFC: Simple Annotations ====== 
  
-  * Version: 0.2 
-  * Date: 2016-05-13 
-  * Author: Rasmus Schultz, rasmus@mindplay.dk 
-  * Status: Draft 
-  * First Published at: http://wiki.php.net/rfc/simple-annotations 
- 
-===== Introduction ===== 
- 
-This RFC proposes the introduction of simple value annotations - arbitrary values attached to classes and class members as meta-data, obtainable via reflection. 
- 
-As an alternative proposal to [[https://wiki.php.net/rfc/attributes|attributes]], this proposal aims to fully leverage existing language features, in order to provide more flexibility, lessen the learning curve, and expose meta-data in a manner that is more immediately useful, without having to build any run-time facilities. 
- 
-Compared with annotation systems such as [[https://github.com/doctrine/annotations|Doctrine Annotations]], this proposal does not attempt to define or enforce any domain rules - it does not define inheritance semantics, rules about applicable source-code elements, cardinality, or any other rules; these can be defined and implemented by userland packages. 
- 
-===== Proposal ===== 
- 
-The proposed syntax of a single annotation is very simple: 
- 
-<code> 
-"<<" <php-expression> ">>" 
-</code> 
- 
-Any valid PHP expression is a valid annotation. 
- 
-Any number of annotations may be placed in front of any of the following applicable declarations: 
- 
-  * ''class'', ''trait'' and ''interface'' declarations 
-  * ''function'' and property declarations in classes/traits/interfaces 
-  * anonymous ''function'' declarations 
-  * anonymous ''class'' declarations (and their members) 
-  * argument declarations of functions, methods and closures 
- 
-Annotations are internally collected, for each annotated class or member, in a list which can be obtained via reflection. 
- 
-The following trivial example annotates a class with a string and an array of numbers: 
- 
-<code php> 
-<< "Hello World" >> 
-<< [1, 2, 3] >> 
-class Hello 
-{} 
-</code> 
- 
-The following example annotates an entity with a ''TableName'' instance, which might be consumed by a database abstraction: 
- 
-<code php> 
-class TableName 
-{ 
-    public $name; 
-     
-    public function __construct($name) { 
-        $this->name = $name; 
-    } 
-} 
- 
-<< new TableName("users") >> 
-class User 
-{ 
-    // ... 
-} 
- 
-$reflection = new ReflectionClass(User::class); 
- 
-var_dump($reflection->getAnnotations()); 
-</code> 
- 
-Example output: 
- 
-<code> 
-array(1) { 
-  [0]=> 
-  object(TableName)#1 (1) { 
-    ["name"]=> 
-    string(5) "users" 
-  } 
-} 
-</code> 
- 
-Annotation expressions are not evaluated until reflection is invoked, and are evaluated only once and internally memoized upon the first call to ''getAnnotations()''. 
- 
-==== Annotations are Context-free ==== 
- 
-By design, annotations expressions are evaluated individually in an empty scope - which means there is no access to variables in the parent class, file, local or global scope, e.g. no ''$this'', ''self'' or ''static''. 
- 
-Annotations work consistently regardless of which source element they are applied to, and may be evaluated without first creating an object instance. 
- 
-Annotations that do require context should explicitly ask for that context - for example, you could use an anonymous function, a ''callable'', or an anonymous class, to provide context via dependency injection. 
- 
-==== Reflection API ==== 
- 
-The following classes will have an added ''getAnnotations()'' method: 
- 
- * ''ClassReflection'' 
- * ''ReflectionFunctionAbstract'' (''ReflectionFunction'' and ''ReflectionMethod'') 
- * ''ReflectionProperty'' 
- * ''ReflectionParameter'' 
- 
-The ''getAnnotations()'' method has the following signature: 
- 
-    public function getAnnotations($filter = null) : array 
- 
-The optional ''$filter'' argument, if given, filters the returned list of annotations as follows: 
- 
- * If one of ''string'', ''int'', ''float'', ''bool'' are given, filters annotations using ''is_*()'' 
- * If a fully-qualified class-name is given, filters annotations using ''instanceof'' 
- 
-If ''null'' is given (default) all annotations are returned. 
- 
-These methods do not take into account inheritance - annotations belong to the actual *declaration*, not to an abstract *member*, and as such, traversing parent classes, interfaces, etc. is up to the consumer. 
- 
-===== Backward Incompatible Changes ===== 
- 
-None. 
- 
-===== Proposed PHP Version(s) ===== 
- 
-Next PHP 7.x. 
- 
-===== RFC Impact ===== 
- 
-==== To SAPIs ==== 
- 
-TODO 
- 
-==== To Existing Extensions ==== 
- 
-TODO 
- 
-==== To Opcache ==== 
- 
-TODO 
- 
-===== Open Issues ===== 
- 
-Make sure there are no open issues when the vote starts! 
- 
-===== Unaffected PHP Functionality ===== 
- 
-Annotations are a new feature - it does not affect any existing functionality. 
- 
-===== Future Scope ===== 
- 
-TODO file-level annotations? others? 
- 
-===== Proposed Voting Choices ===== 
- 
-TODO State whether this project requires a 2/3 or 50%+1 majority (see [[voting]]) 
- 
-===== Patches and Tests ===== 
- 
-There is a draft with no available implementation at this time. 
- 
-===== Implementation ===== 
- 
-TODO 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://gist.github.com/mindplay-dk/ebd5e4f7da51da3c4e56232adef41b46|some notes in a gist]] 
- 
-===== Rejected Features ===== 
- 
-None. 
rfc/simple-annotations.txt · Last modified: 2017/09/22 13:28 (external edit)