XML-Parser

Die Klasse XMLParser analysiert eine XML-Datei mit der Dateierweiterung .xml. Der Aufbau der XML-Datei ist im folgenden genauer beschrieben. Eingeleitet wird eine Routing-Datei mit dem Standard-XMl-Tag und dem Haupttag definition

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definition />

Im folgenden werden die zur Verfügung stehenden Elemente/Tags beschrieben:

XPATH
/definition
/definition/routes
/definition/routes/group Gruppen
/definition/routes/group/route
/definition/routes/group/route/presenter Presenter
/definition/routes/group/route/method HTTP-Methode
/definition/routes/group/route/pattern URL-Suchmuster
/definition/routes/group/route/template URL-Template
/definition/routes/group/route/configuration Konfigurationswerte
/definition/routes/group/route/links Linksammlung
/definition/routes/group/route/links/link
/definition/routes/group/route/parameters Parameter
/definition/routes/group/route/parameters/parameter
/definition/routes/group/route/exceptions Behandlung von Ausnahmen
/definition/routes/group/route/exceptions/exception
/definition/routes/group/route/exceptions/exception/parameter
/definition/routes/group/route/accesscontrol Zugriffs- und Rechtedefinition
/definition/routes/group/route/accesscontrol/permission
/definition/routes/group/route/accesscontrol/permission/entity

Standard-Route

Wenn keine Route passt, so kann über das Attribute default="true" eine Route als Standardroute gekennzeichnet werden. Bei dieser Route wird das Pattern nicht überprüft und die Route wird unabhängig davon ausgeführt.

<route id="B1" default="true">
     <method>GET</method>
     <presenter>\Alvine\Application\Web\Presenter\Home</presenter>
     <pattern><![CDATA[^/$]]></pattern>
     <template>/</template>
</route>

Group

Eine Gruppe ermöglicht es verschiedene Werte presenter, configuration, parameter, method, pattern, template ausserhalb einer Route zu definieren. Diese Werte gelten dann für alle in dieser Gruppe definierten Routen.

In dem folgenden Beispiel besitzen die Routen r1, r2 und r3 alle den gleichen Presenter. Die Route r4 definiert, obwohl in der gleichen Gruppe einen eigenen Presenter.

<routes>
    <group>
        <presenter>GroupPresenter</presenter>
        <route id="r1" /> 
        <route id="r2" />
        <route id="r3" />
        <route id="r4">
            <presenter>R4Presenter</presenter>
        </route>
    ....     

Route

Die eigentliche Definition einer Route erfolgt in dem route-Tag. Jede Route benötigt eine eindeutige ID. Wird eine ID mehrfach definiert, so wird die letzte Definition genommen. Im folgenden fall werden drei Routen r1, r2 und r3 angelegt.

<route id="r1" />
<route id="r2" />
<route id="r3" />
<route id="r2" />

Das Pattern und die Methode werden zur identifizierung einer Route verwendet.

Pattern

Das Pattern definiert das Suchmuster. Die Sonderzeichen eines Regex sollten mit einem CDATA gekapselt werden. In dem folgenden Beispiel wird die Route beim Aufruf der URL /home/ vwerwendet, jedoch nicht bei /home.

Das Pattern ist ein regulärer Ausdruck der Online zum Beispiel hier getestet werden kann.

<pattern><![CDATA[^/home/$]]></pattern>

Im Suchmuster können benannte Parameter definiert werden, die dem Presenter zur Verfüng stehen. Dazu muss Regex eine Gruppe (über Klammern) definiert werden. Dieser Gruppe wird dann wie folgt ein Name name zugewiesen: (?<name>group).

In dem folgenden Beispiel wird der zweite Teil der URL als Blog-ID blogid definiert. Dieses Pattern trift auf alle URL die mit /blog/ anfangen und dann eine Zeichenfolge aus Buchstaben und Zahlen haben. Der zweite Teil der URL wird dem Presenter dann als Parameter blogid übergeben.

<pattern><![CDATA[^/blog/(?<blogid>[a-z_0-)]+)$]]></pattern>

Method

Die Methode kann eine der gültigen HTTP-Methoden

<method>GET</method>

oder das Schlüsselwort ANY sein.

<method>ANY</method>

enthalten.

Presenter

Der presenter-Tag legt die zu verwendende Presenter-Klasse inklusive Namespace fest.

<presenter>\Namespace\MyPresenter</presenter>

Template

Das Template wird für die Erstellung der URL zu dieser Route verwendet.

Dies kommt zum Beispiel bei einem Redirekt zum Tragen. Hier wird die entsprechend neue Route über die definierte ID geladen und das Template zur Erstellung der Route genommen.

<template><![CDATA[/home/]]></template>

Beispiel mit Platzhalter

<template>/info/{category}</template>

Die Platzhalter in den geschweiften Klammern werden von der Anwendung ersetzt.

Parameter

Über eine URL können Parameter an den Presenter übergeben werden. Dies kann entweder in der Form von Benannten Gruppen im Pattern oder über Parameter in der URL (alles nach dem Fragezeichen) erfolgen.

Welche Parameter definierbar sind und welchen Typ diese Parameter haben, wird im parameters-Block definiert. Im folgenden Besipiel sind zwei Parameter definiert:

<parameters>
    <parameter name="dataset" type="ArrayType" />
    <parameter name="page" type="StringType" required="required" />
</parameters>

Die Typen müssen im Namensraum \Alvine\Types\Parameter definiert sein.

Typ
ArrayType
Boolean
Collection
Integer
Map
Mixed
ObjectType
Simple
StringType

Hinweis

Bei Integer-Parametern ist darauf zu achten, dass diese einen Default-Wert haben.

Dem Presenter werden nur die Parameter die der Presenter in der Methode Presenter::getExecuteParameter() definiert hat, übergeben. Die Standardimplementierung von Presenter::getExecuteParameter() nimmt alle Werte die in der Route innerhalb des -Blocks definiert sind als gültige Parameter.

/**
 * Diese Methode definiert welche
 * Parameter im Presenter zur Verfügung 
 * stehen sollen.
 * 
 * @param \Alvine\Application\Web\Route  $routeObj  Route-Objekt
 * @param \Alvine\Types\Map\ParameterMap $parameter Parameter der Route
 * @param \string                        $method    HTTP-Verb
 * @param \Alvine\Net\Resource\URI       $route     Aufgerufene URI
 * 
 * @return \\Alvine\Types\Map\ParameterMap
 */
public function getExecuteParameter(Route $routeObj, \Alvine\Types\Map\ParameterMap $parameter, $method, \Alvine\Net\Resource\URI $route) {
        $parameterMap=new \Alvine\Types\Map\ParameterMap;
        foreach($parameter as $param) {
            $parameterMap->setValue($param->getKey(), $param);
        }
        return $parameterMap;
}

Auswertung der Parameter

Die Werte eines Parameters können aus unterschiedlichen Quellen kommen. Die Standardimplementierung prüft der Reihe nach Parameter die über die Route definiert wurden, Cookies, Werte aus dem Query, aus dem HTTP-Body und von der URI.

Hinweis

Gibt eine der Methoden einen Wert ungleich null zurück, so wird dieser Wert genommen.

Reihen- folge Wert Konstante Methode im Router Beschreibung Beispiel
1 url PARAMETERFROMURL getUrlParameter Werte die über ein Matching der URL entstehen - pattern www.example.com/mustermann/ (in der Route definiert (?[a-z])/) )
2 body PARAMETERFROMBODY getBodyParameter alle im Body per Post übergebenen Variablen mit MIMEType Formular name=mustermann (im HTTP-Body übertragen)
3 query PARAMETERFROMQUERY getQueryParameter Die Werte in der URL die nach dem Fragezeichen kommen www.example.com/?name=mustermann
4 coockie PARAMETERFROMCOOKIE getCookieParameter alle im Cookie übertragenen Werte name=mustermann (im Header übertragen)
5 route PARAMETERFROMROUTE getRouteParameter die in der Route definierten Parameters true

Die verwendeten Parameter und die Reihenfolge kann über das Attribute source definiert werden. In dem folgenden Beispiel sollen nur Werte die über ein Cookie kommen, oder im Query definiert sind genommen werden.

<parameters source="cookie,query">
   <!-- String-Parameter mit Defaultwert my -->
   <parameter name="template" type="StringType">my</parameter>
   <!-- Boolean-Parameter mit Defaultwert true -->
   <parameter name="flag" type="Boolean">true</parameter>
</parameters>

Im Presenter stehen definierten Parameter zur Verfügung. Wird in der Route keine gesonderte Angabe gemacht stehen alle Werte die über eine HTTP-Anfrage gekommen sind (post, get, cookie) und die über das Pattern definierten Parameter (url) zur Verfügung.

<route id="A3">
     <method>GET</method>
     <presenter>\Alvine\Application\Web\Presenter\PHPInfo</presenter>
     <pattern><![CDATA[^/info/(?<category>([0-9]+))$]]></pattern>
</route>

Parameter deaktivieren

Soll kein Parameter überschrieben werden und der Standard vom Presenter verwendet werden , können die Parameter auch leer gelassen werden

<parameters source="" />

Configuration

Die Konfiguration hängt vom verwendeten Presenter ab und ist hier zu entnehmen.

Accesscontrol

Soll eine URL nur für bestimmte Benutzer, Gruppen oder Rollen aufrufbar sein, so kann eine Zugriffskontrolle über einen accesscontrol-Block definiert werden.

<accesscontrol>
    <permission class="\Alvine\Application\Web\Route\Permission" 
                entity-factory="\Alvine\Application\Platform\Web\Route\EntityFactory">
        <entity class="\Alvine\Security\Authentication\User">administrator</entity>
        <entity class="\Alvine\Application\Platform\Security\Authentication\Group">administrator</entity>
    </permission>
</accesscontrol>

Exceptions

Wird bei der Bearbeitung eines Request eine Exception geworfen, so würde dies zu einem 500er Fehler führen. Möchte man in einer Route auf Fehler reagieren, so kann man über einen Exception-Block Exceptions abfangen und ein alternatives Verhalten definieren.

In dem Beispiel wird ein interner Redirect definiert auf die URL /api/access-denied definiert.

<exceptions>
    <exception class="\Alvine\Application\Web\Route\Exception\AccessDenied" 
               handler="\Alvine\Application\Web\Route\Handler\InternalRedirect">
        <parameters>
            <parameter name="path">/api/access-denied</parameter>
        </parameters>
    </exception>
</exceptions>

Standard-Handler für Exeptions

Die folgenden Handler können in der Reoutendefinition verwendet werden. Eigene Handler lassen sich einfach integrieren.

Klasse Information Parameter Beschreibung
AlvineApplicationWeb RouteHandlerRedirect Dieser Handler führt einen permanenten Redirect durch (StatusCode 301). Ein eigener StatusCode (z.B. 303) kann über den Parameter statuscode übergeben werden location statuscode Ziel-URL HTTP-Statuscode optional
AlvineApplicationWeb RouteHandlerInternalRedirect Dieser Handler führt die angegebene Route ohne vorheriges überprüfen des Musters aus. path Pfad auszuführenden Route
AlvineApplicationWeb RouteHandlerServerFailure Es wird eine interne Fehlerseite für Serverfehler angezeigt. Das ist dann Nützlich, wenn ein schwerwiegender Fehler auftritt und kein Presenter oder View zurVerfügung steht. Dieser Handler sollte sparsam eingesetzt werden und besser durch einen internen Redirect ersetzt werden. message Fehlermeldung optional

Hinweis

Handler sollten nicht zur Ausgabe von Inhalten "missbraucht" werden.

Über Links lassen sich Routen definieren, die als Ausgwabspunkt der aktuellen Route genommen werden können. Wird zum Beispiel eine Liste angezeigt, besteht ausgehend von der Liste die Möglichkeit Einträge zu ändern und zu löschen.

<links>
    <link route="A1" relation="delete" label="Löschen"/>
    <link route="A2" relation="list" label="Liste"/>
    <link route="A3" relation="update" label="Ändern"/>
    <link route="A4" relation="patch" label="Patchen"/>
</links>

Attribute

Attribute Beschreibung
relation Schlüsselwort der Beziehung
route ID der Zielroute
label Bezeichnung des Links (z.B. im Anchor)

Besondere Relationen

Beziehung Beschreibung
delete URL zum löschen der Route
list Liste
update Ändern eines Eintrages
patch Ändern eines Feldes
add Hinzufügen eines neuen Eintrages

Eigene Routen-Klasse

Die Standardroute stellt eine Vielzahl von Möglichkeiten bereit. Möchte man jedoch Änderungen am Verhalten der Route vornehmen, so kann man eine eigene Route-Klasse über den Parameter class im Route-Tag definieren. Die eigene Route-Klasse muss aber von Route abgeleitet sein.

<route id="A1" class="MyRoute">
    <method>GET</method>
    <presenter>\Alvine\Application\Web\Presenter\PHPInfo</presenter>
</route> 

Die PHP-Klasse sieht dann folgendermaßen aus:

class MyRoute extends \Alvine\Application\Web\Route {
}