Filter :: Adventure PHP Framework (APF)

Filter

1. Einführung

Das Thema "Filter" spielt im Adventure PHP Framework eine zentrale Rolle. In den Releases inkl. 1.8 wurden diese bereits versteckt für die Sicherung der Ein- und Ausgaben genutzt, ab dem 1.9er-Zweig können diese vom Benutzer direkt beeinflusst und über die Registry verwaltet werden. Weiterhin stehen nun Filter für Formularfelder zur Verfügung, die zusätzlich zu den Ein- und Ausgabe-Filtern zur Sicherung der Benutzereingaben verwendet werden können.

2. Eingabe-Filter

Die Klasse der Eingabe-Filter kümmern sich um die Auswertung der Benutzereingaben der in der URL und der im HTTP-Protokoll eingebetteten Inhalte (aka POST-Daten). Dazu sind im Framework bereits vier allgemeingültige Filter-Typen enthalten, die sich um die Verarbeitung von Benutzer-Eingaben mit und ohne Rewrite-URLs kümmern.

Da der Kern des Frameworks selbst keine Kenntnis vom URL-Layout hat, sondern ausschließlich mit dem $_REQUEST-Array arbeitet, ermöglichen erst die Filter ein so generisches Rewrite-URL-Layout.

Die Filter gliedern sich in die folgenden Bereiche:

2.1. PageController mit Standard-URLs

Der einfachste Typ wird beim Einsatz des PageControllers im normalen URL-Modus verwendet. Der StandardRequestFilter aus dem Namespace core::filter::input ersetzt die eingegebenen Werte durch ihre HTML-codierten Entsprechungen (siehe htmlspecialchars()) und führt ein stripcslashes() aus, falls die Option magic_quotes_gpc auf den Wert 1 gesetzt wurde um Inhalte in Formularen korrekt darstellen zu können.

2.2. PageController mit Rewrite-URLs

Die Entgegennahme der Benutzer-Eingaben im Fall von Rewrite-URLs übernimmt der Filter PagecontrollerRewriteRequestFilter aus dem Namespace core::filter::input. Dieser zerlegt die Rewrite-URL in seine Bestandteile und generiert aus diesen die Inhalte des $_REQUEST-Arrays neu. Der Filter geht dabei davon aus, dass die umgeschriebenen URLs eine Folge von durch "/" getrennte Parameter-Wert-Paare enthalten. Anschließend wird der StandardRequestFilter ausgeführt um die Eingaben zu sichern.

2.3. FrontController mit Standard-URLs

Der FrontController-Filter für Standard-URLs analysiert den Request, extrahiert die FrontController-Anweisungen und registriert die Actions beim FrontController. Normale Parameter werden identisch zu den beiden vorangegangenen Filtern mit den StandardRequestFilter behandelt. Hierfür zeichnet sich der FrontcontrollerRequestFilter aus dem Namespace core::filter::input verantwortlich.

2.4. FrontController mit Rewrite-URLs

Ähnlich dem PagecontrollerRewriteRequestFilter filtert der FrontcontrollerRewriteRequestFilter aus dem Namespace core::filter::input die Eingaben bei Nutzung des Frontcontrollers in Verbindung mit Rewrite-URLs. Dabei werden ebenfalls die umgeschriebenen Action-Anweisungen und die normalen Parameter aus der URL extrahiert, in das $_REQUEST-Array gespeichert und die Actions an den Frontcontroller übergeben.

3. Ausgabe-Filter

Die Ausgabe-Filter kümmern sich um die Formatierung des erzeugten HTML-Codes. Da hier keine Unterscheidung zwischen Front- und PageController notwendig ist, beinhaltet das APF nur einen Ausgabe-Filter, der sich im Fall von aktiviertem URL-Rewriting um das Umschreiben der Links und Formular-Actions kümmert. Diese Aufgabe übernimmt der HtmlLinkRewriteFilter aus dem Namespace core::filter::output. Um Links explizit davon auszunehmen, kann das Link-Attribut linkrewrite auf den Wert false gesetzt werden. mailto:-Links werden ab Release 1.10 automatisch ausgenommen.

Der mit dem APF mitgelieferte OutputFilter (Klasse: GenericOutputFilter) nutzt den XmlParser des APF zur Analyse der HTML-Links. Aus diesem Grund ist es notwendig, dass die Attribute alle Links mit >>"<< umschlossen sind und keine TAB-Zeichen enthalten. Ist das nicht der Fall kann es zum Endlos-Schleifen-Effekt kommen, der im Forum unter 99% CPU-Last bei aktiviertem UrlRewriting beschrieben wurde.

4. Aufbau und Funktion

Ein Filter im Adventure PHP Framework wird durch eine Klasse, die von AbstractFilter ableitet, repräsentiert. Diese muss die Methode filter() implementieren, die ein Argument trägt: den Input. Am Ende der Funktion muss der Output zurückgegeben werden.

In der folgenden Code-Box wird ein Beispiel beschrieben:

PHP-Code

class MySpecialFilter extends AbstractFilter {

   public function filter($input){
      return $this->__replaceAWithB($input);
   }

   private function __replaceAWithB($string){
      return str_replace('a','b',$input);
   }

}

Um einen Filter nutzen zu können, muss dieser über die FilterFactory erzeugt werden. Die Methode getFilter() erwartet ein FilterDefinition-Objekt als Parameter. Die FilterDefinition beinhaltet dabei den Namespace und den (Klassen- bzw. Datei-)Namen des Filters.

Das folgende Beispiel zeigt die Verwendung eines Filters:

PHP-Code

// define the filter
$filterDef = new FilterDefinition('my::filter::namespace','MySpecialFilter');

// create the filter
$filter = FilterFactory::getFilter($filterDef);

// gather the input
$input = /* ... */

// apply the filter
$output = $filter->filter($input);

Der interne Aufbau eines Filters ist dabei komplett dem Entwickler überlassen.

Details zu den enthaltenen Standard-Filtern kann der API-Dokumentation der jeweiligen Version unter Downloads entnommen werden.

5. Konfiguration

Die Konfiguration der Ein- und Ausgabe-Filter wird über die Registry gesteuert. Hierzu existieren folgende Registry-Einträge im Namespace apf::core::filter:

PageControllerInputFilter: wird bei Verwendung des PageControllers beim Erstellen des Page-Objekts ausgeführt.
FrontControllerInputFilter: wird bei Verwendung des FrontControllers beim Starten ausgeführt. Inkludiert die Funktionen des PageControllerInputFilter hinsichtlich URL-Rewriting.
OutputFilter: Wird bei der Transformation der PageController-Seite auf den generierten Quelltest angewendet.

Möchte der Entwickler sein eigenes URL-Layout definieren, so kann dies durch einen eigenen Filter abgebildet werden, der als Page- oder FrontController-Input-Filter definiert wird. Da die Konfiguration über die Registry erfolgt, kann dies in der Bootstrap-Datei vorgenommen werden. Die folgende Code-Box zeigt, wie die Konfiguration vorgenommen für den PageController werden kann:

PHP-Code

// include page controller
include('./apps/core/pagecontroller/pagecontroller.php');

// configure registry
Registry::register(
   'apf::core::filter',
   'PageControllerInputFilter',
   new FilterDefinition('my::filter::namespace','MyPageControllerInputFilter')
);

// create page and display page
$page = new Page();
$page->loadDesign('namespace::of::my::webpage','mytemplate');
echo $page->transform();

Im Fall des FrontControllers erfolgt die Anpassung wie folgt:

PHP-Code

// include page controller
include('./apps/core/pagecontroller/pagecontroller.php');

// include front controller
import('core::frontcontroller','Frontcontroller');

// configure registry
Registry::register(
   'apf::core::filter',
   'FrontControllerInputFilter',
   new FilterDefinition('my::filter::namespace','MyFrontControllerInputFilter')
);

// create front controller and start it
$fC = &Singleton::getInstance('Frontcontroller');
$fC->start('namespace::of::my::webpage','mytemplate');

Wichtig: die Konfiguration muss vor dem Erzeugen des Page- bzw. FrontControllers erfolgen!

Die Manipulation des Ausgabe-Filters gestaltet sich identisch zu den beiden vorherigen Beispielen. Hier muss jedoch der Registry-Eintrag OutputFilter mit einer neuen FilterDefinition belegt werden.

Falls keine Filterung erwünscht ist, können die oben aufgezeigten Konfigurationsdirektiven mit null belegt werden:

PHP-Code

// include page controller
include('./apps/core/pagecontroller/pagecontroller.php');

// include front controller
import('core::frontcontroller','Frontcontroller');

// disable all filters (or just parts of it)
Registry::register('apf::core::filter','PageControllerInputFilter',null);
Registry::register('apf::core::filter','FrontControllerInputFilter',null);
Registry::register('apf::core::filter','OutputFilter',null);

...

6. Formular-Filter

Aufbauend auf der oben gezeigten Definition von Filtern existieren Seit dem 1.9er-Branch auch Filter für Formular-Felder. Die Verwendung und Anpassung der Filter wird im Kapitel Verwendung von Formular-Filtern erläutert.

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.

Für diesen Artikel liegen aktuell keine Kommentare vor.

Filter

Kommentare

QUICKNAVI