rfc:reflection_doccomment_annotations
no way to compare when less than two revisions

Differences

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


Next revision
—rfc:reflection_doccomment_annotations [2013/01/06 21:53] – created yahavgb
Line 1: Line 1:
 +====== Request for Comments: Reflection Annotations using the Doc-Comment ======
 +  * Version: 1.0
 +  * Date: 2013-01-06
 +  * Author: Yahav Gindi Bar <g.b.yahav@gmail.com>
 +  * Status: Under Discussion
 +  * First Published at: http://wiki.php.net/rfc/reflection_doccomment_annotations
 +
 +===== Introduction =====
 +
 +This RFC proposes to improve the Reflection extension with methods that can interact with the doc-comment in order to retrieve decorated annotations.
 +
 +==== Why do we need it? ====
 +
 +Today's scripts using the doc-comment to store information, such as variables types, function/method return type and so on. However, in addition to that standard usage, because the lack of Annotations in PHP, some complex applications uses the doc-comment in order to provide some static metadata. In order to read that metadata, the developers implement a function that uses Reflection's getDocComment() and analyze it in userland.
 +
 +===== About the implementation =====
 +
 +This RFC propose is to include the ability to read doc-comment annotations directly from Reflection.
 +You should note that this implementation does not contains any complex features such as "constructors" or code evaluating, like in Doctorine implementation.
 +This implementation only gives access to the decorated annotations values.
 +
 +===== Simple examples =====
 +<code php>
 +/*
 + * This class representing a user.
 + * @Table("Users")
 + */
 +class User
 +{
 +    /**
 +     * The user id
 +     * @var Integer
 +     * @Key
 +     */ 
 +    private $id;
 +    
 +    /**
 +     * The user name
 +     * @var String
 +     * @MaxLength 255
 +     * @Type varchar
 +     */ 
 +    private $name;
 +}
 +
 +$han = new ReflectionClass("User");
 +
 +print_r($han->getAllAnnotations()); // Array( [Table] => Users )
 +
 +print_r($han->getProperty("name")->getAnnotations()); // Array( [var] => "string", [MaxLength] => 255, [Type] => varchar )
 +var_dump($han->getProperty("id")->hasAnnotation("type")); // bool(false)
 +var_dump($han->getProperty("name")->getAnnotation("MaxLength")); // int(255)
 +</code>
 +
 +===== Applications that uses metadata today =====
 +
 +1. Symfony
 +<code php>
 +use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 +
 +class PostController extends Controller
 +{
 +    /**
 +     * @Route("/")
 +     */
 +    public function indexAction()
 +    {
 +        // ...
 +    }
 +}
 +</code>
 +
 +2. Doctorine
 +<code php>
 +class User
 +{
 +    //...
 +    /**
 +     * @ManyToMany(targetEntity="Group")
 +     */
 +    private $groups;
 +}
 +</code>
 +
 +===== User-land implementations =====
 +
 +Well-known implementations can be found at Symfony and Doctorine code, as well as at Zend Framework.
 +
 +===== List of methods to implement =====
 +
 +  * getAllAnnotations()
 +  * getAnnotation(string annotationName)
 +  * hasAnnotation(string annotationName)
 +
 +The methods will be applied to:
 +  * ReflectionClass
 +  * ReflectionMethod
 +  * ReflectionFunction
 +  * ReflectionProperty
 +
 +===== Proposal and Patch =====
 +
 +The patch is not available yet. I don't mind to write it myself.
 +
 +===== Changelog =====
 +
 +   * 2013-01-06 Initially created by Yahav Gindi Bar.
  
rfc/reflection_doccomment_annotations.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools