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/13 10:04]
mindplay
rfc:simple-annotations [2017/09/22 13:28]
Line 1: Line 1:
-====== PHP RFC: Simple Annotations ====== 
  
-  * Version: 0.1 
-  * 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 meta-data values applicable to classes and class members, obtainable via the reflection API. 
- 
-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 extremely 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 
-  * function and method argument declarations 
-  * anonymous ''function'' and ''class'' declarations (and their members) 
- 
-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()''. 
- 
-==== Context Free ==== 
- 
-Annotations are context-free - there is no access to variables in the parent class, file or global scope, no ''self'' or ''static'' or ''$this''. 
- 
-This is by design - 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 to provide context via dependency injection. 
- 
-===== 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)