# Der Front Controller

## Übersicht

`Zend_Controller_Front` implementiert ein Front Controller-Entwurfsmuster, das in Model-View-Controller (MVC)-Anwendungen verwendet wird. Seine Aufgabe ist, die Abfrage-Umgebung u initialisieren, die eingehende Abfrage zu routen und dann die Anfrage an alle angefragten Aktionen weiterzuleiten (das alles zusammen wird auch dispatchen genannt); er fasst alle Antworten zusammen und gibt sie zurück, wenn der Prozess beendet ist.

`Zend_Controller_Front` implementiert auch das Singleton-Entwurfsmuster , das heißt nur eine einzige Instanz dieser Klasse darf zu jedem Zeitpunkt existieren. Das ermöglicht es auch, dass der Front-Controller als Registry fungiert, in der alle anderen Objekte des Prozesses Daten persistent speichern können.

`Zend_Controller_Front` registriert einen Plugin-Broker in der Registry, die er selber ist, was es erlaubt, verschiedene Events, die er auslöst, von den Plugins überwachen zu lassen. In den meisten Fällen gibt das dem Entwickler die Möglichkeit, einen maßgeschneiderten Dispatch-Prozess zu entwerfen, ohne den Front-Controller erweitern zu müssen um Funktionalität hinzuzufügen.

Als ein absolutes Minimum, um zu funktionieren, braucht der Front-Controller den Pfad zu einem oder mehr Verzeichnissen, die Action-Controller enthalten. Verschiedene Methoden können auch noch aufgerufen werden, um die Front-Controller-Umgebung und die seiner Hilfsklassen anzupassen.

### Standardverhalten

Standardmäßig lädt der Front-Controller sowohl das ErrorHandler-Plugin als auch das ViewRenderer-Action-Helper-Plugin. Diese sind dafür geschrieben, Fehlerbehandlung bzw. das Rendern von Views in den Controllern zu vereinfachen.

Um den ErrorHandler abzuschalten, kann der folgende Code an jeder Stelle vor dem Aufruf der `dispatch()`-Methode des Front-Controllers ausgeführt werden:

    // Error-Handler-Plugin abschalten:
    $front->setParam('noErrorHandler', true);

Um den ViewRenderer abzuschalten muss wiederum der folgende Code vor dem `dispatch()` ausgeführt werden:

    // Den ViewRenderer Action-Helper deaktivieren:
    $front->setParam('noViewRenderer', true);

## Grundlegende Methoden

Der Front-Controller hat etliche Zugriffsmethoden, die benutzt werden können, um seine Umgebung zu konfigurieren. Jedoch gibt es drei grundlegende Methoden, die entscheidend für die funktionalität des Front-Controllers sind:

### getInstance()

`getInstance()` wird benutzt, um eine Front-Controller Instanz zu erhalten. Da der Front-Controller das Singleton-Entwurfsmuster implementiert, ist das auch die einzige Möglichkeit, ein Front-Controller Objekt zu erhalten.

    $front = Zend_Controller_Front::getInstance();

### setControllerDirectory() und addControllerDirectory()

`setControllerDirectory()` wird benutzt, um dem Dispatcher zu sagen, wo er nach Action-Controller-Klassendateien suchen soll. Sie akzeptiert sowohl einen einzelnen Pfad als auch ein Array aus Modul und Pfad-Paaren.

Ein Paar Beispiele:

    // Standard-Controller-Verzeichnis setzen:
    $front->setControllerDirectory('../application/controllers');

    // Einige Modul-Ordner auf einmal setzen:
    $front->setControllerDirectory(array(
        'default' => '../application/controllers',
        'blog'    => '../modules/blog/controllers',
        'news'    => '../modules/news/controllers',
    ));

    // Den Ordner für das Modul 'foo' hinzufügen:
    $front->addControllerDirectory('../modules/foo/controllers', 'foo');

Wenn `addControllerDirectory()` ohne einen Modulnamen verwendet wird, setzt sie den Ordner für das Modul default -- und überschreibt einen Pfad, der vorher gesetzt wurde.

Die aktuellen Einstellungen für den/die Controller-Ordner können mit `getControllerDirectory()` abgerufen werden; das gibt ein Array mit Modul und Verzeichnis-Paaren zurück.

### addModuleDirectory() und getModuleDirectory()

Ein Aspekt des Frontcontrollers ist das man eine modulare Verzeichnisstruktur definieren kann für die Erstellung von alleinstehenden Komponenten; diese werden "Module" (modules) genannt.

Jedes Modul sollte in seinem eigenen Verzeichnis sein und die Verzeichnisstruktur des Standardmoduls spiegeln -- z.B., sollte es mindestens ein `/controllers/` Unterzeichnis haben und typischerweise ein `/views/` Unterverzeichnis und andere Anwendungsverzeichnisse.

`addModuleDirectory()` erlaubt es den Namen des Verzeichnisses zu übergeben der ein oder mehrere Modulverzeichnisse enthält. Er scannt dieses dann und fügt es den Controllerverzeichnissen des Frontcontrollers hinzu.

Später, wenn man den Pfad zu einem speziellen Modul oder dem aktuellen Modul eruieren will, kann `getModuleDirectory()` aufgerufen werden und optional ein Modulname übergeben werden für das das spezielle Modulverzeichnis geholt werden soll.

### dispatch()

`dispatch(Zend_Controller_Request_Abstract $request = null, Zend_Controller_Response_Abstract $response = null)` erledigt die Schwerstarbeit des Front-Controllers. Sie nimmt als Parameter optional ein Anfrage-Object und/oder ein Antwort-Objekt entgegen, was dem entwickler erlaubt, wahlweise eigene Objekte für diese beiden Aufgaben zu bestimmen.

Wenn kein Anfrage- oder Antwort-Objekt angegeben werden, wird `dispatch()` nach vorher registrierten Objekten suchen und diese benutzen oder Standard-Versionen für seinen Prozess instanzieren (in beiden Fällen wird der HTTP Dialekt als Standard benutzt).

Auf ähnliche Art sucht `dispatch()` nach registrierten Router- und Dispatcher-Objekten und instanziert die Standard-Versionen wenn keine gefunden werden.

Der Dispatch-Prozess hat drei verschiedene Schritte:

- Routing

- Dispatching

- Antwort

Das Routing geschieht genau einmal, indem die Werte aus dem Anfrage-Objekt benutzt, die zum Zeitpunkt des Aufrufes von `dispatch()` vorhanden waren. Das Dispatchen geschieht in einer Schleife; eine Anfrage kann entweder melden, dass es mehrere Aktionen gibt, die ausgeführt werden sollen, oder der Controller oder ein Plugin können das Anfrage-Objekt zurücksetzen, um zu erzwingen, dass noch zusätzliche Aktionen ausgeführt werden sollen. Wenn alles erledigt ist, gibt der Front-Controller eine Antwort zurück.

### run()

`Zend_Controller_Front::run($path)` ist eine statische Methode, die einfach einen Pfad zu einem Verzeichnis, das Action-Controller enthält, als Parameter akzeptiert. Sie holt sich eine Front-Controller-Instanz (mit getInstance(), registriert den angegebenen Pfad mit setControllerDirectory(), und dispatcht schlussendlich.

Im Grunde ist `run()` eine Komfort-Methode, die für Seitenkonstellationen benutzt werden kann, die keine Anpassung der Front-Controller-Umgebung benötigen.

    // Front-Controller instanzieren, Controller-Verzeichnis setzen
    // und dispatchen in einem einfachen Schritt:
    Zend_Controller_Front::run('../application/controllers');

## Methoden für Umgebungszugriff

Zusätzlich zu den oben aufgelisteten Methoden gibt es eine Menge Zugriffsmethoden, die benutzt werden können, um die Front-Controller-Umgebung zu beeinflussen -- und damit die Umgebung der Klassen, an die der Front-Controller seine Arbeit weiterleitet.

- `resetInstance()` wird benutzt, um alle aktuellen Einstellungen zu löschen. Ihr hauptsächlicher Nutzen sind Testfälle, aber sie kann auch für Fälle benutzt werden, in denen mehrere Front-Controller-Ausführungen aneinander gehängt werden sollen.

- `setDefaultControllerName()` und `getDefaultControllerName()` erlauben es, dem Front-Controller einen anderen Namen für den Standard-Action-Controller mitzugeben (ansonsten wird 'index' benutzt), bzw. den aktuellen Wert herauszufinden. Diese Funktionen leiten die Anfragen an den Dispatcher weiter.

- `setDefaultAction()` und `getDefaultAction()` erlauben analog, den Standard-Aktionsnamen zu setzen - ohne Einstellung wird 'index' verwendet - und den aktuellen Wert auszulesen. Auch diese beiden leiten an den Dispatcher weiter.

- Mit `setRequest()` und `setRequest()` kann die Request Klasse oder das Objekt, das während des Dispatch-Prozesses verwendet wird und um das aktuelle Objekt zu erhalten. Wenn das Requestobjekt gesetzt wird, kann ein Request-Klassenname übergeben werden, und in diesem Fall wird die Methode die Klassendatei laden und Sie initialisieren.

- Mit `setRouter()` sowie `setRouter()` kann auf die gleiche Art der Klassenname bzw. das Objekt übergeben bzw. zurückgegeben werden, das beim dispatchen als Router verwendet wird.

  Wenn nach dem Router-Objekt gefragt wird, wird erst überprüft, ob eines existiert. Wenn nicht, wird der Standard-Router (der Rewrite-Router) instanziert und zurückgegeben.

- `setBaseUrl()` und `setBaseUrl()` erlauben es, die Basis URL zu setzen, die beim Routen der Anfrage außen vor gelassen wird, sowie den aktuellen Wert dieser Einstellung zu erhalten. Diese URL wird dem Request-Objekt erst direkt vor dem Routing bekannt gemacht.

- `setDispatcher()` und `setDispatcher()` kann die Dispatcher-Klasse oder das Dispatcher-Objekt setzen, das den Dispatch-Prozess übernimmt. Wie oben, so kann auch hier ein Klassenname oder ein Objekt übergeben werden; die get-Methode gibt in jedem Fall ein Objekt zurück.

  Wenn das Dispatcher Objekt empfangen wird, wird erst überprüft, ob bereits ein Dispatcher existiert, wenn nicht, wird der Standard-Dispatcher instanziert und zurückgegeben.

- Über `setResponse()` und `setResponse()` kann das Antwort-Objekt gesetzt bzw. erhalten werden. Auch hier kann wieder ein Klassenname oder ein Objekt übergeben werden.

- Mit `registerPlugin(Zend_Controller_Plugin_Abstract $plugin, $stackIndex = null)` können Front-Controller-Plugins registriert werden. Über den optionalen `$stackIndex` kann kontrolliert werden, in welcher Reihenfolge die Plugins ausgeführt werden.

- `unregisterPlugin($plugin)` kann registrierte Plugin-Objekte entfernen. `$plugin` kann entweder ein Plugin-Objekt oder eine Zeichenkette sein, welche die Klasse des zu entfernenden Plugins angibt.

- Mit `throwExceptions($flag)` wird festgelegt, ob Exceptions (Ausnahmen), die während des Dispatch-Prozesses von Plugins, Controllern, Hilfsklassen etc. geworfen werden. Als Standardeinstellung werden Exceptions gefangen und im Antwort-Objekt gespeichert. Das Einschalten von `throwExceptions()` überschreibt dieses Verhalten.

  Mehr Informationen gibt es hier: MVC Exceptions.

- `returnResponse($flag)` stellt ein, ob die Antwort nach `dispatch()` vom Front-Controller zurückgegeben werden soll (`TRUE`) oder ob er sie automatisch ausgibt (`FALSE`). In der Standardeinstellung wird die Antwort automatisch ausgegeben (durch Aufruf von `Zend_Controller_Response_Abstract::sendResponse()`); das Einschalten von `returnResponse()` ändert das.

  Gründe, die Antwort zurückzugeben, wären zum Beispiel der Wunsch, nach Fehlern zu suchen, bevor die Antwort ausgegeben wird, das Logging verschiedener Aspekte der Antwort (bspw. HTTP-Header), etc.

## Front Controller-Parameter

In der Einführung haben wir erwähnt, dass der Front-Controller auch als eine Registry für die verschiedenen Controller-Komponenten fungiert. Das macht er über eine Gruppe von "param"-Methoden, de es erlauben, beliebige Daten -- Objekte und Variablen -- im Front-Controller zu registrieren, die dann zu jeder Zeit im Dispatch-Prozess abgerufen werden können. Diese Werte werden weitergegeben an den Router, den Dispatcher, und an die Aktions-Controller. Diese Methodengruppe besteht aus:

- `setParam($name, $value)` setzt einen einzelnen Parameter mit dem Namen `$name` und dem Wert `$value`.

- `setParams(array $params)` setzt mehrere Parameter auf einmal mit Hilfe eines assoziativen Arrays.

- `getParam($name)` gibt den Parameter `$name` zurück.

- `getParams()` gibt eine komplette Liste mit allen gesetzten Parametern zurück.

- `clearParams()` kann einen Parameter löschen (wenn eine Zeichenkette mit einem gültigen Namen übergeben wird), mehrere benannte Parameter (wenn ein Array mit mehreren Parameter-Namen übergeben wird) oder alle (wenn nichts übergeben wird).

Es gibt mehrere vordefinierte Parameter (die ebenfalls gesetzt werden können), die speziellen Einfluss auf den Dispatch-Prozess haben:

- useDefaultControllerAlways wird benutzt, um dem Dispatcher zu sagen, dass er, wenn er einen Fehler beim Dispatchen feststellt - also ein Modul / einen Controller / eine Aktionsmethode nicht findet, automatisch den Startseiten-Controller im Modul default benutzen soll. Standardmäßig ausgeschaltet.

  Siehe das Kapitel MVC Exceptions denen man begegnen kann für detailliertere Informationen über die Benutzung dieser Einstellung.

- disableOutputBuffering sagt dem Dispatcher, dass er keinen Ausgabepuffer benutzen soll, um die Ausgabe, die von den Action-Controllern generiert wird, abzufangen. Standardmäßig werden sämtliche Ausgaben abgefangen und im Antwort-Objekt gespeichert.

- Wenn noViewRenderer auf `TRUE` steht, wird der ViewRenderer abgeschaltet.

- noErrorHandler auf `TRUE` schaltet das ErrorHandler-Plugin ab.

## Erweitern des Front-Controllers

Um den Front-Controller zu erweitern, muss als Minimalanforderung auf jeden Fall die Methode `getInstance()` überschrieben werden:

    class My_Controller_Front extends Zend_Controller_Front
    {
        public static function getInstance()
        {
            if (null === self::$_instance) {
                self::$_instance = new self();
            }

            return self::$_instance;
        }
    }

Das Überschreiben der `getInstance()`-Methode sorgt dafür, dass folgende Aufrufe von `Zend_Controller_Front::getInstance()` eine Instanz der neuen Subklasse zurückgeben anstatt einer `Zend_Controller_Front`-Instanz -- das ist speziell für einige der alternativen Router und View-Helfer nützlich.

Typischerweise muss der Front-Controller nicht erweitert werden, es sei denn, es ist gewünscht, neue Funktionalität (wie zum Beispiel einen Plugin-Autoloader oder einen Weg, Action-Helper-Pfade anzugeben) hinzuzufügen. Einige Gelegenheiten, bei denen das Standard-Verhalten geändert werden könnte, wären zum Beispiel die Art, wie Controller geladen oder deren Pfade gespeichert werden, oder welcher Standard-Router und/oder Dispatcher benutzt werden.