Table of Contents

Request for Comments: Reflection Annotations using the Doc-Comment

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

/*
 * 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->getAnnotations()); // 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)

Applications that uses metadata today

1. Symfony 

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 
class PostController extends Controller
{
    /**
     * @Route("/")
     */
    public function indexAction()
    {
        // ...
    }
}

2. Doctorine 

class User
{
    //...
    /**
     * @ManyToMany(targetEntity="Group")
     */
    private $groups;
}

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

The methods will be applied to:

Proposal and Patch

The patch is not available yet. I don't mind to write it myself.

Changelog