rfc:annotations-in-docblock

Differences

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

Link to this comparison view

Next revision
Previous revision
rfc:annotations-in-docblock [2011/05/11 18:05]
guilhermeblanco created
rfc:annotations-in-docblock [2017/09/22 13:28] (current)
Line 1: Line 1:
-====== Request for Comments: How to write RFCs ======+====== Request for Comments: Annotations in DocBlock ======
  
   * Version: 1.0   * Version: 1.0
   * Date: 2011-05-11   * Date: 2011-05-11
   * Author: Guilherme Blanco <guilhermeblanco@hotmail.com>, Pierrick Charron <pierrick@php.net>   * Author: Guilherme Blanco <guilhermeblanco@hotmail.com>, Pierrick Charron <pierrick@php.net>
-  * Status: Under Discussion+  * Status: Inactive
   * First Published at: http://wiki.php.net/rfc/annotations-in-docblock   * First Published at: http://wiki.php.net/rfc/annotations-in-docblock
  
Line 42: Line 42:
 [[http://www.softwarereality.com/programming/annotations.jsp]] [[http://www.softwarereality.com/programming/annotations.jsp]]
  
-===== Proposal =====+===== Tokens choice =====
  
-First thing to be decided would be the tokens to be used for categorize an Annotation.+First thing to be decided is how would the tokens be arranged to categorize an Annotation.
  
   * Java uses [[http://en.wikipedia.org/wiki/Java_annotation|Annotations]]   * Java uses [[http://en.wikipedia.org/wiki/Java_annotation|Annotations]]
Line 50: Line 50:
  
 When using meta mapping, less characters is preferred to speed up its construction. When using meta mapping, less characters is preferred to speed up its construction.
 +Since it's a de-facto standard on docblocks to use @, we'll stick to this one for compatibility.
 +
 +===== How to define annotations =====
 +
 +**This section still needs expand on subject, since it's just an idea**
 +
 +<code php>
 +/**
 + * Foo class.
 + *
 + * @Entity {"repositoryClass": "FooRepository"}
 + * @Table  {"name": "foos"}
 + *
 + * @author "Guilherme Blanco"
 + */
 +class Foo 
 +{
 +  // ...
 +}
 +</code>
 +
 +The basic idea is to define an entry name "@[a-zA-Z_]{1}[a-zA-Z0-9_]*" and then a JSON as value.
 +That way, we could abstract the ReflectionAnnotation class as a generic implementation:
 +
 +<code php>
 +class ReflectionAnnotation
 +{
 +    private $value;
 +    
 +    public function __construct(\stdClass $value)
 +    {
 +        $this->value = $value;
 +    }
 +    
 +    public function getValue()
 +    {
 +        return $this->value;
 +    }
 +}
 +</code>
 +
 +And have a public Reflection API:
 +
 +<code php>
 +class ReflectionFunction {
 +    // ...
 +
 +    public function getAnnotations();
 +    public function getAnnotation($name);
 +    public function hasAnnotation($name);
 +}
 +
 +class ReflectionClass {
 +    // ...
 +
 +    public function getAnnotations();
 +    public function getAnnotation($name);
 +    public function hasAnnotation($name);
 +}
 +
 +class ReflectionProperty {
 +    // ...
 +
 +    public function getAnnotations();
 +    public function getAnnotation($name);
 +    public function hasAnnotation($name);
 +}
 +
 +class ReflectionMethod {
 +    // ...
 +
 +    public function getAnnotations();
 +    public function getAnnotation($name);
 +    public function hasAnnotation($name);
 +}
 +
 +class ReflectionParameter {
 +    // ...
 +
 +    public function getAnnotations();
 +    public function getAnnotation($name);
 +    public function hasAnnotation($name);
 +}
 +</code>
 +
 +Please notice that ReflectionParameter would now accept docblock to support Annotations. This is something that still needs to be discussed.
 +
 +===== Consuming =====
 +
 +<code php>
 +$reflClass = new \ReflectionClass('Foo');
 +var_dump($reflClass->getAnnotations());
 +
 +/*
 +array(3) {
 +  ["Entity"]=>
 +  object(ReflectionAnnotation)#1 (1) {
 +    ["value"]=>
 +    object(stdClass)#1 (1) {
 +      ["repositoryClass"]=>
 +      string(13) "FooRepository"
 +    }
 +  }
 +  ["Table"]=>
 +  object(ReflectionAnnotation)#2 (1) {
 +    ["value"]=>
 +    object(stdClass)#1 (1) {
 +      ["name"]=>
 +      string(4) "foos"
 +    }
 +  }
 +  ["author"]=>
 +  object(ReflectionAnnotation)#3 (1) {
 +    ["value"]=>
 +    string(16) "Guilherme Blanco"
 +  }
 +}
 +*/
 +</code>
  
 ===== Patch ===== ===== Patch =====
rfc/annotations-in-docblock.1305137101.txt.gz · Last modified: 2017/09/22 13:28 (external edit)