rfc:simple-annotations

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:simple-annotations [2016/05/13 10:04]
mindplay
rfc:simple-annotations [2016/06/27 17:45]
mindplay remove provision about reserved annotations
Line 1: Line 1:
 ====== PHP RFC: Simple Annotations ====== ====== PHP RFC: Simple Annotations ======
  
-  * Version: 0.1+  * Version: 0.3
   * Date: 2016-05-13   * Date: 2016-05-13
   * Author: Rasmus Schultz, rasmus@mindplay.dk   * Author: Rasmus Schultz, rasmus@mindplay.dk
Line 9: Line 9:
 ===== Introduction ===== ===== 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.+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. 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.
Line 17: Line 17:
 ===== Proposal ===== ===== Proposal =====
  
-The proposed syntax of a single annotation is extremely simple:+The proposed syntax of a single annotation is very simple:
  
 <code> <code>
Line 29: Line 29:
   * ''class'', ''trait'' and ''interface'' declarations   * ''class'', ''trait'' and ''interface'' declarations
   * ''function'' and property declarations in classes/traits/interfaces   * ''function'' and property declarations in classes/traits/interfaces
-  * function and method argument declarations +  * anonymous ''function'' declarations 
-  * anonymous ''function'' and ''class'' declarations (and their members)+  * 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. Annotations are internally collected, for each annotated class or member, in a list which can be obtained via reflection.
Line 80: Line 81:
 Annotation expressions are not evaluated until reflection is invoked, and are evaluated only once and internally memoized upon the first call to ''getAnnotations()''. 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 ====
  
-Annotations are context-free - there is no access to variables in the parent class, file or global scope, no ''self'' or ''static'' or ''$this''.+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''.
  
-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 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.+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_int()'', ''is_string()'', etc. 
 +   * 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 ===== ===== Backward Incompatible Changes =====
Line 118: Line 141:
 Annotations are a new feature - it does not affect any existing functionality. Annotations are a new feature - it does not affect any existing functionality.
  
-===== Future Scope =====+===== Out of Scope =====
  
-TODO file-level annotations? others?+It has been suggested that this RFC should reserve certain names for compiler directives, such as (for instance) the memoization-directive [[https://docs.hhvm.com/hack/attributes/special|supported by Hack]]. This proposal does not reserve any such names, because (as others pointed out during that discussion) these are not meta-data, but rather directives for the compiler, and such features ought to be supported directly by keywords or syntax rather than by magical meta-data.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
rfc/simple-annotations.txt · Last modified: 2017/09/22 13:28 (external edit)