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.

Die Funktionen call_user_func() oder call_user_func_array() fallen leider aus, da wir noch kein Callback-Objekt haben. Es gibt aber einen sehr einfachen Weg mit Reflections.

Zuerst ein paar einfache Klassen zum Testen. Von der Klasse Foo soll ein Objekt erstellt werden und diese erwartet je ein Objekt vom Typ Bar und Baz als Parameter im Konstruktor.

<?php
class Bar {}
class Baz {}

class Foo
{
  public function __construct(Bar $bar, Baz $baz)
  {
    echo '<pre>' . print_r(func_get_args(), true) . '</pre>';
  }
}

Nun wird das Objekt über eine sehr einfache Factory-Methode erzeugt und dabei wird die Parameterliste von create() an den Konstruktor weitergegeben.

<?php
class Factory
{
  public static function create($type)
  {
    $args = func_get_args();
    array_shift($args);
    $class = new ReflectionClass($type);
    return $class->newInstanceArgs($args);
  }
}

$foo = Factory::create('Foo', new Bar(), new Baz());

So einfach ist es. Über die Reflection-Klasse wird ein neues Objekt erzeugt.

Wir kennen es sicher alle: Wir haben irgendein Objekt und wollen dessen Status oder einen bestimmten Wert setzen oder abfragen. Was passiert sicher in 95% aller Fälle? Es wird ein String- oder Integer-Wert gesetzt oder verglichen. Aus meiner Sicht nicht besonders elegant und erst recht nicht sicher, da der Wert unnötig oft überprüft werden muss.

Mit Enums haben wir den Vorteil, dass wir bestimmte Werte vorgeben können und auch nur diese zu Verfügung stehen. Da wir unter PHP nur “normale” Klassen verwenden können, haben wir dadurch immer automatisch einen bestimmten Typen.

Wir wollen nun den Status eines Benutzers in unserem System definieren und legen uns dazu folgende Klasse mit den erforderlichen Werten an.

<?php
class UserStatus extends Custom_Enum
{
  const ACTIVE    = 1;
  const NOTACTIVE = 2;
  const DELETED   = 3;
}

Damit können wir unseren Benutzern einen eindeutigen Status setzen.

<?php
class User
{
  public function setStatus(UserStatus $status)
  {
    // ..
  }
}

$user = new User();

$status = new UserStatus();
$user->setStatus($status->active());

Durch das Type-Hinting können wir schon bei der Parameterübergabe den richtigen Objekttypen sicherstellen und müssen darauf später nicht mehr extra prüfen.

Die Klasse Custom_Enum funktioniert mit Reflektion und etwas PHP-Magie und ist bislang erst nur ein grober Entwurf. Ein paar Überprüfungen und eine bessere Fehlerbehandlung wären dann noch notwendige Maßnahmen.

<?php
abstract class Custom_Enum
{
  private $_constants;  // array
  private $_index;  // string

  public function  __construct()
  {
    $rc = new ReflectionClass($this);
    $this->_constants = $rc->getConstants();
  }

  public function __call($method, $args)
  {
    if (preg_match('/^is([a-zA-Z]*?)$/', $method, $matches)) {
      return $this->is($matches[1]);
    }
    $this->set($method);
    return $this;
  }

  public function __toString()
  {
    return (string)$this->getValue();
  }

  public function set($index)
  {
    $this->_index = strtoupper($index);
    return $this;
  }

  public function is($index)
  {
    return strtoupper($index) == $this->_index;
  }

  public function getValue()
  {
    return $this->_constants[$this->_index];
  }
}

Ich finde das schon wesentlich besser als lose String- oder Integerwerte auszutauschen, aber vielleicht geht es ja noch besser und sicherer? Eure Ideen, Kritik, Fragen oder was auch immer sind dann in den Kommentaren gut aufgehoben. Also keine Scheu und diskutiert mit!

Viele Fehler treten bei Magento schon durch eine fehlerhafte Konfiguration auf, was zur Folge haben kann, dass wir keine Instanz unser lokalisierten Klasse bekommen, sondern ein standard Magento-Objekt oder einen Fehler, weil keine passende Klasse gefunden wird.

So habe ich also angefangen, die Existenz der zu prüfenden Klassen zu testen und ob die Mage-Factory das gewünschte Objekt zurück gibt. Bei einigen Klassen ist es zudem auch noch wichtig, dass sie von der richtigen Elternklasse abgeleitet sind.

Da sich diese Tests immer wiederholten, zeichnete sich schnell ein Muster ab. Ebenso erfolgt auch die Namesgebung der Magentoklassen nach einem gewissen Muster. Was wäre also naheliegender, als beides miteinander zu verbinden und so in Zukunft eine Menge unnützer Schreibarbeit zu sparen?

Als erstes habe ich dafür einen erweiteren TestCase vom PHPUnit-TestCase abgeleitet, der mir weitere vereinfachte Asserts zur Verfügung stellt und die Tests dadurch auch etwas lesbarer macht.

$this->assertClassExists($classname);

statt

$this->assertTrue(class_exists($classname));

Auf diesem Wege lassen sich dann auch z.B. Getter und Setter einfach auf das gewünschte Standardverhalten prüfen.

Im nächsten Schritt habe ich einen Entity-TestCase abgeleitet, der als Basis für alle weiteren TestCases für Models, Blocks und Helper dienen soll. Dieser ist in sich schon ein wenig intelligenter und erkennt anhand des Namens der Test-Klasse, welche Klasse getestet werden soll, welchen Typ diese hat und welche die Standard-Elternklasse ist.

Diese Informationen werden, nebenbei bemerkt, durch protected Methoden ermittelt und könnten zu jeder Zeit durch noch speziellere TestCases wieder überschrieben werden.

Mit den nun vorliegenden Informationen ist diese TestCase-Klasse mächtig genug, um alleine durch Vererbung die grundlegenden Tests durchzuführen.

Für die jeweiligen Typen, z.B. Model habe ich dann noch weitere TestCases abgeleitet, um dort noch spezielle Methoden implementieren zu können.

Ein sehr einfacher Test für die Model-Klasse “Mein_Customer_Model_Customer” sähe dann beispielsweise so aus:

class Mein_Customer_Model_CustomerTest extends Mein_Model_TestCase
{
}

Dadurch würde nun automatisch getestet werden, ob der Autoloader die Klasse “Mein_Customer_Model_Customer” finden kann, diese von der Magento-Model-Klasse erbt und ob die Factory aufgrund der Konfiguration auch das richtige Objekt liefert.

Ich denke, dass es viel einfacher nicht mehr geht und das Argument gegen Tests damit dann auch aus der Welt sein sollte.

Kleiner Tipp: Wenn man es nun noch etwas konfortabler mag, dann kann man sich seine Models auch mit dem Zend_CodeGenerator bauen lassen und die Tests gleich mit.

Viele Methoden sind mit __call() implementiert und das hat die Nachteile, dass z.B. die Codecompletion, Reflection, automatische Dokumentation oder die Navigation in der IDE ausgehebelt werden.

Zum Glück können wir das ja zum Teil in vererbten Klassen wieder abfangen, ohne die ursprünglichen Klassen umschreiben zu müssen, z.B. weil wir die fremden Libraries zwecks späterer Updates nicht verändern wollen.

<?php

class A
{
  public function __call($method, $args)
  {
    echo __METHOD__ . ' ' . $method;
  }
}

class B extends A
{
  public function machWas()
  {
    parent::machWas();
  }
}

$b = new B();
$b->machWas();

Die Methode B::machWas() delegiert den Aufruf an die magische Methode, wobei sich das Verhalten nach außen nicht verändert, jedoch alles andere wieder funktionieren wird.