PHP のアノテーションの構文がよくわからなかったので調べて見ました。
PHP のアノテーションと言っていますが、 PHP の言語自体にアノテーションの構文はありません。PHP でアノテーションが出てきた場合は Doctrine のパッケージの一部である Doctrine Annotations が使われていることが多いです。Java に影響を受けたと書かれているので、 Java 使う方は親近感がある構文だと思います。
Doctrine Annotations のドキュメントはこちらなのですが、話がアノテーションの定義方法の方に寄っていて、実際にアノテーションを使う時にどう書くかはあまり書かれていないように見えました。ですので、ソースを見つつアノテーションの書き方をまとめてみました。
アノテーション全体
@AnnotationName(attribute)
@AnnotationName(key1=value1[, key2=value2 [, …]])
AnnotationName: アノテーションの名称を指定します。アノテーションの実態はクラスなので、クラスの名前を指定します。基本的に名前空間から指定します。
attribute: 0個以上のアノテーションの属性を指定します。属性のキー=属性の値 というように記述し、, （カンマ）区切りで複数指定できます。属性が value というキー1つだけの場合は value= を省略できます。
以下はアノテーションの例です。
<?php
namespace Annotations;
/**
* @Annotation
*/
final class MyAnnotation
{
public $strProperty;
public $intProperty;
public $boolProperty;
public $nullProperty;
public $floatProperty;
public $constProperty;
public $arrProperty;
public $mapProperty;
public $objProperty;
}
<?php
namespace Annotations;
/**
* @Annotation
*/
final class ChildAnnotation
{
public $value;
}
<?php
namespace Classes;
class Foo
{
const Baz = 3.14;
/**
* @Annotations\MyAnnotation(
* strProperty="value",
* intProperty=-123,
* boolProperty=true,
* nullProperty=null,
* doubleProperty=3.14,
* constProperty=Classes\Foo::Baz,
* arrProperty={0, 1, 2},
* mapProperty={"key": "value", "hoge"="fuga"},
* objProperty=@Annotations\ChildAnnotation(false),
* )
*/
private $bar;
}
アノテーションの属性値として指定可能な型
以下が指定できる型です。例は上記を参照してください。
文字列
文字列は “” で囲みます。
数値
数値はそのまま記載します。PHP で言う整数と浮動小数点数を指定可能です。
真偽値
ブーリアン true false も指定可能です。
null
null を指定できます。
アノテーション
アノテーションの属性の値として、アノテーションを指定することも可能です。
定数
定数を指定可能です。以前こちらで使用方法を紹介しました。
連想配列
連想配列を指定できます。 {"A", "B", "C"} のように配列形式に指定したり、 {"key": "value", "foo"="bar"} のようにマップ形式で指定もできます。key と value の区切りには : と = どちらも使用できるようです。大かっこ [] ではなく中かっこ {} なので間違えそうですね。
配列の値は、アノテーションの属性の値と同じ型を指定できます。アノテーションの配列を作ることも可能です。
アノテーション名の省略
例えば Doctrine の Id アノテーションを使う場合、 @Doctrine\ORM\Mapping\Id のようになります。名前空間からクラス名を書くとどうしても長くなってしまいます。
そういった場合は use を使うことで省略が可能です。
<?php
use Doctrine\ORM\Mapping as ORM;
class Table
{
/**
* @ORM\Id
*/
private $id;
}