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.

Links¶

Ü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 {
}