Doctrine Common – Annotations

Ein alter Hut in anderen Sprachen, aber in PHP gerade wirklich in und das mit gutem Grund. Annotations sind Meta-Informationen, die meist in PHP-Doc-Blöcken im Code anzufinden sind. Was dann mit diesen Informationen gemacht werden soll, kann man selbst bestimmten, dafür gibt es keinen Standard. Nehmen wir also ein Beispiel:

class Listener
{
  /**
   * @Event("SomeComponent.Render")
   */
  public function method1(Event $event)
  {
  }
}

$dispatcher->connectListener(new Listener);
$disptcher->notify("SomeComponent.Render")

In diesem einfachen Beispiel haben wir einen Event-Dispatcher, der einen Listener bekommt. Was hier wohl passieren wird ist folgendes: Der Dispatcher sieht die Annoatation @Event im Doc-Block und wertet sie aus. Er weiß, dass er diesen Listener anstupsten muss, wenn das Event „SomeComponent.Render“ passiert. Ich habe dieses Beispiel gewählt, da ich letzte Woche einen kleines Event-Dispatching-Modul geschrieben habe.

Jetzt könnte man natürlich die Implementierung dieser Annoation denkbar dumm halten und mit preg_match und der Reflection-API einfach den benötigten String rausholen. Ihr erinnert euch vielleicht an meinen Artikel darüber. Da das Thema Annotations aber gerade einen Hype erfährt haben sich viel schlauere Leute hingesetzt und eine saubere Lösung gebaut.

Diese Leute, die ich meine, haben Doctrine entworfen und als „Abfallprodukt“ kam noch ein (an Java angelehnter) Annotation-Reader bei raus. Um den soll es heute gehen. Eines möchte ich aber vorneweg noch sagen. Leider habe ich keine Dokumentation zu Doctrine & Co. gefunden, die wunderbar erklärt, wie man es verwendet. Alles Wissen habe ich aus den Unit-Tests.

Fangen wir also an. Die benötigten Klassen finden sich im Doctrine-Common-Paket, welches auf github gefunden werden kann. Das ganze Paket legen wir in unser Projekt und sagen dem Autoloader, wo er Doctrine finden kann. Jetzt können wir eigentlich auch schon loslegen mit der Implementierung.

Der AnnotationReader, den wir benutzen funktioniert wie folgt. Zuerst einmal sagen wir dem Reader, welche Annotations uns überhaupt interessieren und wie die Objekt aussehen soll, dass er uns dann zurückgibt. Danach übergeben wir ihm die Klasse oder Methode, die wir aufgeschlüsselt haben wollen als RefelctionClass bzw. ReflectionMethod. Dann nimmt sich der Reader den Doc-Block und fängt an ihn in seine Bestandteile zu zerlegen (lexing, tokenizing), darauf parsed er die Inhalte und baut uns die Objekte zusammen, die eine bestimme Annotation repräsentiert. Als Anwender müssen dabei gar nicht so tief eindringen, der Code, den wir schreiben sieht dann so oder so ähnlich aus:

$annotationReader = new AnnotationReader();
$annotationReader->setDefaultAnnotationNamespace('Phphatesme\Annotations\\');
$reflectionClass = new ReflectionClass(new Listener);
$refelctedMethod = $reflectionClass->getMethod('method1');
$annotations = $annotationReader->getMethodAnnotations($reflectedMethod);

Mit diesem Stück Code sind wir auch schon fast fertig. Die Zeile mit dem DefaultNamespace schauen wir uns aber noch einmal genauer an. Ich habe ja vorhin gesagt, dass wir dem Reader sagen müssen, was für Klassen er benutzen soll, um später die Annotation-Repräsentanten zu erstellen. Dies machen wir, indem wir den Namespace angeben. Für unseren @Event brauchen wir jetzt eine Klasse, die Phphatesme\Annotations\Event heißt und von \Doctrine\Common\Annotations\Annotation ableitet. In unserem Fall braucht diese Klasse nichts, außer einen Namen. Da sind wir also schnell mit fertig.

class \Phphatesme\Annotations\Event extends \Doctrine\Common\Annotations\Annotatio
{
}

Jetzt sollte der Code laufen und wir unsere Annotation-Objekte zusammengesammelt bekommen. Auf den Wert, den wir benötigen kommen wir dann mit $annotations[0]->value.

Ich glaube, mehr muss man gar nicht zeigen, denn die Grundideen sind relativ einfach und klar. Jeder der ein wenig tiefer in die Materie einsteigen will hat vielleicht mit dem Artikel einen „guten“ Einstiegspunkt.