Plugins

Einführung

Die Controller Architektur beinhaltet ein Pluginsystem, das den Aufruf von Anwendercode ermöglicht, wenn bestimmte Ereignisse im Controller Prozess auftreten. Der Front Controller verwendet einen Plugin Broker als eine Registry für User Plugins und der Plugin Broker stellt sicher, dass die Ereignismethoden von jedem Plugin aufgerufen werden, die im Front Controller registriert worden sind.

Die Ereignismethoden sind in der abstrakten Klasse Zend_Controller_Plugin_Abstract definiert, von dem User Plugin Klassen angeleitet werden müssen:

  • routeStartup() wird aufgerufen bevor Zend_Controller_Front den Router aufruft, um den Request anhand der registrierten Routen zu überprüfen.

  • routeShutdown() wird aufgerufen, nachdem der Router das Routing der Anfrage beendet.

  • dispatchLoopStartup() wird aufgerufen, bevor Zend_Controller_Front den Dispatch Loop aufnimmt.

  • preDispatch() wird von dem Dispatcher aufgerufen, bevor eine Aktion verarbeitet wird. Dieser Callback erlaubt ein Proxy oder Filter Verhalten. Durch Verändern des Requests und Zurücksetzen des Verarbeitungsstatus (mittels Zend_Controller_Request_Abstract::setDispatched(false)) kann die aktuelle Aktion abgebrochen oder ersetzt werden.

  • postDispatch() wird von dem Dispatcher aufgerufen, nachdem eine Aktion verarbeitet wurde. Dieser Callback erlaubt ein Proxy oder Filter Verhalten. Durch Verändern des Requests und Zurücksetzen des Verarbeitungsstatus (mittels Zend_Controller_Request_Abstract::setDispatched(false)) kann eine neue Aktion für die Verarbeitung angegeben werden.

  • dispatchLoopShutdown() wird aufgerufen, nachdem Zend_Controller_Front den Dispatch Loop beendet.

Plugins schreiben

Um eine Plugin Klasse zu schreiben, bindet man einfach die abstrakte Klasse Zend_Controller_Plugin_Abstract ein und erweitert sie:

class MyPlugin extends Zend_Controller_Plugin_Abstract
{
    // ...
}

Keine der Methoden von Zend_Controller_Plugin_Abstract ist abstrakt, so dass Plugin Klassen nicht gezwungen werden, irgend einen der vorhandenen Ereignismethoden zu implemetieren, die oben gelistet wurden. Schreiber von Plugins brauchen nur die Methoden zu implementieren, die sie für ihre speziellen Bedürfnisse benötigen.

Zend_Controller_Plugin_Abstract stellt den Controller Plugins außerdem die Request und Response Objekte über die getRequest() und getResponse() Methoden zur Verfügung.

Plugins verwenden

Plugin Klassen werden mit Zend_Controller_Front::registerPlugin() registriert und können jederzeit registriert werden. Der folgende Schnipsel zeigt, wie ein Plugin in der Controllerkette verwendet werden kann:

class MyPlugin extends Zend_Controller_Plugin_Abstract
{
    public function routeStartup(Zend_Controller_Request_Abstract $request)
    {
        $this->getResponse()
             ->appendBody("<p>routeStartup() called</p>\n");
    }

    public function routeShutdown(Zend_Controller_Request_Abstract $request)
    {
        $this->getResponse()
             ->appendBody("<p>routeShutdown() called</p>\n");
    }

    public function dispatchLoopStartup(
        Zend_Controller_Request_Abstract $request)
    {
        $this->getResponse()
             ->appendBody("<p>dispatchLoopStartup() called</p>\n");
    }

    public function preDispatch(Zend_Controller_Request_Abstract $request)
    {
        $this->getResponse()
             ->appendBody("<p>preDispatch() called</p>\n");
    }

    public function postDispatch(Zend_Controller_Request_Abstract $request)
    {
        $this->getResponse()
             ->appendBody("<p>postDispatch() called</p>\n");
    }

    public function dispatchLoopShutdown()
    {
        $this->getResponse()
             ->appendBody("<p>dispatchLoopShutdown() called</p>\n");
    }
}

$front = Zend_Controller_Front::getInstance();
$front->setControllerDirectory('/path/to/controllers')
      ->setRouter(new Zend_Controller_Router_Rewrite())
      ->registerPlugin(new MyPlugin());
$front->dispatch();

Angenommen das keine der Aktionen igendeine Ausgabe produzieren, und nur eine Aktion aufgerufen wurde, dann erzeugt die Funktionalität des obigen Plugins trotzdem die folgende Ausgabe:

<p>routeStartup() aufgerufen</p>
<p>routeShutdown() aufgerufen</p>
<p>dispatchLoopStartup() aufgerufen</p>
<p>preDispatch() aufgerufen</p>
<p>postDispatch() aufgerufen</p>
<p>dispatchLoopShutdown() aufgerufen</p>

Anmerkung

Plugins können jederzeit während der Ausführung des Frontcontrollers registriert werden. Wenn trotzdem ein Event ausgeführt wurde für dass das Plugin eine registrierte Eventmethode enthält, wird diese Methode nicht getriggert.

Empfangen und Manipulieren von Plugins

Fallweise kann es notwendig sein ein Plugin zu entfernen oder empfangen. Die folgenden Methoden des Frontcontrollers erlauben dies:

  • getPlugin($class) erlaubt es ein Plugin durch den Klassennamen zu empfangen. Wenn kein Plugin entspricht, wird FALSE zurückgegeben. Wenn mehr als ein Plugin dieser Klasse registriert ist, wird ein Array zurückgegeben.

  • getPlugins() empfängt den kompletten Plugin Stack.

  • unregisterPlugin($plugin) erlaubt die Entfernung eines Plugins vom Stack. Es kann ein Plugin Objekt oder der Klassenname des Plugins, das entfernt werden soll, übergeben werden. Wenn der Klassenname übergeben wird, wird jedes Plugin dieser Klasse entfernt.

Plugins die in der Standard Distribution enthalten sind

Zend Framework enthält ein Plugin für die Fehlerbehandlung in der Standard Distribution.

ActionStack

Das ActionStack Plugin erlaubt es einen Stack von Anfragen zu verwalten, und operiert als postDispatch Plugin. Wenn eine Weiterleitung (z.B. ein Aufruf zu einer anderen Aktion) bereits im aktuellen Anfrage Objekt gefunden wurde, führt es nicht durch. Trotzdem, wenn nicht, prüft es seinen Stack und entfernt den obersten Teil von Ihm und leitet diesen zu der Aktion weiter die in dieser Anfrage spezifiziert ist. Der Stack wird in der LIFO Reihenfolge bearbeitet.

Das Plugin kann jederzeit vom Front Controller empfangen werden indem Zend_Controller_Front::getPlugin('Zend_Controller_Plugin_ActionStack') verwendet wird. Sobald das Plugin Objekt vorliegt, gibt es eine Anzahl von Mechanisman die verwendet werden können, um es zu manipulieren.

  • getRegistry() und setRegistry(). Intern verwendet ActionStack eine Instanz von Zend_Registry um den Stack zu speichern. Diese kann durch eine andere Registry Instanz ersetzt werden oder dieselbe mit diesen Zugriffsmethoden empfangen.

  • getRegistryKey() und setRegistryKey(). Diese können verwendet werden um anzuzeigen welcher Registryschlüssel verwendet wird wenn der Stack herausgenommen wird. Der Standardwert ist 'Zend_Controller_Plugin_ActionStack'.

  • getStack() erlaubt es den Stack von Aktionen in seiner Ganzheit zu empfangen.

  • pushStack() und popStack() erlauben es dem Stack etwas hinzuzufügen und auch zu entfernen. pushStack() akzeptiert ein Anfrageobjekt.

Eine zusätzliche Methode, forward(), erwartet ein Anfrageobjekt, und setzt den Status des aktellen Anfrageobjektes im Front Controller auf den Status des angegebenen Anfrageobjekts, und markiert dieses als unerledigt (das forciert einen weiteren Durchlauf der Dispatch Schleife).

Zend_Controller_Plugin_ErrorHandler

Zend_Controller_Plugin_ErrorHandler bietet ein Plugin für die Handhabung von Ausnahmen die von der Anwendung geworfen werden, inklusive denen die aus fehlenden Controllern oder Aktionen resultieren; das ist eine Alternative zu den Methoden die in der Sektion MVC Ausnahmen aufgeführt sind.

Die primären Ziele dieses Plugins sind:

  • Abfangen von Ausnahmen welche auftreten wenn keine passende Route existiert

  • Abfangen von Ausnahmen die durch fehlende Controller oder Aktionsmethoden auftreten

  • Abfangen von Ausnahmen die innerhalb von Controllern aufrufen

Mit anderen Worten ist das ErrorHandler Plugin kreiert worden um HTTP 404 Fehler zu behandeln (fehlende Seite) und 500 Fehler (interner Fehler). Es ist nicht dazu gedacht Ausnahmen zu fangen die in anderen Plugins verursacht werden.

Standardmäßig leitet Zend_Controller_Plugin_ErrorHandler auf ErrorController::errorAction() im Standardmodul weiter. Es kann ein alternativer Wert für dieses gesetzt werden durch Verwendung der diversen Zugriffsmethoden die zu dem Plugin existieren:

  • setErrorHandlerModule() setzt das Controller Modul das verwendet werden soll.

  • setErrorHandlerController() setzt den Controller der verwendet werden soll.

  • setErrorHandlerAction() setzt die Controller Aktion die verwendet werden soll.

  • setErrorHandler() nimmt ein assoziatives Array, welches einen der Schlüssel 'module', 'controller', oder 'action' enthalten kann und mit denen es die gewünschten Werte setzt.

Zusätzlich kann ein optionales assoziatives Array an den Konstruktor übergeben werden, welches dann an den setErrorHandler() weitergeleitet wird.

Zend_Controller_Plugin_ErrorHandler benötigt einen postDispatch() Hook und prüft auf Ausnahmen die im Antwort Objekt registriert sind. Wenn welche gefunden werden, versucht es zur registrieren Fehler Handler Aktion weiterzuleiten.

Wenn eine Ausnahme während der Abarbeitung des Error Handlers auftritt, teilt das Plugin dem Front Controller mit das eine Ausnahme geworfen werden muß, und die letzte registrierte Ausnahme im Antwort Objekt wird nocheinmal geworfen.

Den Fehler Handler als 404 Handler verwenden

Da das ErrorHandler Plugin nicht nur Anwendungsfehler erfasst, sondern auch Fehler in der Controller Kette die durch fehlende Controller Klassen und/oder Aktions Methoden auftreten, kann es als 404 Handler verwendet werden. Hierfür muß der eigene Fehler Controller den Typ der Ausnahme prüfen.

Aufgefangene Ausnahmen werden in einem in der Anfrage registrierten Objekt geloggt. Um dieses zu empfangen kann Zend_Controller_Action::_getParam('error_handler') verwendet werden:

class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');
    }
}

Sobald das Fehler Objekt vorhanden ist, kann man es über den Typ mit $errors->type; erhalten. Es wird eines der folgenden sein:

  • Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE, zeigt das keine passende Route existiert.

  • Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER, zeigt das der Controller nicht gefunden wurde.

  • Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION, zeigt das die angefragte Aktion nicht gefunden wurde.

  • Zend_Controller_Plugin_ErrorHandler::EXCEPTION_OTHER, zeigt andere Ausnahmen.

Man kann auf jeden der ersten drei Typen testen, und wenn dem so ist, eine 404 Seite anzeigen:

class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Controller oder Aktion nicht gefunden
                $this->getResponse()
                     ->setRawHeader('HTTP/1.1 404 Not Found');

                // ... Ausgabe für die Anzeige erzeugen...
                break;
            default:
                // Anwendungsfehler; Fehler Seite anzeigen, aber den
                // Status Code nicht ändern
                break;
        }
    }
}

Letztendlich kann die Anwendung die den Fehler Handler verursacht hat, empfangen werden indem die exception Eigenschaft des error_handler Objektes genommen wird:

public function errorAction()
{
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Controller oder Aktion nicht gefunden
                $this->getResponse()
                     ->setRawHeader('HTTP/1.1 404 Not Found');

                // ... Ausgabe für die Anzeige erzeugen...
                break;
            default:
                // Anwendungsfehler; Fehler Seite anzeigen, aber den
                // Status Code nicht ändern

                // ...

                // Ausnahme loggen:
                $exception = $errors->exception;
                $log = new Zend_Log(
                    new Zend_Log_Writer_Stream(
                        '/tmp/applicationException.log'
                    )
                );
                $log->debug($exception->getMessage() . "\n" .
                            $exception->getTraceAsString());
                break;
        }
}
Zuvor gerenderte Ausgaben erhalten

Wenn mehrfache Aktionen in einer Anfrage behandelt werden, oder wenn die Aktion mehrere Aufrufe zu render() macht, ist es möglich dass das Antwort Objekt bereits Inhalt in sich gespeichert hat. Das kann dazu führen das eine Mixtur von erwartetem Inhalt und Fehler Inhalt gerendert wird.

Wenn Fehler innerhalb solcher Seiten gerendert werden, ist keine Änderung notwendig. Wenn solche Inhalte nicht gerendert werden sollen, muß der Antwort Body vor dem rendern jeglicher Views gelöscht werden:

$this->getResponse()->clearBody();
Beispiele für die Verwendung des Plugins

Beispiel 147. Standardverwendung

$front = Zend_Controller_Front::getInstance();
$front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler());

Beispiel 148. Einen anderen Fehler Handler setzen

$front = Zend_Controller_Front::getInstance();
$front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler(array(
    'module'     => 'mystuff',
    'controller' => 'static',
    'action'     => 'error'
)));

Beispiel 149. Zugriffsmethoden verwenden

$plugin = new Zend_Controller_Plugin_ErrorHandler();
$plugin->setErrorHandlerModule('mystuff')
       ->setErrorHandlerController('static')
       ->setErrorHandlerAction('error');

$front = Zend_Controller_Front::getInstance();
$front->registerPlugin($plugin);

Beispiel für den Fehler Controller

Um das Fehler Handler Plugin zu verwenden, benötigt man einen Fehler Controller. Nachfolgend ist ein einfaches Beispiel.

class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Controller oder Aktion nicht gefunden
                $this->getResponse()->setRawHeader('HTTP/1.1 404 Not Found');

                $content =<<<EOH
<h1>Error!</h1>
<p>Die angefragte Seite konnte nicht gefunden werden.</p>
EOH;
                break;
            default:
                // Anwendungsfehler
                $content =<<<EOH
<h1>Fehler!</h1>
<p>Ein unerwarteter Fehler trat auf.
Bitte versuchen Sie es etwas später nocheinmal.</p>
EOH;
                break;
        }

        // Vorherige Inhalte löschen
        $this->getResponse()->clearBody();

        $this->view->content = $content;
    }
}

Zend_Controller_Plugin_PutHandler

Zend_Controller_Plugin_PutHandler bietet ein Drop-In Plugin für die Verwendung von PUT Request Bodies in Anfrage Parametern, so wie POST Anfrage Parameter. Er betrachtet die Anfrage und, wenn diese PUT ist, wird parse_str verwendet um den rohen PUT Body in ein Array von Parametern zu parsen welches dann bei der Anfrage gesetzt wird. z.B.,

PUT /notes/5.xml HTTP/1.1

title=Hallo&body=Welt

Um die 'title' und 'body' Parameter als reguläre Anfrage Parameter zu erhalten muss das Plugin registriert werden:

$front = Zend_Controller_Front::getInstance();
$front->registerPlugin(new Zend_Controller_Plugin_PutHandler());

Anschließend kann man auf die Parameter des PUT Bodies durch Ihren Namen zugreifen, von der Anfrage im eigenen Controller aus:

...
public function putAction()
{
    $title = $this->getRequest()->getParam('title'); // $title = "Hallo"
    $body = $this->getRequest()->getParam('body'); // $body = "Welt"
}
...