Federico Cargnelutti

Simple is better than complex. Complex is better than complicated. | @fedecarg

Using Annotations in PHP

with 7 comments

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;

More information

Related Projects


Written by Federico

July 19, 2008 at 11:39 am

Posted in PHP, Programming

7 Responses

Subscribe to comments with RSS.

  1. Looks very interesting, thanks :)

    phpimpact

    July 22, 2008 at 8:56 pm

  2. Hey, thanks for linking my project. Do you actually use it in your projects?

    johno

    July 27, 2008 at 11:21 am

  3. 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

  4. ” 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

  5. I see the purpose of having annotations. I am always lost in code and helps going faster when comming back to job.

    fff

    March 27, 2010 at 6:04 pm

  6. [...] Using Annotations in PHP Share and [...]


Leave a Reply