Der RequestDispatcher
ist ein Front-Controller, der zusammen mit dem BeanContainer
den Kern von f9 bildet. Er bildet den Kern, weil alle Web-Requests hier ankommen und von hier aus weiter verteilt werden. Im Folgenden möchte ich den RequestDispatcher
näher beschreiben – als ersten Teil der Beschreibung des f9-Frameworks.
- 10 subjektive Kriterien für ein gutes PHP (micro-) Framework
- f9 – noch ein neues PHP-Micro-Framework
- Eine beispielhafte f9-Anwendungsarchitektur
- Der f9-RequestDispatcher
- Die f9-View-Klassen
- Ein erstes Mini-Beispiel mit f9
- Die f9-Datenbank-Klasse
- Sessions in f9
- Der f9-Dependency-Injection-Container
- Views und Request mit dem Bean-Container verbinden
Ein wichtiger Hinweis gleich vorweg: Der RequestDispatcher
ist entstanden auf der Basis
der EpiRoute-Klasse des Epiphany-Frameworks. Mittlerweile sind die Unterschiede recht groß, aber die Verwandtschaft ist nicht zu übersehen. Deshalb: Dank an Jaisen Mathai und Kevin Hornschemeier für die großartige Grundlage. Wer nach einem hervorragenden micro-Framework für php sucht, sollte sich Epiphany auf jeden Fall ansehen.
Und noch ein zweites: Den Code zum Artikel gibts unten zum Download.
Das Front-Controller-Pattern
Für alle, die nicht wissen, was ein Front-Controller ist und welche Rolle er in einer Web-Anwendung spielt, zunächst ein paar kurze Sätze zur Erläuterung.
Ein Front-Controller bekommt alle eingehenden Requests einer Web-Site zugeleitet. Als Dispatcher oder Verteiler analysiert er die URL und die Parameter und leitet die Requests auf der Grundlage dieser Analyse an einzelne Controller weiter. Die Zuordnung von Requests oder URLs zu Controllern geschieht über eine Reihe von Mustern oder Regeln.
Der Front-Controller ist also der zentrale Einstiegspunkt für die gesamte Kommunikation mit einer Web-Anwendung.
Die einzelnen Controller sind dann Funktionen oder Methoden, die den Request abarbeiten; z.B. indem sie Funktionen und Methoden einer Service-Ebene aufrufen oder gleich Datenbank-Abfragen etc. durchführen — was hier geschieht ist abhängig von der weiteren Architektur des Systems und gehört nicht mehr primär zur Controller-Ebene.
Wer mehr über Front-Controller erfahren möchte, muss im Netz nicht lange suchen. Nach wie vor eine der besten Quellen ist Martin Fowlers Buch zu Anwendungs-Architekturen:
Fowler, Martin (2003): Patterns of Enterprise Application Architecture. (Addison-Wesley)
Namespace
Als Teil des f9-Frameworks liegt die RequestDispatcher-Klasse im net\f9-Namespace. Will man sie benutzen, ist die entsprechende Klasse also zunächst per use
einzubinden:
use net\f9\RequestDispatcher;
Der RequestDispatcher
Wie beschrieben ist der RequestDispatcher
der Einstigespunkt für jede f9-Anwendung. Ohne Erweiterung oder Ableitung einer neuen Klasse kann er die eingehenden Requests an php-Funktionen und Klassen-Methoden verteilen. Durch Definition neuer Loader und Runner oder durch Ableitung neuer Klassen können einfach weitere Controller-Typen genutzt werden.
Umleitung auf den Dispatcher
Damit alle Requests auf den RequestDispatcher
umgeleitet werden, muss der Webserver entsprechend konfiguriert sein. Beim Apache geschieht dies über die .htaccess
-Datei.
RewriteEngine on RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)\?*$ /index.php?__route__=/$1 [L,QSA]
Ggf. muss hier noch der Pfad angepasst werden. Nimmt man aber die Regel in Zeile vier als Beispiel, würden alle Requests auf die Datei index.php
umgeleitet. In dieser Datei muss dann der RequestDispatcher
seine Arbeit tun — dazu später mehr.
Dispatching
Der RequestDispatcher
verteilt eingehende Requests an Controller und gibt weiter, was die Controller zurückgeben — egal, was es ist: Ein String, ein Objekt oder irgendetwas anderes. Der Dispatcher ist reiner Weichensteller; er sorgt dafür, dass Daten an die richtige Stelle gelangen, greift die Daten aber nicht an, d.h. er manipuliert die weiterzuleitenden Daten nicht.
Dabei wird wie folgt vorgegangen:
- Wenn der Rückgabe-Wert des Controllers ein String ist und mit ‚redirect:‘ beginnt, wird versucht, einen entsprechenden Redirect durchzuführen.
- Wenn kein View-Resolver definiert wurde, wird der Rückgabe-Wert des Controllers unverändert ausgegeben (per
echo
). - Wenn ein View-Resolver definiert wurde, wird der Rückgabe-Wert des Controllers dem View-Resolver übergeben — der View-Resolver muss dann selbst anhand dieses Datums einen passenden View finden. Findet der View-Resolver einen passenden View, wird dessen Ausgabe-Methode (
render()
) aufgerufen. Für diesen letzteren Fall sind Klassen vorgesehen, die zwischen Controllern, View-Resolvern etc. ausgetauscht werden können und die View-Namen und die anzuzeigenden Modell-Daten zusammenfassen (ModelAndView
).
View
, ViewResolver
sowie ModelAndView
sind weitere f9-Klassen; sie werden an anderer Stelle eingehend erklärt.
Die ini-Datei
Der RequestDispatcher verteilt die eingehenden Requests auf der Basis von Regeln, die in einer ini-Datei zentral definiert werden.
Die Werte für method
und path
sind für alle Controller-Typen zwingend. Alle weiteren Werte können variieren, je nachdem von welchem Typ der Controller ist. Die Angaben für Controller-Funktionen und Controller-Methoden werden im Folgenden beschrieben. Für andere Controller-Typen können beliebige weitere Werte hinzugefügt werden, vgl. dazu den Abschnitt über die Erweiterungsmöglichkeiten des RequestDispatchers.
Funktionen als Controller
Das folgende Beispiel zeigt einen exemplarischen Eintrag für eine Route in der ini-Datei, bei der php-Funktionen als Controller eingesetzt werden. GET-Requests der Form /pingopong
werden an die Funktion my_func()
weitergeleitet.
[example] method = GET path = "/pingopong" type = function function = my_func
Die Benennung des Abschnitts mit example
ist irrelevant und hat für die Funktion der Routen-Definition keine Bedeutung; sie muss nur eindeutig sein.
Zunächst wird mit method
angegeben, für welchen HTTP-Request-Typ die Definition gelten soll (hier: GET).
Der path
-Eintrag gibt die Route an, für die ein Handler definiert wird. Hier sind Reguläre Ausdrücke erlaubt; innerhalb eines Regulären Ausdrucks können mit Gruppierungen Teile der Route als Parameter für den Controller erfasst werden. Damit ist es möglich, einen Controller für verschiedene Routen zu nutzen (dazu hier mehr).
Schließlich geben die beiden folgenden Angaben den Controller an, an den die Requests weitergeleitet werden sollen. Im Beispiel ist dies eine Funktion mit dem Namen my_func
.
Objekt-Methoden als Controller
Neben der Weiterleitung an Funktionen ist beim RequestDispatcher
die Weiterleitung an Klassen-Methoden möglich. Dies muss wie folgt angegeben werden:
[example] method = GET path = "/pong" type = class class = net\f9\examples\PongController function = pong_method
Hier wird der GET-Request /pong
an die Methode pong_method
der Klasse net\f9\examples\PongController
weitergeleitet; wann immer ein /pong
-Request zum RequestDispatcher
gelangt, wird eine Instanz der Klasse PongController
erzeugt und deren Methode pong_method
aufgerufen.
Reguläre Ausdrücke, Gruppierungen und Controller-Parameter
Über Reguläre Ausdrücke in der Pfad-Angabe können verschiedene Requests auf den gleichen Controller umgeleitet werden und Teile der URL als Parameter an den Controller übergeben werden.
Mit folgender Pfad-Angabe würden alle Requests, die mit /user
beginnen, an den gleichen Controller weitergeleitet.
path = "/user/+"
In der Regel ist das, was auf /user
folgt, wichtig für die weitere Verarbeitung des Requests (es könnte hier z.B. ein User-Name oder eine User-ID sein.). Deshalb ist es möglich, Teile der Route über Regex-Gruppierungen festzuhalten und als Parameter an die Controller zu übergeben.
Controller-Parameter
Angenommen, es wäre eine User-ID (Integer), so würde folgende Pfad-Angabe zunächst einen Controller für alle Requests definieren, bei denen auf /user
ein Integer folgt, z.B /user/537849
.
path = "/user/?(\d+)"
Durch die Gruppierung wird zudem die ID an den Controller als Parameter weitergegeben. Die Controller-Funktion oder -Methode müsste folglich so aussehen:
function do_sth_with_user($id) { //... }
Das heißt: Alle in einem Regulären Ausdruck angegebenen Gruppen werden dem entsprechenden Controller als Parameter übergeben.
Zusätzlich bekommt die Controller-Methode den eigentlichen Request als letzten Parameter übergebenn.
Controller bubbling
Controller bubbling heißt, dass mehrere Controller für die gleiche Route definiert werden können. Die Controller werden der Reihe nach aufgerufen und ihre Rückgabe-Werte wie oben beschrieben behandelt.
Auf diese Weise lassen sich Controller verketten und sich wiederholende Aufgaben in spezialisierte Controller auslagern. Genutzt werden kann dies zum Beispiel für Debugging-Zwecke oder ein sehr einfaches Logging.
Sind mehrere Controller für eine Route definiert, werden die Controller aufgerufen, bis der erste true
zurückgibt. In diesem Fall wird die Kette unterbrochen bzw. beendet und der Request gilt als abgearbeitet.
Das Prinzip das Bubbling ist bekannt vom Event-Bubbling (z.B. in JavaScript), wo für ein Event mehrere Handler definiert werden können und wie beim Controller-Bubbling die Aufruf-Kette durch den Rückgabe-Wert eines Handlers beendet werden kann.
Einfache Bespiele für Controller-Bubbling finden sich in den Beispiel-Anwendungen sowohl für Controller mit Funktionen als auch für Controller mit Klassen.
Loader und Runner – den RequestDispatcher erweitern
Schon der einfache Request-Dispatcher kann mit zwei Arten von Controllern umgehen: Funktionen und Objekt-Methoden. Der Request-Dispatcher kann zudem leicht um weitere Controller-Typen erweitert werden, weil für neue Typen Loader und Runner abgegeben werden können.
Die Aufgabe des Loaders ist es, die Angaben der ini-Datei zu analysieren und daraus die Informationen zusamenzubauen, die der Runner benötigt, wenn er einen Request abarbeitet. Einfacher – aber auch nicht ganz korrekt – könnte man sagen, dass der Loader den Controller lädt und der Runner ihn im Bedarfsfalle aufruft.
Loader
Ein neuer Loader wird über die Methode addLoader($name, $func)
dem RequestDispatcher hinzugefügt. Dabei ist der erste Parameter der Name des neuen Loaders, der zweite Parameter eine Funktion, der die Daten eines Abschnitts der ini-Datei als assoziatives Array übergeben werden. Auf der Basis dieser Daten registriert die übergebene Funktion einen Handler für den in der ini-Datei angegebenen Request-Typ (GET, POST etc.) und für die dort angegeben Route. Benötigt ein spezieller Loader mehr Daten als für die beiden Basis-Loader des RequestDispatchers vorgesehen, können sie in der ini-Datei einfach hinzugefügt werden.
Das folgende Beispiel zeigt den Loader für php-Funktionen:
addLoader('function', function($route) { if ((isset($route['type']) && $route['type']==='function') && isset($route['function'])) { $method = strtolower($route['method']); RequestDispatcher::getInstance()->$method($route['path'], $route['function']); } });
In Zeile sechs des Beispiels findet das eigentlich interessante statt. Hier wird — je nach http-Methode — eine der RequestDispatcher
-Methoden get($route, $callback)
, post($route, $callback)
, put($route, $callback)
oder delete($route, $callback)
aufgerufen. Das heißt: Es wird für die jeweilige http-Methoden für eine gegebene Route ein Controller registriert.
Runner
Ist der Controller registriert, d.h. eine Funktion, muss angegeben werden, was passieren soll, wenn ein Controller tatsächlich benötigt wird. Für den Fall einer Funktion als Controller heißt das: Die Funktion muss mit den entsprechenden Argumenten aufgerufen werden.
Ähnlich wie beim Loader wird auch hier eine Funktion registriert, die diesen Job übernimmt. In unserem Beispiel-Falle also ein Funktion, die die Controller-Funktion aufruft:
addRunner('function', function($def, $arguments) { if (is_string($def['callback']) && function_exists($def['callback'])) { return call_user_func_array($def['callback'], $arguments); } return null; });
Damit sind Loader und Runner für Funktionen als Controller definiert. Der BeanAwareRequestDispatcher
ist ein Request-Dispatcher, der den RequestDispatcher
um einen weiteren Controller-Typ erweitert: Um Methoden von Klassen bzw. Objekten, die dem f9-Bean-Container ‚entnommen‘ werden. Auch diese Erweiterung geschieht über die Registrierung eines je neuen Loaders und Runners. In der ini-Datei werden diese über den Typ bean
angegeben.
Beispiel
Das einfache RequestDispatcher-Beipiel zeigt den grundlegenden Einsatz des RequestDispatcher
s.
Wie beschrieben sorgt die .htaccess
-Datei dafür, dass alle Requests auf die Datei index.php
umgeleitet werden. (Die Datei könnte natürlich auch anders heißen.)
In dieser Datei wird nichts anderes gemacht, als mit
RequestDispatcher::getInstance()->dispatch();
den eingegangenen Request an den Dispatcher weiterzuleiten, damit er den passenden Controller ermittelt und den Request dorthin weiterleitet.
Zuvor muss jedoch die ini-Datei mit den Routen-Definitionen gelesen werden:
RequestDispatcher::getInstance()->load('routes.ini');
In der ini-Datei werden zwei Routen definiert; der Einfachheit halber soll aber für beide Routen die gleiche Funktion als Controller benutzt werden:
[hello] method = GET path = "/hallihallo" type = function function = hello [tach] method = GET path = "/tach" type = function function = hello
Weitere Beispiele (u.a. zum Controller-Bubbling) finden sich in den Downloads.
Downloads
Der RequestDispatcher
und die Beispiele können jeweils einzeln als Archiv runtergeladen werden. Das komplette f9-Framework habe ich noch nicht gang fertig — bis dahin müssen die einzelnen Archive ausreichen.
Zunächst der RequestDispatcher
selbst:
[download id=“1″]
Das einfache, oben beschriebene Beispiel findet sich hier:
[download id=“2″]
Schließlich zwei Beispiele für das Controller-Bubbling.
Zunächst Controller-Bubbling mit Methoden als Controllern:
[download id=“3″]
Und als zweites Controller-Bubbling mit Funktionen als Controllern:
[download id=“4″]
Das komplette f9-Framework mit allen Klassen und Beispielen:
[download id=“12″]
Schluss
Ein Request-Dispatcher ist immer ein guter Ausgangspunkt (im wahrsten Sinne des Wortes) für eine Web-Anwendung. Ob der hier vorgestellte Dispatcher das auch ist, könnt Ihr selbst entscheiden. Für das f9-Framework stellt er jedenfalls eine Kern-Komponente dar; zu den anderen Komponenten demnächst mehr.