PHP: rfc:reflection_doccomment_annotations

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.
Page Tools
