Es geht um zwei einfache, aber zugleich sehr nützliche Dinge, die das PHP-Framework Symfony2 mitbringt: Ein einfaches, flexibles Event-Handling und Annotations.

Für mich waren die letzten drei Wochen auch die ersten Gehversuche mit Symfony2 und bislang wurden alle meine Erwartungen bestätigt. Das Framework ist sehr flexibel, aber auch recht komplex. Wer allerdings andere MVC-Frameworks wie Zend kennt, der wird sich auch hier schnell zurecht finden.

So, genug Lob an der Stelle. Neben der positiven Eigenschafft eines Eventhandlingsystems fiel mir auch gleich die Art auf, wie sich in Symfony2 Controllerrouten mit Annotations konfigurieren lassen.

Leider habe ich nichts Vergleichbares für Eventlistener gefunden und die klassische Konfiguration über YML gefiel mir dann auch nicht mehr so recht. Das nahm ich dann also gleich mal als praxisnahes Kennenlernbeispiel her und habe mir da was gebaut.

Als erstes braucht es immer einen Auslöser, damit die Annotations verarbeitet werden. Dafür habe ich mich an das Event “kernel.request” gehängt, das noch vor dem Kontrolleraufruf verarbeitet werden kann.

Einen speziellen Listener hatte ich erst dazwischen, habe es dann später aber wieder etwas vereinfacht. Mein Code entspricht vielleicht nicht allen Symfony-Richtlinien, aber zum Arbeiten und Erklären reicht es aus.

Zum Verarbeiten der Annotations habe ich eine einfache Klasse aufgebaut und mich dabei an den “Route()”-Annotations orientiert. Die Methode “findClass()” ist aus bestehendem Code “recycled”, da sie anders schwerer erreichbar wäre.

<?php
namespace MyNamespace\Annotations;

use Doctrine\Common\Annotations\Reader;
use Symfony\Component\EventDispatcher\EventDispatcher;

class AnnotatedEventClassLoader
{
  private $reader;
  private $eventDispatcher;
  private $eventAnnotationClass  = 'MyNamespace\\Annotations\\Event';

  /**
   * Constructor
   *
   * @param    Reader $reader
   * @param    EventDispatcher $eventDispatcher
   * @return    void
   */
  public function __construct(
    Reader $reader, EventDispatcher $eventDispatcher) {
    $this->reader = $reader;
    $this->eventDispatcher = $eventDispatcher;
  }

  public function init() {
    $listenersDir = realpath(__DIR__ . '/../../Listener');

    $iterator = new \RecursiveIteratorIterator(
      new \RecursiveDirectoryIterator($listenersDir),
        \RecursiveIteratorIterator::LEAVES_ONLY);

    foreach ($iterator as $file) {
      if (!$file->isFile() || '.php' !== substr($file->getFilename(), -4)) {
        continue;
      }

      if ($class = $this->findClass($file)) {
        $reflClass = new \ReflectionClass($class);
        if ($reflClass->isAbstract()) { continue; }

        foreach($reflClass->getMethods() as $method) {
          $annotation = $this->reader->getMethodAnnotation($method, $this->eventAnnotationClass);
          if (!$annotation instanceof Event || empty($annotation)) { continue; }
          $this->registerEvents($annotation, $class, $method->getName());
        }
      }
    }
  }

  /**
   *
   * @param    \MyNamespace\Annotations\Event $eventAnnotation
   * @param    string|object $class
   * @param    string $method
   * @return   \MyNamespace\Annotations\AnnotatedEventClassLoader
   */
  public function registerEvents($eventAnnotation, $class, $method) {
    $listener = is_object($class) ? $class : new $class();

    foreach ($eventAnnotation->getEvents() as $event) {
      $this->eventDispatcher->addListener(
        $event, array($listener, $method), $eventAnnotation->getPriority()
      );
    }
    return $this;
  }

  /**
   * Returns the full class name for the first class in the file.
   *
   * @param string $file A PHP file path
   *
   * @return string|false Full class name if found, false otherwise
   */
  protected function findClass($file) {
    $class = false;
    $namespace = false;
    $tokens = token_get_all(file_get_contents($file));
    for ($i = 0, $count = count($tokens); $i < $count; $i++) {
      $token = $tokens[$i];

      if (!is_array($token)) { continue; }

      if (true === $class && T_STRING === $token[0]) {
        return $namespace.'\\'.$token[1];
      }

      if (true === $namespace && T_STRING === $token[0]) {
        $namespace = '';
        do {
          $namespace .= $token[1];
          $token = $tokens[++$i];
         } while ($i < $count && is_array($token) && in_array($token[0], array(T_NS_SEPARATOR, T_STRING)));
       }

       if (T_CLASS === $token[0]) {
         $class = true;
       }

       if (T_NAMESPACE === $token[0]) {
         $namespace = true;
       }
     }

     return false;
   }
}

Damit der Loader später auch seinen Dienst tut, muss er noch als Listener für das “kernel.request”-Event bekannt gemacht werden. Dafür habe ich die Datei “app/config/annotations.xml” mit folgendem Inhalt angelegt.

<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

  <parameters>
    <parameter key="myapp.event.loader.class">MyNamespace\Annotations\AnnotatedEventClassLoader</parameter>
  </parameters>

  <services>
    <service id="myapp.event.loader">
      <tag name="kernel.event_listener" event="kernel.request" method="init" />
      <argument type="service" id="annotation_reader" />
      <argument type="service" id="event_dispatcher" />
    </service>
  </services>
</container>

Die Konfiguration muss dann auch noch der AppKernel-Klasse mitgeteilt werden und damit ist der Loader eingebunden.

class AppKernel extends Kernel {
  // other methods...

  public function registerContainerConfiguration(LoaderInterface $loader) {
    // ...
    $loader->load(__DIR__ . '/config/annotations.xml');
  }
}

Annotations werden durch eigene Klassen verarbeitet und können dadurch mit beliebiger Logik versehen werden. Alles was einer Annotation als Parameter mitgegeben wird, bekommt die Klasse als Array im Constructor übergeben.

Für die Registrierung von Eventlistener brauchte ich nur die Events, die hier kommasepariert übergeben werden und gegebenenfalls noch die Priotität, in dem Fall optional. Die Klasse selber wird auch durch eine Annotation als solche gekennzeichnet.

<?php
namespace MyNamespace\Annotations;

/**
 * @Annotation
 */
class Event {
  private $events = array();
  private $priority = 0;

  public function __construct($options) {
    if (isset($options['value'])) {        
      $this->setEvents($options['value']);
    }

    $this->setPriority(
      isset($options['priority']) ? $options['priority'] : 0 );
  }

  public function getEvents() {
    return $this->events;
  }

  public function setEvents($events) {
    if(!is_array($events)) {
      $events = array_map('trim', explode(',', $events));
    }
    $this->events = $events;
    return $this;
  }

  public function getPriority() {
    return $this->priority;
  }

  public function setPriority($priority) {
    $this->priority = (int)$priority;
      return $this;
  }
}

Nun sollte alles an PHP-Code und Konfiguration an seinem Platz sein, aber wie funktioniert das jetzt genau?

Durch das Event wird der Loader benachrichtigt, dass die Listener initialisiert werden sollen. Dazu wird das Verzeichnis “Listener” nach Klassen mit Annotations durchsucht, welche dann von der Annotation-Event-Klasse verarbeitet werden. Innerhalb des Loader werden dann die Listener für die Events registriert und können von da an verwendet werden.

Die Untersuchung des PHP-Codes funktioniert mit Reflections, was ansich immer den Ruf hat langsam zu sein. Der AnnotationReader verfügt über ein eigenes Caching und macht sich daher zeitlich nicht negativ bemerkbar.

Der Loader durchsucht das gesamte Verzeichnis in beliebiger Tiefe nach Dateien, daher bleibt man in der Namensvergabe frei.

Ein Listener könnte dann zum Beispiel so aussehen:

<?php
namespace MyNamespace\Bundle\Listener\Deep\Folder\Structure\Test;

use MyNamespace\Annotations\Event;

class Listener {
    /**
     * @Event("foo.bar, bar.foo", priority="1")
     * @param type $event
     */
    public function onFooBar1($event) {
        echo __METHOD__;
    }

    /**
     * @Event("foo.bar", priority="20")
     * @param type $event
     */
    public function onFooBar2($event) {
        echo __METHOD__;
    }
}

Ein Aufruf aus dem Kontroller funktioniert dann wie gewohnt über den EventDispatcher, der fast überall als Service erreichbar ist.

public function indexAction() {        
  $this->get('event_dispatcher')->dispatch('foo.bar');
}

// oder

public function indexAction() {
  $someEvent = new SomeEvent();       
  $this->get('event_dispatcher')->dispatch('foo.bar', $someEvent);
}

Wie gesagt sind das meine ersten Versuche mit Symfony und der Code ist nicht optimiert. Die Funktionen des Loaders sollten noch weiter in Unterobjekte verteilt werden, damit das ganze noch flexibler wird und auch der gecodete Teil mit dem Verzeichnisnamen ist verbesserungfähig.

Ich konnte dabei wieder ein paar Sachen lernen und vielleich spart es ja dem einen oder anderen von euch etwas Zeit, falls ihr das braucht.

Zuerst erweitern wir das Interface Custom_Model_Interface um SplSubject und ein paar eigene Methoden.

<?php
interface Custom_Model_Interface
    extends ArrayAccess,
            Iterator,
            Countable,
            SplSubject
{
  public function mark();
  public function modified();
  public function cleanModified();
  public function modifiedKeys();
}

Anschliessend kümmern wir uns um die Klassen Custom_Model und bauen alles Nötige ein.

<?php
class Custom_Model implements Custom_Model_Interface
{
  // ...
  protected $_observers;
  protected $_modified;

  public function attach(SplObserver $observer) {}
  public function detach(SplObserver $observer) {}
  public function notify() {}

  public function mark() {}
  public function modified() {}
  public function cleanModified() {}
  public function modifiedKeys() {}
  // ...
}

So weit, so gut! Die ersten drei Methoden attach(), detach() und notify() werden durch das Interface SplSubject vorgeschrieben und sind die Schnittstelle, um Observer am Objekt zu registrieren, sie zu entfernen oder zu benachrichtigen.

Mit den vier weiteren können wir den Status des Objektes setzen oder kontrollieren. Die beiden protected Eigenschaften enthalten eine Liste von Typ SplObjectStorage für die Observer und ein einfaches Array für den jeweiligen Status eines Feldes.

Bevor wir das verwenden können, müssen wir es im Konstruktor initialisieren.

public final function __construct()
{
  $this->_observers = new SplObjectStorage();
  $this->cleanModified();
  // ...
}

Der Vorteil von SplObjectStorage ist der, dass jedes Objekt nur einmal darin vorkommen kann und wir uns um die Steuerung keine Gedanken machen müssen. Das macht dann auch das Hinzufügen und Entfernen eines Observers sehr einfach.

public function attach(SplObserver $observer)
{
  $this->_observers->attach($observer);
  return $this;
}

public function detach(SplObserver $observer)
{
  $this->_observers->detach($observer);
  return $this;
}

Mir zaubert das immer ein breites Grinsen ins Gesicht, wenn eine Aufgabe mit so wenig Code gelöst werden kann und der Doc-Block teilweise länger ist als die Funktion.

Aber nun wieder zum Thema. Bevor wir uns an die wirklich einfache Benachrichtigung machen, werde ich noch schnell auf die Sache mit der Statuskontrolle eingehen. Eine Aktion, z.B. _set() setzt den “modified”-Status eines Feldes, so dass jeder Schreibzugriff auf das Modell erkennbar wird.

Dadurch haben wir später die Möglichkeit, nur zu benachrichtigen, wenn es nötig ist oder auch nur die Felder zu speichern, die sich verändert haben.

Um eine Änderung bekannt zu machen verwenden wir mark().

public function mark($key)
{
  if($this->keyExists($key)) {
    $this->_modified[$this->_mapKey($key)] = true;
  }
  return $this;
}

Die Methode erwartet den Namen eines existierenden Feldes und setzt ein Flag im Array.

Um den Status des Objektes oder eines einzelnen Feldes abfragen zu können haben wir dann modified().

public function modified($key = null)
{
  if(null !== $key) {
    return isset($this->_modified[$this->_mapKey($key)]);
  }
  return count($this->_modified) > 0;
}

Durch die Angabe des Parameters $key wird ein Feld abgefragt, ansonsten der Gesamtstatus. Nach dem selben Prinzip funktioniert dann auch cleanModified(), um den Status wieder zurück zu setzen.

public function cleanModified($key = null)
{
  if(null != $key) {
    unset($this->_modified[$this->_mapKey($key)]);
  } else {
    $this->_modified = array();
  }
  return $this;
}

Falls wir eine Liste der veränderten Felder brauchen, dann ist dafür modifiedKeys() vorgesehen.

public function modifiedKeys()
{
  $keys = array();

  foreach($this->_keys as $key) {
    if($this->modified($key)) {
      $keys[] = $key;
    }
  }

  return $keys;
}

Nachdem wir das alles durch haben, können wir uns nun notify() widmen, bevor wir unser Werk an ein paar Beispielen testen können.

public function notify()
{
  if($this->modified()) {
    foreach($this->_observers as $observer) {
      $observer->update($this);
    }
  }
  $this->cleanModified();
  return $this;
}

Die Methode macht im Prinzip nichts weiter, als bei allen in der Liste befindlichen Observer-Objekten update() aufzurufen und sich selbst als Parameter mitzugeben. Dadurch weiß die Observerklasse gleich, welches Objekt sich verändert hat.

Das folgende Beispiel zeigt einen einfachen Beobachter, der nur den Klassennamen von $subject ausgibt und eine Liste der geänderten Felder, wenn das Objekt vom Typ Custom_Model ist.

class myObserver implements SplObserver
{
  public function update(SplSubject $subject)
  {
    echo get_class($subject) . ' hat sich verändert<br/>';
    if($subject instanceof Custom_Model) {
      print_r($subject->modifiedKeys());
    }
  }
}

$model = new Person();
$model->attach(new myObserver());
$model->setId(42)
      ->setVorname('Bart');

$model->notify();

Das interessante an dem Observer-Muster ist die lose Kopplung der Objekte und die Tatsache, dass ein Observer beliebig viele Subjekte beobachten kann und umgekehrt ein Subjekt beliebig viele Observer haben kann.

So, das war es dann auch schon für diese Woche und zu diesem Thema. Wie ich einst schon sagte, ist es ein sehr ergiebiges Thema, weil sich viele Techniken in sinnvoller Verbindung anwenden lassen. Bislang haben wir trotzdem erst nur einen Datenklumpen mit etwas Dekoration.

Richtig interessant wird es dann, wenn wir die Models über Mapper-Klassen laden und speichern können, aber das wird dann evtl. das Thema einer neuen Serie…

Die Lösung ist deratig einfach, wenn man es weiß… Die Einstellung für das jeweilige Event muss natürlich im richtigen Scope in der config.xml gemacht werden.

Ist der Beobachter nun also global eingestellt, klappt es auch in allen Bereichen. Andersherum lässt sich so aber auch eine unterschiedliche Verarbeitung für das selbe Ereignis einstellen.

Aber welche Vor- und Nachteile haben denn nun die einzelnen Einstellungen?

“Lass es uns doch einfach halten”, “Das macht doch viel mehr Arbeit” oder “Mehr soll dieses Objekt nie können” und “Unsere Designer kennen das doch nur so” sind oft die Argumente warum die Eigenschaften public sein sollten.

Persönlich bin ich immer für eine saubere Datenkapselung und Verwendung von Zugriffsmethoden.

Zunächst ist es richtig, dass die Programmierung der Zugriffsmethoden mehr Arbeit macht, als einfach eine öffentliche Variable zu verwenden. Viele IDEs, z.B. Eclipse können diese Methoden aber auch automatisch generieren, so dass wirklich nur noch wenige Mausklicks nötig sind.

Viele andere Sprachen bieten die Typisierung von Variablen standardmäßig an, so dass man sich dort schon weitestgehend darauf verlassen kann welcher Typ vorliegt. PHP zum Beispiel bietet das (bislang) nicht und wir müssen uns selber darum kümmern.

Das schützt uns aber auch noch nicht davor, dass statt dem geforderten Objekttyp ein NULL-Wert gesetzt ist und wir mit einem Methodenaufruf einen Laufzeitfehler auslösen. Solche Anforderungen können wir dann in unseren Zugriffsmethoden umsetzen.

Wird einer Set-Methode ein NULL-Wert übergeben, so können wir entsprechend darauf reagieren und eine Exception werfen.

Ebenso können wir auch der Get-Methode eine nützliche Logik implementieren. Ist die Eigenschaft beim Methodenaufruf noch nicht gesetzt, können wir an dieser Stelle z.B. ein (Null-)Objekt erzeugen, einen bestimmten Wert aus der Datenbank laden oder einfach einen Standardwert zurückgeben.

Oftmals ergibt sich auch die Anforderung, auf Veränderungen an einem Objekt reagieren zu müssen. Dafür bietet sich das Observer/Beobachter-Entwurfsmuster an.

Die Beobachter müssen über eine Veränderung benachrichtigt werden und auch das funktioniert über die Zugriffsmethoden. Würden wir zu einem späteren Zeitpunkt feststellen, dass wir das Objekt beobachten müssen und dafür eine nachträgliche Veränderung der Schnittstelle erforderlich ist, bringt das meist sehr viel Arbeit und potentielle Fehlerquellen mit sich, da alle Stellen im Programm überarbeitet werden müssen, an denen das Objekt verwendet wird.

Es gibt natürlich auch immer wieder Situationen, die öffentliche Eigenschaften verlangen oder in denen die Handhabung einfacher wird, z.B. weil schon 150 Templates damit arbeiten und nicht extra angepasst werden sollen.

Verschiedene Sprachen bieten dafür Möglichkeiten an, um direkte Zugriffe auf Objekteigenschaften an Zugriffsmethoden zu delegieren.

Bei PHP ab Version 5 sind das die sogenannten Magischen Methoden oder Interceptor-Methoden __get() und __set().

Alles in allem haben wir bei der Programmierung unserer Klassen etwas mehr Aufwand, aber dafür weniger Stress, wenn sich unsere Anwendung in eine Richtung weiterentwickelt, die wir heute noch nicht vorhersehen können.