Using Annotations in PHP
Annotations provide data about a program that is not part of the program itself. They have no direct effect on the operation of the code they annotate. In PHP, annotations can only be read reflectively at run time.
Basic concept of Annotations
- Add meta-data to classes, methods, properties
- Do not (directly) affect program semantics
- Can be used by tools or libraries
- Can be parameterized or simple marker annotations
Addendum is a PHP library that supports single-value and multi-value annotations. There are three annotation types:
Marker
Marker type annotations have no elements, except the annotation name itself.
Example:
class Persistent extends Annotation {}
Usage:
/** @Persistent */
class Person {
...
}
// by class name
$reflection = new ReflectionAnnotatedClass('Person');
// by instance
$person = new Person();
$reflection = new ReflectionAnnotatedClass($person);
// true
$reflection->hasAnnotation('Persistent');
Single-value
Single-value type annotations provide a single piece of data only. This can be represented with a data=value pair or, simply with the value (a shortcut syntax) only, within parenthesis.
Example:
class Table extends Annotation {}
Usage:
/** @Table("people") */
class Person {
...
}
// by class name
$reflection = new ReflectionAnnotatedClass('Person');
// contains string "people"
$reflection->getAnnnotation('Table')->value;
Multi-value
Multi-value type annotations have multiple data members. Therefore, you must use a full data=value parameter syntax for each member.
Example:
class Secured extends Annotation {
public $role;
public $level;
}
Usage:
/** @Secured(role = "admin", level = 2) */
class Administration {
...
}
// by class name
$reflection = new ReflectionAnnotatedClass('Administration');
$annotation = $reflection->getAnnnotation('Secured');
// contains string "admin"
$annotation->role;
// contains integer "2"
$annotation->level;
Hmm…
http://interfacelab.com/metadataattributes-in-php/
Jon G.
July 22, 2008 at 7:35 pm
Looks very interesting, thanks :)
Federico
July 22, 2008 at 8:56 pm
Hey, thanks for linking my project. Do you actually use it in your projects?
johno
July 27, 2008 at 11:21 am
Call me stupid but I still don’t see any purpose in having annotations in PHP source.
I understand that having meta-data might be useful but haven’t really seen anything of use, except for a single article where the author suggests “marking” model methods as RESTable so they beocme discoverable programmatically. This I thought was quite brilliant.
Cheers,
Alex
PCSpectra
November 25, 2008 at 6:18 am
” Call me stupid but I still don’t see any purpose in having annotations in PHP source. ”
If YOU don’t see the purpose, it doesn’t mean other won’t also. It is a shame that PHP is the only mainstream web technology that does not offer this kind of syntactic sugar tool.
- Java has native support
- Python has native support
- Ruby – you can easily invent them thanks to blocks
shame, they would be such a good tool for DDL/DSL purposes and beyond
iongion
October 31, 2009 at 7:27 am
[...] Using Annotations in PHP Share and [...]
DevReference.org
July 16, 2010 at 10:14 am
I’m made an experimental patch for ZendEngine/PHP, to allow native annotations in php using the @@ token (the @ was already taken).
This patch is made for PHP 5.3.5, and allows the annotation of 0 or more classes, properties, methods, and arguments for the methods.
The annotations can be accessed via the getAnnotations() method for ReflectionClass, ReflectionMethod, ReflectionProperty, and ReflectionParameter.
Marcelo Gornstein
March 16, 2011 at 12:22 pm
Thanks buddy. For those who are interested, here’s the link:
https://github.com/marcelog/AnoForPHP
Federico
April 2, 2011 at 11:07 am
Having worked with annotations in C# extensively, I was not satisfied with any of the implementations available for PHP, for a number of reasons – I wrote my own annotation library, which is available here:
http://code.google.com/p/php-annotations/
If you’d like to understand why none of the existing implementations cut it for me, you can read about my design-considerations for this project here:
http://code.google.com/p/php-annotations/wiki/DesignConsiderations
Rasmus Schultz (@mindplaydk)
February 20, 2012 at 3:13 am
Looks good, thanks Rasmus.
Federico
February 20, 2012 at 12:23 pm