Documentation

Der Standard Router - Zend_Controller

Der Standard Router

Einführung

Zend_Controller_Router_Rewrite ist der Standard Router des Frameworks. Routing ist der Prozess der Übernahme und Zerteilung einer URI (dem Teil der URI der nach der Basis URL kommt), um zu ermitteln, welches Modul, welcher Controller und welche Aktion des Controllers die Anfrage erhalten soll. Die Definition des Moduls, des Controllers, der Aktion sowie weiterer Parameter wird in einem Objekt mit Namen Zend_Controller_Dispatcher_Token gekapselt, das dann vom Zend_Controller_Dispatcher_Standard verarbeitet wird. Das Routing geschieht nur einmal: wenn zu Beginn die Anfrage erhalten wird und bevor der erste Controller aufgerufen wird.

Zend_Controller_Router_Rewrite wurde entwickelt, um mit reinen PHP Strukturen eine mod_rewrite ähnliche Funktionalität zu erlauben. Es richtet sich sehr frei nach dem Ruby on Rails Routing und benötigt kein tieferes Wissen über URL Weiterleitung des Webservers. Es wurde entwickelt, um mit einer einzigen mod_rewrite Regel zu arbeiten.

  1. RewriteEngine on
  2. RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php

oder (bevorzugt):

  1. RewriteEngine On
  2. RewriteCond %{REQUEST_FILENAME} -s [OR]
  3. RewriteCond %{REQUEST_FILENAME} -l [OR]
  4. RewriteCond %{REQUEST_FILENAME} -d
  5. RewriteRule ^.*$ - [NC,L]
  6. RewriteRule ^.*$ index.php [NC,L]

Der Rewrite Router kann auch mit dem IIS Webserver verwendet werden (Versionen <= 7.0), wenn » Isapi_Rewrite als Isapi Erweiterung installiert wurde und folgende Umschreibungsregel verwendet wird:

  1. RewriteRule ^[\w/\%]*(?:\.(?!(?:js|ico|gif|jpg|png|css|html)$)[\w\%]*$)? /index.php [I]

Note: IIS Isapi_Rewrite
Bei Verwendung von IIS, wird $_SERVER['REQUEST_URI'] entweder nicht vorhanden oder auf einen leeren String gesetzt sein. In diesem Fall wird Zend_Controller_Request_Http versuchen, den durch die Isapi_Rewrite Erweiterung gesetzten Wert $_SERVER['HTTP_X_REWRITE_URL'] zu verwenden.

IIS 7.0 führt ein natives URL Rewriting Modul ein, und kann wie folgt konfiguriert werden:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <configuration>
  3.      <system.webServer>
  4.          <rewrite>
  5.              <rules>
  6.                  <rule name="Imported Rule 1" stopProcessing="true">
  7.                      <match url="^.*$" />
  8.                      <conditions logicalGrouping="MatchAny">
  9.                          <add input="{REQUEST_FILENAME}"
  10.                              matchType="IsFile" pattern=""
  11.                              ignoreCase="false" />
  12.                          <add input="{REQUEST_FILENAME}"
  13.                              matchType="IsDirectory"
  14.                              pattern="" ignoreCase="false" />
  15.                      </conditions>
  16.                      <action type="None" />
  17.                  </rule>
  18.                  <rule name="Imported Rule 2" stopProcessing="true">
  19.                      <match url="^.*$" />
  20.                      <action type="Rewrite" url="index.php" />
  21.                  </rule>
  22.              </rules>
  23.          </rewrite>
  24.      </system.webServer>
  25. </configuration>

Bei der Verwendung von Lighttpd, ist folgende Umschreibungsregel gültig:

  1. url.rewrite-once = (
  2.     ".*\?(.*)$" => "/index.php?$1",
  3.     ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
  4.     "" => "/index.php"
  5. )

Einen Router verwenden

Um den Rewrite Router richtig zu verwenden, muß er instanziiert, einige benutzerdefinierte Routen hinzufügt und in den Controller einbunden werden. Der folgende Code veranschaulicht die Vorgehensweise:

  1. // Einen Router erstellen
  2.  
  3. $router = $ctrl->getRouter(); // gibt standardmäßig einen Rewrite Router zurück
  4. $router->addRoute(
  5.     'user',
  6.     new Zend_Controller_Router_Route('user/:username',
  7.                                      array('controller' => 'user',
  8.                                            'action' => 'info'))
  9. );

Grundsätzliche Rewrite Router Operationen

Das Herz des RewriteRouters ist die Definition von Benutzerdefinierten Routen. Routen werden durch aufruf der addRoute Methode des RewriteRouters hinzugefügt und übergeben eine neue Instanz einer Klasse die Zend_Controller_Router_Route_Interface implementiert. Z.B.:

  1. $router->addRoute('user',
  2.                   new Zend_Controller_Router_Route('user/:username'));

Der Rewrite Router kommt mit sechs Basistypen von Routen (eine von denen ist speziell): is special):

Routen können unzählige Male verwendet werden um eine Kette oder benutzerdefinierte Routing Schemas von Anwendungen zu erstellen. Es kann jede beliebige Anzahl von Routen in jeder beliebigen Konfiguration verwendet werden, mit Ausnahme der Modul Route, welche nur einmal verwendet werden sollte, und möglicherweise die am meisten standardmäßige Route ist (z.B., als ein Standard). Jede Route wird später detailiert beschrieben.

Der erste Parameter für addRoute ist der Name der Route. Er wird als Handle verwendet um die Route außerhalb des Routers zu erhalten (z.B. für den Zweck der URL Erzeugung). Der zweite Parameter ist die Route selbst.

Note: Die gewöhnlichste Verwendung des Namens der Route ist gegeben durch die Zwecke des Zend_View Url Helfers:

  1. <a href=
  2. "<?php echo $this->url(array('username' => 'martel'), 'user') ?>">Martel</a>
Was zu folgender href führt: user/martel.

Routen ist ein einfacher Prozess des Durchlaufens aller vorhandenen Routen und Vergleichens deren Definitionen mit der aktuellen Anfrage URI. Wenn ein positiver Vergleich gefunden wird, werden variable Werte von der Instanz des Routers zurückgegeben, und werden für die spätere Verwendung im Dispatcher in das Zend_Controller_Request Objekt iniziiert, sowie in von Benutzern erstellten Controllern. Bei einem negativen Ergebnis des Vergleiches, wird die nächste Route in der Kette geprüft.

Wenn man herausfinden will welche Route gepasst hat, kann man die getCurrentRouteName() Methode verwenden, die den Identifikator zurückgibt der verwendet wurde als die Route im Router registriert wurde. Wenn man das aktuelle Route Objekt benötigt, kann getCurrentRoute() verwendet werden.

Note: Umgekehrter Vergleich
Routen werden in umgekehrter Reihenfolge verglichen. Deswegen muß sichergestellt werden das die generellen Routen zuerst definiert werden.

Note: Zurückgegebene Werte
Werte die vom Routen zurückgegeben werden kommen von URL Parametern oder Benutzerdefinierten Router Standards. Diese Variablen sind später durch die Zend_Controller_Request::getParam() oder Zend_Controller_Action::_getParam()Methoden verwendbar.

Es gibt drei spezielle Variablen welche in den Routen verwendet werden können - 'module', 'controller' und 'action'. Diese speziellen Variablen werden durch Zend_Controller_Dispatcher verwendet um einen Controller und die Aktion zu funden zu der verwiesen wird.

Note: Spezielle Variablen
Die Namen dieser speziellen Variablen kann unterschiedlich sein wenn entschieden wird die Standards in Zend_Controller_Request_Http mithilfe der setControllerKey() und setActionKey() Methode zu Ändern.

Standard Routen

Zend_Controller_Router_Rewrite kommt mit einer Standard Route vorkonfiguriert, welche URIs im Sinn von controller/action entspricht. Zusätzlich kann ein Modul Name als erstes Pfad Element definiert werden, welches URIs in der Form von module/controller/action erlaubt. Letztendlich wird es auch allen zusätzlichen Parametern entsprechen die der URI standardmäßig hinzugefügt wurden - controller/action/var1/value1/var2/value2.

Einige Beispiele wie solche Routen verglichen werden:

  1. // Folgende Annahme:
  2. $ctrl->setControllerDirectory(
  3.     array(
  4.         'default' => '/path/to/default/controllers',
  5.         'news'    => '/path/to/news/controllers',
  6.         'blog'    => '/path/to/blog/controllers'
  7.     )
  8. );
  9.  
  10. Nur Modul:
  11. http://example/news
  12.     module == news
  13.  
  14. Ungültiges Modul, geht an den Controller Namen:
  15. http://example/foo
  16.     controller == foo
  17.  
  18. Modul + Controller:
  19. http://example/blog/archive
  20.     module     == blog
  21.     controller == archive
  22.  
  23. Modul + Controller + Aktion:
  24. http://example/blog/archive/list
  25.     module     == blog
  26.     controller == archive
  27.     action     == list
  28.  
  29. Modul + Controller + Aktion + Parameter:
  30. http://example/blog/archive/list/sort/alpha/date/desc
  31.     module     == blog
  32.     controller == archive
  33.     action     == list
  34.     sort       == alpha
  35.     date       == desc

Die Standardroute ist einfach ein Zend_Controller_Router_Route_Module Objekt welches unter dem Namen (Index) 'default' im RewriteRouter gespeichert ist. Es wird mehr oder weniger wie folgt erstellt:

  1. $compat = new Zend_Controller_Router_Route_Module(array(),
  2.                                                   $dispatcher,
  3.                                                   $request);
  4. $this->addRoute('default', $compat);

Wenn diese spezielle Standard Route im eigenen Routing Schema nicht gewünscht ist, kann Sie durch Erstellung einer eigenen 'default' Route überschrieben werden (z.B. durch Speichern unter dem Namen 'default') oder dem kompletten Entfernen durch verwenden von removeDefaultRoutes():

  1. // Löschen aller Standard Routen
  2. $router->removeDefaultRoutes();

Basis URL und Unterverzeichnisse

Der Rewrite Router kann in Unterverzeichnissen verwendet werden (z.B. http://domain.com/user/application-root/) und in diesem Fall sollte die Basis URL der Anwendung (/user/application-root) automatisch durch Zend_Controller_Request_Http erkannt und auch verwendet werden.

Sollte die Basis URL nicht richtig erkannt werden kann diese mit eigenen Basispfad überschrieben werden durch Verwendung von Zend_Controller_Request_Http und Auruf der setBaseUrl() Methode (siehe Basis URL und Unterverzeichnisse):

  1. $request->setBaseUrl('/~user/application-root/');

Globale Parameter

Man kann in einem Router globale Parameter setzen die der Route automatisch zur Verfügung stehen wenn Sie durch setGlobalParam() eingefügt werden. Wenn ein globaler Parameter gesetzt ist, aber auch direkt an die Assemble Methode gegeben wird, überschreibt der Benutzer-Parameter den Globalen-Parameter. Globale Parameter können auf folgendem Weg gesetzt werden:

  1. $router->setGlobalParam('lang', 'en');

Router Typen

Zend_Controller_Router_Route

Zend_Controller_Router_Route ist die standardmäßige Framework Route. Sie kombiniert einfache Verwendung mit einer flexiblen Routendefinition. Jede Route besteht primär aus URL Übereinstimmungen (von statischen und dynamischen Teilen (Variablen)) und kann mit Standardwerten initialisiert werden wie auch mit variablen Notwendigkeiten.

Angenommen unsere fiktive Anwendung benötigt eine informelle Seite über den Seitenauthor. Es soll möglich sein mit dem Browser auf http://domain.com/author/martel zu verweisen um die Informationen über diesen "martel" Typ zu sehen. Und die Route für so eine Funktionalität würde so aussehen:

  1. $route = new Zend_Controller_Router_Route(
  2.     'author/:username',
  3.     array(
  4.         'controller' => 'profile',
  5.         'action'     => 'userinfo'
  6.     )
  7. );
  8.  
  9. $router->addRoute('user', $route);

Der ersten Parameter im Konstruktor von Zend_Controller_Router_Route ist eine Routendefinition die einer URL entspricht. Routendefinitionen bestehen aus statischen und dynamischen Teilen die durch einen Schrägstrich ('/') seperiert sind. Statische Teile sind nur einfacher Text: author. Dynamische Teile, Variablen genannt, werden durch einen vorangestellten Doppelpunkt, zum variablen Namen, markiert: :username.

Note: Zeichen verwenden
Die aktuelle Implementation erlaubt die Verwendung von allen Zeichen (außer einem Schrägstrich) als variablen Identifikator, aber es wird dringend empfohlen das nur Zeichen verwendet werden die auch für PHP Veriablen Identifikatoren gültig sind. Zukünftige Implementationen können dieses Verhlaten ändern, was zu versteckten Bugs im eigenen Code führen würde.

Diese Beispielroute wird verglichen wenn der Browser auf http://domain.com/author/martel zeigt. In diesem Fall werden alle seine Variablen dem Zend_Controller_Request Objekt injiziiert und es kann im ProfileController darauf zugegriffen werden. Variablen die von diesem Beispiel zurückgegeben werden können als Array mit den folgenden Schlüssel- und Wertepaaren repräsentiert werden:

  1. $values = array(
  2.     'username'   => 'martel',
  3.     'controller' => 'profile',
  4.     'action'     => 'userinfo'
  5. );

Später sollte Zend_Controller_Dispatcher_Standard die userinfoAction() Methode der eigenen ProfileController Klasse aufrufen (im Standardmodul) basierend auf diesen Werten. Dort ist es möglich alle Variablen durch die Zend_Controller_Action::_getParam() oder Zend_Controller_Request::getParam() Methoden zuzugreifen:

  1. public function userinfoAction()
  2. {
  3.     $request = $this->getRequest();
  4.     $username = $request->getParam('username');
  5.  
  6.     $username = $this->_getParam('username');
  7. }

Eine Routendefinition kann ein weiteres spezielles Zeichen enthalten - eine Wildcard - dargestellt durch ein '*' Symbol. Es wird verwendet um Parameter genauso wie im standard Modulrouter zu erhalten (var => Wertepaare definiert in der URI). Die folgende Route imitiert mehr oder weniger das Verhalten des Modulrouters:

  1. $route = new Zend_Controller_Router_Route(
  2.     ':module/:controller/:action/*',
  3.     array('module' => 'default')
  4. );
  5. $router->addRoute('default', $route);

Variable Standards

Jede Variable im Router kann einen Standardwert haben und das ist für was der zweite Parameter des Konstruktors von Zend_Controller_Router_Route verwendet wird. Dieser Parameter ist ein Array mit Schlüsseln die Variablennamen repräsentieren und mit Werten als gewünschte Standards:

  1. $route = new Zend_Controller_Router_Route(
  2.     'archive/:year',
  3.     array('year' => 2006)
  4. );
  5. $router->addRoute('archive', $route);

Die obige Route entspricht URLs wie http://domain.com/archive/2005 und http://example.com/archive. Im späteren Fall wird die Variable year einen initialen Standardwert von 2006 haben.

Dieses Beispiel resultiert darin das eine year Variable in das Anfrage Objekt injiziiert wird. Da keine Routinginformation vorhanden ist (es sind keine Controller und Aktionsparameter definiert), wird die Anwendung zum Standardcontroller und der Aktionsmethode (welche beide in Zend_Controller_Dispatcher_Abstract definiert sind) weitergeleitet. Um es verwendbarer zu machen muß ein gültiger Controller und eine gültige aktion als Standard für die Route angegeben werden:

  1. $route = new Zend_Controller_Router_Route(
  2.     'archive/:year',
  3.     array(
  4.         'year'       => 2006,
  5.         'controller' => 'archive',
  6.         'action'     => 'show'
  7.     )
  8. );
  9. $router->addRoute('archive', $route);

Diese Route führt dazu das an die Methode showAction() der Klasse ArchiveController weitergeleitet wird.

Variable Anforderungen

Man kann einen dritten Parameter dem Zend_Controller_Router_Route Konstruktor hinzufügen wo variable Anforderungen gesetzt werden können. Diese werden als Teil eines regulären Ausdrucks definiert:

  1. $route = new Zend_Controller_Router_Route(
  2.     'archive/:year',
  3.     array(
  4.         'year'       => 2006,
  5.         'controller' => 'archive',
  6.         'action'     => 'show'
  7.     ),
  8.     array('year' => '\d+')
  9. );
  10. $router->addRoute('archive', $route);

Mit einer Route die wie oben definiert ist, wird das Routing nur dann stattfinden wenn die year Variable nummerische Daten enthält, z.B. http://domain.com/archive/2345. Eine URL wie http://example.com/archive/test wird nicht zugeordnet und die Kontrolle wird stattdessen an die nächste Route in der Kette übertragen.

Übersetzte Segmente

Die Standardroute unterstützt übersetzte Segmente. Um dieses Feature zu verwenden muß zumindest ein Übersetzer (eine Instanz von Zend_Translate) auf einem der folgenden Wege definiert werden:

  • In die Registry mit dem Schlüssel Zend_Translate geben.

  • Über die statische Methode Zend_Controller_Router_Route::setDefaultTranslator() setzen.

  • Als vierten Parameter im Constructor übergeben.

Standardmäßig wird das Gebietsschema verwendet das in der Instanz von Zend_Translate verwendet wird. Um es zu überschreiben, kann es (als Instanz von Zend_Locale oder einem Gebietsschema-String) auf einem der folgenden Wege gesetzt werden:

  • In die Registry mit dem Schlüssel Zend_Locale geben.

  • Über die statische Methode Zend_Controller_Router_Route::setDefaultLocale() setzen.

  • Als fünften Parameter im Constructor übergeben.

  • Als @locale Parameter der assemble Methode übergeben.

Übersetzte Segmente werden in zwei Teile getrennt. Ein fixes Segment dem ein einzelnes @-Zeichen vorangestellt wird, der anhand des aktuellen Gebietsschemas übersetzt wird und auf der Position des Parameters eingefügt wird. Dynamischen Segmenten wird ein :@ vorangestellt. Beim Zusammenbauen, wird der gegebene Parameter übersetzt und an der Position des Parameters eingefügt. Bei der Überprüfung, wird der übersetzte Parameter von der URL wieder in die Nachrichten ID umgewandelt.

Note: Nachrichten IDs und eigene Sprachdateien
Normalerweise werden Nachrichten IDs die man in einer seiner Routen verwenden will, bereits in einem View Skript oder irgendwo anders verwendet. Um die komplette Kontrolle über sichere URLs zu haben, sollte man eine eigene Sprachdatei für die Nachrichten haben die in einer Route verwendet werden.

Nachfolgend ist die einfachste Verwendung gezeigt um eine Standardroute für übersetzte Segmente zu Verwenden:

  1. // Den Übersetzer vorbereiten
  2. $translator = new Zend_Translate(
  3.     array(
  4.         'adapter' => 'array',
  5.         'content' => array(),
  6.         'locale'  => 'en'
  7.     )
  8. );
  9. $translator->addTranslation(
  10.     array(
  11.         'content' =>
  12.             array(
  13.                 'archive' => 'archiv',
  14.                 'year'    => 'jahr',
  15.                 'month'   => 'monat',
  16.                 'index'   => 'uebersicht'
  17.             ),
  18.         'locale' => 'de'
  19.     )
  20. );
  21.  
  22. // Das aktuelle Gebietsschema für den Übersetzer setzen
  23. $translator->setLocale('en');
  24.  
  25. // Als Standard-Übersetzer für Routen setzen
  26. Zend_Controller_Router_Route::setDefaultTranslator($translator);

Dieses Beispiel zeigt die Verwendung von statischen Segmenten:

  1. // Die Route erstellen
  2. $route = new Zend_Controller_Router_Route(
  3.     '@archive',
  4.     array(
  5.         'controller' => 'archive',
  6.         'action'     => 'index'
  7.     )
  8. );
  9. $router->addRoute('archive', $route);
  10.  
  11. // Die URL im Standard-Gebietsschema zusammenbauen: archive
  12. $route->assemble(array());
  13.  
  14. // Die URL in Deutsch zusammenbauen: archiv
  15. $route->assemble(array());

Man kann dynamische Segmente verwenden um eine Modul-Route, so wie die übersetzte Version, zu erstellen:

  1. // Die Route erstellen
  2. $route = new Zend_Controller_Router_Route(
  3.     ':@controller/:@action/*',
  4.     array(
  5.         'controller' => 'index',
  6.         'action'     => 'index'
  7.     )
  8. );
  9. $router->addRoute('archive', $route);
  10.  
  11. // Die URL im Standard-Gebietsschema zusammenbauen: archive/index/foo/bar
  12. $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
  13.  
  14. // Die URL in Deutsch zusammenbauen: archiv/uebersicht/foo/bar
  15. $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));

Man kann auch statische und dynamische Segmente mischen:

  1. // Die Route erstellen
  2. +$route = new Zend_Controller_Router_Route(
  3.     '@archive/:@mode/:value',
  4.     array(
  5.         'mode'       => 'year'
  6.         'value'      => 2005,
  7.         'controller' => 'archive',
  8.         'action'     => 'show'
  9.     ),
  10.     array('mode'  => '(month|year)'
  11.           'value' => '\d+')
  12. );
  13. $router->addRoute('archive', $route);
  14.  
  15. // Die URL im Standard-Gebietsschema zusammenbauen: archive/month/5
  16. $route->assemble(array('mode' => 'month', 'value' => '5'));
  17.  
  18. // Die URL in Deutsch zusammenbauen: archiv/monat/5
  19. $route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));

Zend_Controller_Router_Route_Static

Die oben angeführten Beispiele verwenden alle dynamische Routen -- Routen die einem Pattern entsprechen. Trotzdem wird manchmal eine spezielle Route in Stein gegossen, und das Starten der Regular Expression Maschine wäre ein Overkill. Die Lösung zu dieser Situation ist die Verwendung von statischen Routen:

  1. $route = new Zend_Controller_Router_Route_Static(
  2.     'login',
  3.     array('controller' => 'auth', 'action' => 'login')
  4. );
  5. $router->addRoute('login', $route);

Die obige Route passt zu einer URL von http://domain.com/login, und leitet weiter zu AuthController::loginAction().

Note: Warnung: Statische Routen müssen vernüftige Standards enthalten
Da eine statische Route keinen Teil der URL an das Requestobjekt als Parameter übergibt, muss man alle Parameter die für das Bearbeiten eines Requests notwendig sind als Standards an die Route übergeben. Das unterdrücken der Standardwerte von "controller" oder "action" kann zu unerwarteten Ergebnissen führen, und wird dazu führen das der Request nicht bearbeitet werden kann.
Als Daumenregel sollte man immer jeden der folgenden Standardwerte anbieten:

  • controller

  • action

  • module (if not default)

Optional kann auch der "useDefaultControllerAlways" Parameter an den Frontcontroller während des Bootstrappings übergeben werden:
  1. $front->setParam('useDefaultControllerAlways', true);
Trotzdem ist das als Workaround anzusehen; es ist immer besser vernünftige Standards explizit zu definieren.

Zend_Controller_Router_Route_Regex

Zusätzlich zu den standard statischen Routetypen, ist ein Regular Expression Routetyp vorhanden. Diese Route bietet mehr Power und Flexibilität als die anderen, aber auf leichten Kosten von Komplexität. Wärend der selben Zeit, sollte Sie schneller als die Standardroute sein.

Wie die Standardroute, muß diese Route mit einer Routendefinition und einigen Standardwerten initialisiert werden. Lasst uns eine Archivroute als Beispiel erstellen, ähnlich der zuletzt definierten, nur das dieses Mal die Regex Route verwendet wird:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'archive/(\d+)',
  3.     array(
  4.         'controller' => 'archive',
  5.         'action'     => 'show'
  6.     )
  7. );
  8. $router->addRoute('archive', $route);

Jedes definierte Regex Subpattern wird in das Anfrageobjekt injiziiert. Mit dem obigen Beispiel, nachdem http://domain.com/archive/2006 erfolgreich geprüft wurde, kann das resultierende Wertearray so aussehen:

  1. $values = array(
  2.     1            => '2006',
  3.     'controller' => 'archive',
  4.     'action'     => 'show'
  5. );

Note: Führende und folgende Schrägstriche werden von der URL im Router vor dem Vergleich entfernt. Als Ergebnis, wird ein Vergleich der URL http://domain.com/foo/bar/, ein Regex von foo/bar inkludieren, aber nicht /foo/bar.

Note: Zeilenbeginn und Endanker (normalerweise '^' und '$') werden automatisch allen Ausdrücken vor- und nachgesetzt. Deswegen sollten Sie nicht in den Regular Expressions verwendet werden, und der komplette String sollte entsprechen.

Note: Diese Routeklasse verwendet das '#' Zeichen als Begrenzer. Das bedeutet das ein Hashzeichen ('#') kommentiert werden muß aber keine Schrägstriche ('/') in der Routendefinition. Da das '#' Zeichen (Anker genannt) selben an einen Webserver übergeben wird, wird man dieses Zeichen selten in der eigenen regex verwenden.

Die Inhalte von definierten Subpattern können auf dem üblichen Weg bekommen werden:

  1. public function showAction()
  2. {
  3.     $request = $this->getRequest();
  4.     $year    = $request->getParam(1); // $year = '2006';
  5. }

Note: Beachte das der Schlüssel ein Integer ist (1) anstatt ein String ('1').

Diese Route wird jetzt noch nicht exakt gleich wie Ihr Gegenspieler, die Standardroute, arbeiten da der Standard für 'year' noch nicht gesetzt ist. Und was jetzt noch nicht offensichtlich ist, ist das wir ein Problem mit endenden Schrägstrichen haben, selbst wenn wir einen Standard für das Jahr definieren und das Subpattern optional machen. Die Lösung ist, den ganzen year Teil optional zu nachen zusammen mit dem Schrägstrich, aber nur den nummerischen Teil zu holen:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'archive(?:/(\d+))?',
  3.     array(
  4.         1            => '2006',
  5.         'controller' => 'archive',
  6.         'action'     => 'show'
  7.     )
  8. );
  9. $router->addRoute('archive', $route);

Jetzt betrachten wir das Problem das möglicherweise schon selbst gefunden wurde. Die Verwendung von Integer basierten Schlüsseln für Parameter ist keine einfach zu handhabende Lösung und kann, während einer langen Laufzeit, potentiell problematisch sein. Hier kommt der dritte Parameter ins Spiel. Dieser Parameter ist ein assoziatives Array das einer Karte von Regex Subpatterns zu Parametern benannten Schlüsseln entspricht. Betrachten wir ein einfacheres Beispiel:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'archive/(\d+)',
  3.     array(
  4.         'controller' => 'archive',
  5.         'action' => 'show'
  6.     ),
  7.     array(
  8.         1 => 'year'
  9.     )
  10. );
  11. $router->addRoute('archive', $route);

Als Ergebnis werden die folgenden Werte in die Anfrage injiziiert:

  1. $values = array(
  2.     'year'       => '2006',
  3.     'controller' => 'archive',
  4.     'action'     => 'show'
  5. );

Die Karte kann in jede Richtung definiert werden damit Sie in jeder Umgebung funktioniert. Schlüssel können Variablennamen oder Indezes von Subpattern enthalten:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'archive/(\d+)',
  3.     array( ... ),
  4.     array(1 => 'year')
  5. );
  6.  
  7. // ODER
  8.  
  9. $route = new Zend_Controller_Router_Route_Regex(
  10.     'archive/(\d+)',
  11.     array( ... ),
  12.     array('year' => 1)
  13. );

Note: Schlüssel von Subpattern müssen durch Integer repräsentiert werden.

Es gilt zu beachten das der nummerische Index in den Anfragewerten jetzt weg ist und eine benannte Variable statt Ihm angezeigt wird. Natürlich können nummerische und benannte Variablen gemischt werden wenn das gewünscht ist:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'archive/(\d+)/page/(\d+)',
  3.     array( ... ),
  4.     array('year' => 1)
  5. );

Das führt zu gemischten Werten die in der Anfrage vorhanden sind. Als Beispiel, wird die URL http://domain.com/archive/2006/page/10 zu folgenden Werte führen:

  1. $values = array(
  2.     'year'       => '2006',
  3.     2            => 10,
  4.     'controller' => 'archive',
  5.     'action'     => 'show'
  6. );

Da Regex Patterns nicht einfach rückgängig zu machen sind, muß eine umgekehrte URL vorbereitet werden wenn ein URL Helfer verwendet werden soll oder sogar eine Herstellungsmethode dieser Klasse. Dieser umgekehrte Pfad wird durch einen String dargestellt der durch sprintf() durchsucht werden kann und als vierter Parameter definiert wird:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'archive/(\d+)',
  3.     array( ... ),
  4.     array('year' => 1),
  5.     'archive/%s'
  6. );

Da all das bereits etwas ist das durch die Bedeutung eines standardmäßigen Route Objektes möglich ist kommt natürlich die Frage aus worin der Vorteil einer regex Route besteht? Primär erlaubt Sie jeden Typ von URL zu beschreiben ohne irgendwelche Einschränkungen. Angenommen man hat einen Blog und will eine URL wie die folgende erstellen: http://domain.com/blog/archive/01-Using_the_Regex_Router.html, und muß das jetzt Pfad Element 01-Using_the_Regex_Router.html bearbeiten, in eine Artikel ID und eine Artikel Titel oder Beschreibung; das ist nicht möglich mit der Standardroute. Mit der Regex Route ist etwas wie die folgende Lösung möglich:

  1. $route = new Zend_Controller_Router_Route_Regex(
  2.     'blog/archive/(\d+)-(.+)\.html',
  3.     array(
  4.         'controller' => 'blog',
  5.         'action'     => 'view'
  6.     ),
  7.     array(
  8.         1 => 'id',
  9.         2 => 'description'
  10.     ),
  11.     'blog/archive/%d-%s.html'
  12. );
  13. $router->addRoute('blogArchive', $route);

Wie man sieht, fügt das ein enormes Potential von Flexibilität zur Stnadardroute hinzu.

Zend_Controller_Router_Route_Hostname

Zend_Controller_Router_Route_Hostname ist die Hostname Route des Frameworks. Sie arbeitet ähnlich wie die Standardrouten, aber Sie arbeitet an und mit dem Hostnamen der aufgerufenen URL statt mit dem Pfad.

Verwenden wir also ein Beispiel von der Standardroute und schauen wir uns an wie Sie auf einem Hostnamen basierenden Weg aussehen würde. Statt das der Benutzer über einen Pfad aufgerufen wird, wollen wir das der Benutzer http://martel.users.example.com aufrufen kann, um die Informationen über den Benutzer "martel" zu sehen:

  1. $hostnameRoute = new Zend_Controller_Router_Route_Hostname(
  2.     ':username.users.example.com',
  3.     array(
  4.         'controller' => 'profile',
  5.         'action'     => 'userinfo'
  6.     )
  7. );
  8.  
  9. $plainPathRoute = new Zend_Controller_Router_Route_Static('');
  10.  
  11. $router->addRoute('user', $hostnameRoute->chain($plainPathRoute);

Der erste Parameter in Konstruktor von Zend_Controller_Router_Route_Hostname ist eine Routerdefinition die zu einem Hostnamen passt. Routerdefinitionen bestehen aus statischen und dynamischen Teilen die durch ein Punkt ('.') Zeichen getrennt sind. Dynamische Teile, genannt Variablen, werden durch einen, dem Variablennamen vorangestellten Doppelpunkt, gekennzeichnet: :username. Statische Teile sind nur einfacher Text: user.

Hostnamerouten können verwendet werden wie sie sind, sollten es aber nie. Der Grund dahinter ist, das Hostnamerouten alleine jedem Pfad entsprechen würden. Was man also tun muß, ist eine Pfadroute an die Hostnameroute zu ketten. Das wird, wie im Beispiel, getan indem $hostnameRoute->chain($pathRoute); aufgerufen wird. Indem das getan wird, wird $hostnameRoute nicht geändert, aber eine neue Route (Zend_Controller_Router_Route_Chain), welche dann dem Router übergeben werden kann, wird zurückgegeben.

Zend_Controller_Router_Route_Chain

Zend_Controller_Router_Route_Chain ist eine Route die es erlaubt mehrere Routen miteinander zu verketten. Das erlaubt es Hostname-Routen und Pfad-Routen zu verketten, oder zum Beispiel mehrere Pfad-Routen. Verkettung kann entweder program-technisch oder mit einer Konfigurationsdatei durchgeführt werden.

Note: Priorität der Parameter
Wenn Routen wie die Hostnameroute und die Pfadroute zusammengekettet werden, haben die Parameter der Hostnameroute eine höhere Priorität als die Parameter der Pfadroute. Deshalb wird, wenn man im Hostnamen und in der Pfadroute einen Controller definiert, der Controller der Hostnameroute ausgewählt.

Wenn Programmtechnisch verkettet wird, gibt es zwei Wege das zu tun. Der erste besteht darin eine neue Instanz von Zend_Controller_Router_Route_Chain zu erstellen und dann die chain() Methode mehrere Male mit allen Routen aufzurufen die zusammen verkettet werden sollen. Der andere Weg besteht darin die erste Route zu nehmen, z.B. eine Hostname Route, und die chain() Methode mit der Route auf Ihr aufzurufen, die angehängt werden soll. Das verändert die Hostname Route nicht, gibt aber eine neue Instanz von Zend_Controller_Router_Route_Chain zurück, die dann beide Routen verkettet hat:

  1. // Erstellung zweier Routen
  2. $hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
  3. $pathRoute     = new Zend_Controller_Router_Route(...);
  4.  
  5. // Erster Weg, mit Verkettung über die Chain Route
  6. $chainedRoute = new Zend_Controller_Router_Route_Chain();
  7. $chainedRoute->chain($hostnameRoute)
  8.              ->chain($pathRoute);
  9.  
  10. // Zweiter Weg, direkt verketten
  11. $chainedRoute = $hostnameRoute->chain($pathRoute);

Wenn Routen miteinander verkettet werden, ist Ihr Trennzeichen ein Schrägstrich. Es kann Fälle geben in denen man ein anderes Trennzeichen verwenden will:

  1. // Zwei Routen erstellen
  2. $firstRoute  = new Zend_Controller_Router_Route('foo');
  3. $secondRoute = new Zend_Controller_Router_Route('bar');
  4.  
  5. // Sie mit einem anderen Trennzeichen miteinander verketten
  6. $chainedRoute = $firstRoute->chain($secondRoute, '-');
  7.  
  8. // Zusammenbauen der Route: "foo-bar"
  9. echo $chainedRoute->assemble();

Verkettete Routen über Zend_Config

Um Routen in einer Config Datei miteinander zu verketten gibt es zusätzliche Parameter für die Konfiguration von Ihnen. Der einfachere Weg ist die Verwendung des chains Parameters. Dieser ist einfach eine Liste von Routen, die mit der Eltern-Route verkettet werden. Weder die Eltern-, noch die Kind-Routen werden dem Router direkt hinzugefügt sondern nur die resultierende verkettete Route. Der Name der verketteten Route im Router ist standardmäßig der Name der Eltern-Route und der Name der Kind-Route verbunden mit einem Bindestrich (-). Eine einfache Konfiguration würde in XML wie folgt aussehen:

  1. <routes>
  2.     <www type="Zend_Controller_Router_Route_Hostname">
  3.         <route>www.example.com</route>
  4.         <chains>
  5.             <language type="Zend_Controller_Router_Route">
  6.                 <route>:language</route>
  7.                 <reqs language="[a-z]{2}">
  8.                 <chains>
  9.                     <index type="Zend_Controller_Router_Route_Static">
  10.                         <route></route>
  11.                         <defaults module="default" controller="index"
  12.                                   action="index" />
  13.                     </index>
  14.                     <imprint type="Zend_Controller_Router_Route_Static">
  15.                         <route>imprint</route>
  16.                         <defaults module="default" controller="index"
  17.                                   action="index" />
  18.                     </imprint>
  19.                 </chains>
  20.             </language>
  21.         </chains>
  22.     </www>
  23.     <users type="Zend_Controller_Router_Route_Hostname">
  24.         <route>users.example.com</route>
  25.         <chains>
  26.             <profile type="Zend_Controller_Router_Route">
  27.                 <route>:username</route>
  28.                 <defaults module="users" controller="profile" action="index" />
  29.             </profile>
  30.         </chains>
  31.     </users>
  32.     <misc type="Zend_Controller_Router_Route_Static">
  33.         <route>misc</route>
  34.     </misc>
  35. </routes>

Das führt zu den drei Routen www-language-index, www-language-imprint und users-language-profile die nur basierend auf dem Hostnamen und der Route misc passen, was wiederum mit jedem Hostnamen passt.

Der alternative Weg der Erstellung einer verketteten Route ist der über den chain Parameter, was wiederum nur mit dem Chain-Route Typ direkt verwendet werden kann, und auch im Root Level funktioniert:

  1. <routes>
  2.     <www type="Zend_Controller_Router_Route_Chain">
  3.         <route>www.example.com</route>
  4.     </www>
  5.     <language type="Zend_Controller_Router_Route">
  6.         <route>:language</route>
  7.         <reqs language="[a-z]{2}">
  8.     </language>
  9.     <index type="Zend_Controller_Router_Route_Static">
  10.         <route></route>
  11.         <defaults module="default" controller="index" action="index" />
  12.     </index>
  13.     <imprint type="Zend_Controller_Router_Route_Static">
  14.         <route>imprint</route>
  15.         <defaults module="default" controller="index" action="index" />
  16.     </imprint>
  17.  
  18.     <www-index type="Zend_Controller_Router_Route_Chain">
  19.         <chain>www, language, index</chain>
  20.     </www-index>
  21.     <www-imprint type="Zend_Controller_Router_Route_Chain">
  22.         <chain>www, language, imprint</chain>
  23.     </www-imprint>
  24. </routes>

Man kann auch den chain Parameter als Array übergeben statt die Routen mit einem Komma zu seperieren:

  1. <routes>
  2.     <www-index type="Zend_Controller_Router_Route_Chain">
  3.         <chain>www</chain>
  4.         <chain>language</chain>
  5.         <chain>index</chain>
  6.     </www-index>
  7.     <www-imprint type="Zend_Controller_Router_Route_Chain">
  8.         <chain>www</chain>
  9.         <chain>language</chain>
  10.         <chain>imprint</chain>
  11.     </www-imprint>
  12. </routes>

Wenn man Chain-Routen mit Zend_Config konfiguriert und will dass das Trennzeichen ein anderes als ein Unterstrich ist, dann muss man dises Trennzeichen separat spezifizieren:

  1. $config = new Zend_Config(array(
  2.     'chainName' => array(
  3.         'type'   => 'Zend_Controller_Router_Route_Static',
  4.         'route'  => 'foo',
  5.         'chains' => array(
  6.             'subRouteName' => array(
  7.                 'type'     => 'Zend_Controller_Router_Route_Static',
  8.                 'route'    => 'bar',
  9.                 'defaults' => array(
  10.                     'module'      => 'module',
  11.                      'controller' => 'controller',
  12.                      'action'     => 'action'
  13.                 )
  14.             )
  15.         )
  16.     )
  17. ));
  18.  
  19. // Das Trennzeichen vor dem hinzufügen der Config setzen
  20. $router->setChainNameSeparator('_separator_')
  21.  
  22. // Config hinzufügen
  23. $router->addConfig($config);
  24.  
  25. // Der Name unserer Route ist jetzt: chainName_separator_subRouteName
  26. echo $this->_router->assemble(array(), 'chainName_separator_subRouteName');
  27.  
  28. // Die Prüfung: Ausgegeben wird /foo/bar

Zend_Rest_Route

Die Komponente Zend_Rest enthält eine RESTvolle Route für Zend_Controller_Router_Rewrite. Diese Route bietet ein standardisiertes Routing Schema das Routinganfragen durch Übersetzung der HTTP Methode und der URI zu einem Modul, Controller und einer Action. Die unten stehende Tabelle bietet eine Übersicht darüber wie Anfragemethoden und URI's geroutet werden.

Verhalten von Zend_Rest_Route
Methode URI Module_Controller::action
GET /product/ratings/ Product_RatingsController::indexAction()
GET /product/ratings/:id Product_RatingsController::getAction()
POST /product/ratings Product_RatingsController::postAction()
PUT /product/ratings/:id Product_RatingsController::putAction()
DELETE /product/ratings/:id Product_RatingsController::deleteAction()
POST /product/ratings/:id?_method=PUT Product_RatingsController::putAction()
POST /product/ratings/:id?_method=DELETE Product_RatingsController::deleteAction()

Verwendung von Zend_Rest_Route

Um Zend_Rest_Route für eine komplette Anwendung einzuschalten muss diese ohne Konfigurationsparameter erstellt und als Standardroute dem Frontcontroller hinzugefügt werden:

  1. $front     = Zend_Controller_Front::getInstance();
  2. $restRoute = new Zend_Rest_Route($front);
  3. $front->getRouter()->addRoute('default', $restRoute);

Note: Wenn Zend_Rest_Route keinem gültigen Modul, Controller oder keiner Action entspricht gibt diese FALSE zurück und der Router versucht eine Entsprechung zu finden indem die nächste Route im Router verwendet wird.

Um Zend_Rest_Route für spezielle Module einzuschalten muss diese mit einem Array von Modulnamen als 3tes Argument des Constructors erstellt werden:

  1. $front     = Zend_Controller_Front::getInstance();
  2. $restRoute = new Zend_Rest_Route($front, array(), array('product'));
  3. $front->getRouter()->addRoute('rest', $restRoute);

Um Zend_Rest_Route für spezielle Controller einzuschalten muss ein Array von Controllernamen als Wert für jedes Modul (Arrayelement) hinzugefügt werden.

  1. $front     = Zend_Controller_Front::getInstance();
  2. $restRoute = new Zend_Rest_Route($front, array(), array(
  3.     'product' => array('ratings')
  4. ));
  5. $front->getRouter()->addRoute('rest', $restRoute);

Zend_Rest_Route mit Zend_Config_Ini

Um Zend_Rest_Route von einer INI Konfigurationsdatei aus zu verwenden muss man den "route" Typ Parameter verwenden und die Konfigurationsoptionen setzen:

  1. routes.rest.type = Zend_Rest_Route
  2. routes.rest.defaults.controller = object
  3. routes.rest.mod = project,user

Die 'type' Option benennt den RESTvollen Routing Konfigurationstyp. Die 'defaults' Option wird verwendet um gemeinsame Standardmodule zu spezifizieren, und oder Aktionen für die Route. Alle anderen Optionen in der Konfigurationsgruppe werden als RESTvolle Modulnamen behandelt, und deren Werte sind RESTvolle Kontrollernamen. Die beispielhafte Konfiguration definiert Mod_ProjectController und Mod_UserController als RESTvolle Controller.

Dann ist die addConfig() Methode des Rewrite Router Objekts zu verwenden:

  1. $config = new Zend_Config_Ini('path/to/routes.ini');
  2. $router = new Zend_Controller_Router_Rewrite();
  3. $router->addConfig($config, 'routes');

Zend_Rest_Controller

Um bei der Entwicklung von Controllern zu Hilfe zu sein die mit Zend_Rest_Route verwendet werden, müssen die Controller von Zend_Rest_Controller erweitert werden. Zend_Rest_Controller definiert die 5 am meisten benötigten Operationen für RESTvolle Ressourcen in der Form von abstrakten Actionmethoden.

  • indexAction() - Sollte einen Index von Ressourcen empfangen und diese mit der View verknüpfen.

  • getAction() - Sollte eine einzelne Ressource empfangen die von einer URI identifiziert wird und diese mit der Vew verknüpfen.

  • postAction() - Sollte eine einzelne neue Ressource akzeptieren und dessen Status persistent machen.

  • putAction() - Sollte eine einzelne Ressource akzeptieren die von einer URI identifiziert wird und dessen Status persistent machen.

  • deleteAction() - Sollte eine einzelne Ressource löschen die von einer URI identifiziert wird.

Zend_Config mit dem RewriteRouter verwenden

Manchmal ist es praktischer, eine Konfigurationsdatei mit neuen Routen zu aktualisieren, als den Code zu ändern. Dies ist mit Hilfe der addConfig() Methode möglich. Im Wesentlichen kann man eine Zend_Config kompatible Konfiguration erstellen, in seinem Code einlesen und an den RewriteRouter übergeben:

Als Beispiel wird die folgende INI Datei angenommen:

  1. [production]
  2. routes.archive.route = "archive/:year/*"
  3. routes.archive.defaults.controller = archive
  4. routes.archive.defaults.action = show
  5. routes.archive.defaults.year = 2000
  6. routes.archive.reqs.year = "\d+"
  7.  
  8. routes.news.type = "Zend_Controller_Router_Route_Static"
  9. routes.news.route = "news"
  10. routes.news.defaults.controller = "news"
  11. routes.news.defaults.action = "list"
  12.  
  13. routes.archive.type = "Zend_Controller_Router_Route_Regex"
  14. routes.archive.route = "archive/(\d+)"
  15. routes.archive.defaults.controller = "archive"
  16. routes.archive.defaults.action = "show"
  17. routes.archive.map.1 = "year"
  18. ; OR: routes.archive.map.year = 1

Die oben angeführte INI Datei kann dann wie folgt in ein Zend_Config Objekt eingelesen werden:

  1. $config = new Zend_Config_Ini('/path/to/config.ini', 'production');
  2. $router = new Zend_Controller_Router_Rewrite();
  3. $router->addConfig($config, 'routes');

Im oberen Beispiel teilen wir dem Router mit, den 'routes' Bereich der INI Datei für seine Routen zu verwenden. Jeder Schlüssel auf erster Ebene in diesem Bereich wird verwendet, um den Namen der Routen zu definieren; das obige Beispiel definiert die Routen 'archive' und 'news'. Jede Route erfordert dann mindestens einen 'route' Eintrag und einen oder mehrere 'defaults' Einträge; optional können eine oder mehrere 'reqs' (kurz für 'required', d.h. erforderlich) Einträge angegeben werden. Alles in allem entspricht dies den drei Argumenten, die an ein Zend_Controller_Router_Route_Interface Objekt übergeben werden. Ein Optionsschlüssel 'type' kann verwendet werden, um den Typ der Routenklasse für diese Route anzugeben; standardmäßig wird Zend_Controller_Router_Route verwendet. Im obigen Beispiel wird die 'news' Route definiert, um Zend_Controller_Router_Route_Static zu verwenden.

Erben vom Router

Der Standard Rewrite Router sollte die meisten Funktionalitäten die benötigt werden zur Verfügung stellen; meistens wird es nur notwendig sein einen neuen Router Typen zu erstellen um neue oder modifizierte Funktionalitäten für die verfügbaren Routen zu bieten.

So gesehen, wird man in einigen Fällen ein anderes Routing Paradigma verwenden wollen. Das Interface Zend_Controller_Router_Interface bietet die minimalen Information die benötigt werden um einen Router er erstellen und besteht aus einer einzigen Methode.

  1. interface Zend_Controller_Router_Interface
  2. {
  3.   /**
  4.    * @param  Zend_Controller_Request_Abstract $request
  5.    * @throws Zend_Controller_Router_Exception
  6.    * @return Zend_Controller_Request_Abstract
  7.    */
  8.   public function route(Zend_Controller_Request_Abstract $request);
  9. }

Das Routing findet nur einmal statt, wenn die Anfrage das erste Mal vom System erhalten wird. Der Zweck des Routers ist es, Controller, Aktion und optionale Parameter auf Basis der Anfrageumgebung zu ermitteln und im Request zu setzen. Das Request Objekt wird dann an den Dispatcher übergeben. Wenn es nicht möglich ist, eine Route auf einen Dispatch Token abzubilden, soll der Router nichts mit dem Request Objekt machen.

Copyright

© 2006-2019 by Zend, a Rogue Wave Company. Made with by awesome contributors.

This website is built using zend-expressive and it runs on PHP 7.

Contacts