php object oriented library (phool) v2 - README

• Services

  Services bilden die HTTP Schnittstelle für die Ressourcen einer Software und bilden damit den Kern jeder Anwendung, die mit phool entwickelt wird. Sämtliche Anfragen, die ein Client an eine phool Anwendung stellen kann, werden durch Services abgebildet. Das ist Teil der REST Architektur, die vorgibt, dass ein Client niemals direkt eine Ressource verändern darf.
  Ein Service muss mindestens eine der Methoden GET, POST, PUT oder DELETE implementieren, um auf einen Request dieses Typs zu reagieren. Außerdem kann ein Service die Methode HEAD implementieren, um informationen über sich selbst auszuliefern.
  Die Hauptkomponente einer Anwendung (Dispatcher) führt automatisch die durch den HTTPRequest definierte Methode eines Services aus und erwartet von dieser entweder ein HTTPResponse Objekt, das direkt ausgegeben werden kann oder ein Forward Objekt für die weitere Verarbeitung in der Präsentationsschicht.

• Views

  Die Views bilden die Präsentationsschicht einer Anwendung. Ein View erweitert das HTTPResponse Objekt um eine render() Methode, um Responses mit Inhalten zu füllen. Views haben immer den HTTP Status 200 (OK). Die Verwendung von Views setzt voraus, dass sämtliche Ausgaben entweder zuvor gepuffert werden oder erst im View stattfinden, da ansonsten das senden der Response Header fehlschlägt.
  
  Das Framework liefert zwei spezielle Views mit:

  • Template
    Ein View dessen render() Methode "Suchen & Ersetzen" Muster über den Inhalt der Antwort laufen lassen und auf diese Weise Text-Vorlagen mit Variablen aus einem Forward Objekt befüllen kann.

  • SOAView
    Ein View der den Variablencontainer eines Forward Objektes als textbasierte Datenstruktur ausgeben kann. In phool vordefinierte renderer sind: JSON, PHP Serialize und WDDX Packet.
    Textbasierte Datenstrukturen werden oft verwendet um Daten an User Interface Frameworks wie yui, jQuery oder prototype zu übertragen.

• Filter

  Filter sind Interceptor Objekte, die während des Programmablaufs an definierten Stellen ausgeführt werden.
  Es gibt drei vordefinierte Stellen im Programmablauf an denen Filter geladen und ausgeführt werden:

  • F_PRE (Request Filtering)
    Wird aufgerufen nachdem der Service geladen ist, aber bevor die angeforderte Methode des Services ausgeführt wird. Im Filter Objekt wird dies durch die Methode pre() abgbildet. Der Methode wird ein HTTPRequest Objekt übergeben, um die darin enthaltenen Daten zu filtern. Request Filter können z.b. Validierungen oder Datenbereinigungen enthalten.
    Für PRE Filter gibt es einen Modus "strict". Filter im diesem Modus können den weiteren Programmablauf unterbrechen, wenn die Filtermethode fehlschlägt.

  • F_INTER (Forward Filtering)
    Wird aufgerufen nachdem der Service (erfolgreich) ausgeführt wurde, aber bevor ein View erstellt wird. Im Filter Objekt wird dies durch die Methode inter() abgebildet. Der Methode wird ein Forward Objekt übergeben, dass vom Service erzeugt wurde, um die darin enthaltenen Daten zu modifizieren. Forward Filter können z.b. den regulären Programmablauf in besonderen Situationen verändern.

  • F_POST (Response Filtering)
    Wird aufgerufen nachdem ein View gerendert wurde, aber noch bevor die Antwort an den Client gesendet wird. Im Filter Objekt wird dies durch die Methode post() abgebildet. Der Methode wird ein HTTPResponse Objekt übergeben um den darin enthaltenen Output zu modifizieren. Response Filter können z.b. eine Ausgabe Konvertierung oder die Aufbereitung für spezielle Ausgabegeräte durchführen.

• Resources

  Resources sind die echten Business Objekte einer Anwendung (RESTful "Nouns") die von Services genutzt werden können. Während der Service die HTTP Schnittstelle zum Benutzer Interface darstellt, implementiert eine Resource genau ein Anwendungsobjekt also z.B. einen User, einen Mandanten oder eine Benutzergruppe. Da Resources unabhängig von der Beschaffenheit ihrer Datenquelle(n) sein sollen, verwenden sie die sog. "Data Access Objects" (DAOs).
  DAOs sind "übersetzer" Objekte, die die Beschaffenheit von externen Datenquellen genau kennen und entsprechend implementieren können. Dadurch können externe Datenquellen (z.b. Datenbanktypen) variieren ohne dafür eine Resource zu verändern.
  Die DAOs "übersetzen" die Anfragen der Resources in die jew. "Sprache" der externen Datenquelle und liefern ein Ergebnis mit einer definierten Schnittstelle mit der die Resources dann arbeiten können.
  Der Unterschied zwischen einem DAO und einer Resource ist, dass ein DAO eine abstrakte Schnittstelle für genau eine Quelle implementiert (z.b. eine Datenbank Tabelle) während eine Resource durchaus aber mehrere DAOs nutzen kann.
  Jede Resource muss mind. das CRUD Interface eines Anwendungsobjektes abbilden und daher die folgenden Methoden enthalten:

  • Resource::load( )
    Daten des Anwendungsobjektes aus externer Datenquelle lesen und im internen Datenspeicher ablegen (READ).

  • Resource::save( )
    Daten aus dem internen Datenspeicher der Resource in die externe Datenquelle schreiben (CREATE OR UPDATE)

  • Resource::remove( )
    Daten des Anwendungsobjektes in der externen Datenquelle löschen (DELETE)

• Gateways

  Ein Gateway bietet einen Zugriffsschutz auf die Services einer Anwendung. Gateways können Anfragen authorisieren, Authentifizierungsdaten anfordern und/oder Zugriffsregeln gegen aufgerufene (Service) URLs auflösen.
  Der Entwickler kann mit einem Gateway verschiedene Anwendungsbereiche (realms) definieren und für jeden dieser Bereiche unterschiedliche Zugriffsregeln und Authentifizierungsmethoden definieren.
  Dadurch ist es möglich, die einzelnen Services einer Anwendung in öffentliche oder private Bereiche zu verschieben. Die Regeln können sowohl Methoden (GET, POST, PUT, DELETE) als auch Pfade enthalten und unterstützen auch Wilcards.

• Tools

  Tools sind Hilfsobjekte, die genutzt werden um wiederkehrende Aufgaben durchzuführen. Tools bilden mehr oder weniger lose Sammlungen von Hilfsfunktionen zu einem bestimmten Thema und ihre Methoden haben untereinander keine Beziehung. Daher ist die Haupteigenschaft einer Toolmethode, dass Sie statisch aufgerufen werden kann.
  Der Zugriff auf die Operationen eines Tools erfolgt über die Toolbox. Die Toolbox ist ein Registry Objekt, dass sämtliche Tool Methoden zur Laufzeit laden und ausführen kann, sobald eine Operation eines bestimmten Tools angefordert wird.
  Ein Tool Objekt kann auch Funktionen einer bereits existierenden library importieren und über die Toolbox verfügbar machen. Tools haben dafür eine setup methode, in der z.b. Variablen, die von einer externen library benötigt werden definiert werden können.

• Adapter

  Adapter bieten eine Möglichkeit, bereits entwickelte Business Objekte wie Models zu behandeln. Damit haben Entwickler die Möglichkeit Ihre vorhandenen Business Objekte mit neuen Schnittstellen zu versehen, ohne dabei den alten Code umschreiben zu müssen. D.h. auch eine bereits entwickeltes System kann Stück für Stück mit einer REST Schnittstelle versehen werden, während der eigentliche Kern der Anwendung unverändert bleibt.

1. Dispatcher: Die Hauptkomponente jeder phool Anwendung verarbeitet Requests und erzeugt Services, Views und Filter.
2. Config: Ein Hilfsobjekt zum laden und kapseln von Readonly werten aus Config Files für die Laufzeit.
3. Forward: Ein erweitertes Statusobjekt speichert Informationen verschiedener Komponenten zur Laufzeit.
4. Request/Response: Input und Output eines phool Programms. Können mit Filtern und Views gelesen und manipuliert werden.
5. ValueObject/Container: Definierte Schnittstellen für einfache oder komplexere Datencontainer.
6. Registry: Abstrakte Factory für sämtliche (Haupt)Komponenten und für die Verwaltung von eigenen Singletons.
7. Toolbox: Abstrakte Factory für die Verwaltung von Tool Objekten während der Laufzeit.