PHP, Programming

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;

More information

Related Projects

10 thoughts on “Using Annotations in PHP

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

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

  3. Pingback: DevReference.org
  4. 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.

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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s