Request for Comments: How to write RFCs

• Version: 1.0
• Date: 2011-05-11
• Author: Guilherme Blanco guilhermeblanco@hotmail.com, Pierrick Charron pierrick@php.net
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/annotations-in-docblock

Many languages currently support metadata information. This RFC exposes an idea about how can it be implemented in PHP, providing a powerful tool that many applications can take advantage of.

Frameworks in general rely on metadata information in order to correctly work. They can use it for many purposes:

• phpUnit Providing meta functionality for test cases, examples: @dataProvider for test data iteration, @expectedException for catching exceptions, etc.
• Doctrine For Object-Relational mapping, examples: @Entity, @OneToOne, @Id, etc.
• Zend Framework Server classes Used to automate mappings for XML-RPC, SOAP, etc.
• FLOW3 for dependency injection and validation
• Symfony2 for routing rules
• Others One clear thing that comes to my mind is Validation, Functional Behavior injection (which could take advantage of Traits), etc. Also, any Framework could take advantage of it somehow.

So, any meta mapping injection could be easily achieved via the implementation of a centralized Annotations support.

The .NET framework uses Data Annotation: http://www.asp.net/mvc/tutorials/validation-with-the-data-annotation-validators-cs

An advantage here is the .net framework will process some annotations and inject behavior into the compiled source code.

It's important to note that annotations exist in java and .net but many strong use cases exist in these languages to provide hints to the compiler (@NotNull).

Metadata mapping is commonly referred an feature that cannot be used widely, so its implementation is useless. As pointed previously, there are many use cases for this support.

Though useful, the good and bad use cases of annotations are heavily debated (religiously):

http://willcode4beer.com/design.jsp?set=annotations_gotchas_best_practices

http://www.softwarereality.com/programming/annotations.jsp

First thing to be decided would be the tokens to be used for categorize an Annotation.

• Java uses Annotations
• C# uses Attributes

When using meta mapping, less characters is preferred to speed up its construction.

TBD

• 2011-05-11 guilhermeblanco Initial RFC creation.