Permalink
Fetching contributors…
Cannot retrieve contributors at this time
304 lines (287 sloc) 16.2 KB
<doku:title parent="119" tags="grundlagen,pattern,architektur,aufbau ordner struktur,templates,basis konfiguration,registry,dokumentation" title="Grundlagen" urlname="Grundlagen">
Das Kapitel Grundlagen beschreibt den Aufbau des APF, vermittelt Basis-Wissen und verweist auf für den Einstieg
relevante Inhalte der Dokumentation.
</doku:title>
<h3 id="Chapter-1-Einfuehrung"><a href="#Chapter-1-Einfuehrung">1. Einführung</a></h3>
<p>
Das Adventure PHP Framework (kurz: <em>APF</em>) versteht sich als Hilfsmittel für die Implementierung von
objektorientierten, generischen und wiederverwendbaren PHP-Applikationen. Es implementiert eine Reihe von wichtigen,
objektorientierten Design-Pattern und bietet umfassende Lösungen alltägliche Aufgabenstellungen an.
</p>
<p>
Das APF ist <em>keine</em> fertige Anwendung, die lediglich konfiguriert werden muss, sondern eine Basis um solche
Applikationen auf einfache Weise und unter Zuhilfenahme von Standard-Vorgehensweisen zu erstellen.
</p>
<h3 id="Chapter-2-Prinzipien-und-Paradigmen"><a href="#Chapter-2-Prinzipien-und-Paradigmen">2. Prinzipien und Paradigmen</a></h3>
<p>
Wie andere PHP-Frameworks folgt auch das APF bestimmten Prinzipien und Paradigmen. Die folgende Liste zeigt die
wichtigsten auf:
</p>
<ol>
<li>
<strong>Framework statt Klassen-Bibliothek</strong>:
Das APF versteht sich als Framework und nicht als Klassen-Bibliothek. Es folgt festen Paradigmen folgt und gibt
dem Entwickler verschiedene Vorgehensweisen an die Hand, die unveränderlich mit dem Framework verwoben sind.
Diese - oft fälschlicherweise als Einschränkung empfundene - Tatsache hilft Applikationen nach erprobten Mustern
zu erstellen und schützt Einsteiger vor Fehlern.
</li>
<li>
<strong>Objekt-Orientierung</strong>:
Die Komponenten des Adventure PHP Framework sind ausnahmslos nach dem objektorientierten Muster entworfen. Dies
ermöglicht die Erstellung von gekapselten und wiederverwendbaren Funktionalitäten, die Lösungen für immer
wiederkehrende Aufgabenstellungen bereit stellen.
</li>
<li>
<strong>Design-Pattern</strong>:
Die Implementierung der Komponenten des APF orientiert sich an gängige Entwurfsmuster an um den Einstieg in das
Framework zu erleichtern und gängige Begrifflichkeiten zu verwenden.
</li>
<li>
<strong>Bootstrapping</strong>:
Um Konfiguration und Implementierung zu erleichten arbeitet das APF mit einem einzigen Einstiegspunkt in Ihre
Anwendung - der sogenannten Bootstrap-Datei. Diese (z.B. <em>index.php</em>) nimmt alle Anfragen entgegen und
beantwortet diese wie vom Entwickler vorgesehen. Details hierzu können Sie beispielsweise unter
<int:link pageid="014" /> oder <int:link pageid="111" /> nachlesen.
</li>
<li>
<strong>Trennung von Code und Konfiguration</strong>:
Die Trennung von Applikationslogik und Konfiguration ermöglicht es Ihnen, wiederverwendbare Komponenten und Module
zu erstellen. Nutzen Sie diese Möglichkeit, so lassen sich auf einfache Weise mehrere Projekte auf der selben
Code-Basis aufsetzen bzw. eine Multi-Projekt Hosting-Umgebungen basierend auf nur einer APF-Installation aufbauen.
Details hierzu erfahren Sie unter <int:link pageid="134" />.
</li>
<li>
<strong>Offen für Weiterentwicklung</strong>:
Das APF folgt dem <em>open close principle</em>. Es stellt verschiedene Erweiterungspunkte zur Verfügung, lässt sich
jedoch nicht in seinen Grundfesten veränden. Die definierten <em>extension points</em> lassen jedoch nutzen, um
auch exotische Anforderungen umzusetzen bzw. die im Framework enthaltenen Komponenten gemäß den Projekt-Anforderungen
zu erweitern.
</li>
<li>
<strong>Open Source</strong>:
Das Adventure PHP Framework ist ein Open Source Produkt! Möchten Sie sich an der Weiterentwicklung beteiligen,
werden Sie ein Teil des <int:link pageid="149" />s und nehmen Sie mit uns <int:link pageid="034" /> auf oder
verfassen eine Beitrag im <a class="forum" href="${getBaseUrl(ForumBaseURL)}">Forum</a>. Wir freuen uns
auf Sie!
</li>
</ol>
<h3 id="Chapter-3-Das-1-x-1-des-APF"><a href="#Chapter-3-Das-1-x-1-des-APF">3. Das 1 x 1 des APF</a></h3>
<p>
In den folgenden Kapiteln können Sie grundsätzliche Dinge über das APF nachlesen.
</p>
<h4 id="Chapter-3-1-Was-brauche-ich-fuer-den-Start"><a href="#Chapter-3-1-Was-brauche-ich-fuer-den-Start">3.1. Was brauche ich für den Start?</a></h4>
<p>
Das Adventure PHP Framework ist ein für <a class="external" href="http://www.php.net">PHP</a> geschriebenes Framework
für die Entwicklung von Web-Applikationen. Aus diesem Grund benötigen Sie einen Web-Server der über ein PHP-Modul
verfügt. Hierzu eignen sich sowohl der de-facto Standard <a class="external" href="http://httpd.apache.org">Apache HTTP Server</a>
als auch beispielsweise <a class="external" href="http://nginx.org/en/docs/">nginx</a>.
</p>
<p>
Das APF 2.X setzt eine PHP-Version &gt; 5.3.0 voraus, da es im Vergleich zur 1.X-Reihe PHP-Namespaces nutzt. Gängige
Pakete wie beispielsweise <a class="external" href="http://www.apachefriends.org/de/xampp.html">XAMPP</a> verfügen
in den aktuellen Versionen bereits über die notwendige PHP-Version.
</p>
<p>
Um direkt mit dem Framework loszulegen wird empfohlen, eine <em>apf-demopack-*</em>-Datei herunter zu laden. Diese
beinhaltet nicht nur den Code des APF, sondern auch eine fertige und ohne Anpassungen lauffähige Beispielwebseite -
die <int:link pageid="074" />. Die Sandbox beinhaltet eine Reihe von Beispielen und Wizzards um sich mit dem APF
anzufreunden. Sollten Sie noch keine Erfahrung mit der Entwicklung mit dem APF besitzten, so eignet sich die Sandbox
ebenfalls als Start für die Entwicklung von eigenen Modulen oder Komponenten. Diese können Sie später natürlich ohne
weiteres in Ihrer eigenen Webseite einsetzen.
</p>
<p>
Um möglichst effektiv zu entwickeln empfiehlt das APF-Team den Einsatz von <a class="external" href="http://www.jetbrains.com/phpstorm/">PHPStorm</a>.
Die IDE von JetBrains unterstützt Sie mit Code-Completion, direktem Feedback bei Code-Fehlern und einer Integration
von <a class="external" href="http://xdebug.org/docs/remote">xdebug</a> zur Fehleranalyse Ihrer Anwendung.
</p>
<p>
Mit den beschrieben Dingen sind Sie nun bestens gerüstet um mit der Entwicklung zu beginnen!
</p>
<h4 id="Chapter-3-2-Wo-finde-ich-die-wichtigsten-Ressourcen"><a href="#Chapter-3-2-Wo-finde-ich-die-wichtigsten-Ressourcen">3.2. Wo finde ich die wichtigsten Ressourcen?</a></h4>
<p>
Die Seite des Adventure PHP Frameworks ist in zwei große Bereiche aufgeteilt: der <int:link pageid="008" />-Bereich
und die <int:link pageid="072" />.
</p>
<p>
Im Bereich <int:link pageid="008" /> finden Sie jeweils die Downloads des aktuellen Release und einen Verweis auf
experimentelle Versionen (siehe <int:link pageid="068" />). Suchen Sie nach der aktuell in der Entwicklung befindlichen Version,
so finden Sie diese unter <int:link pageid="068" /> zusammen mit einem Verweis auf einen aktuellen Snapshot.
</p>
<p>
Die Dokumentation zum Framework finden Sie unter <int:link pageid="072" />. Dort finden Sie wiederum folgende
Bereiche: der <int:link pageid="119" /> mit jeweils einem Kapitel zur jeder Komponente, dem Bereich
<int:link pageid="071" /> und der Sektion <int:link pageid="100" /> in dem Sie weiterführendes zum Framework und
zur Software-Entwicklung nachlesen können.
</p>
<p>
Zusätzlich stehen Ihnen noch das <a class="forum" href="${getBaseUrl(ForumBaseURL)}">Forum</a> und das
<a class="wiki" href="${getBaseUrl(WikiBaseURL)}/Hauptseite">Wiki</a> zur Verfügung.
</p>
<h4 id="Chapter-3-3-Welche-Komponenten-besitzt-das-APF"><a href="#Chapter-3-3-Welche-Komponenten-besitzt-das-APF">3.3. Welche Komponenten besitzt das APF?</a></h4>
<p>
Das Adventure PHP Framework besteht im Wesentlichen aus vier Bereichen: dem <em>core</em> in dem die Basis-Komponenten
beheimatet sind, den <em>tools</em> die für die Entwicklung nützliche Komponenten mitliefern und den <em>modules</em>
und <em>extensions</em>, die für den Einsatz fertige Module oder Erweiterungen enthalten.
</p>
<p>
Ein Release besteht typischerweise aus mehreren Pakete, die jedoch alle auf dem <em>apf-codepack-*</em> aufbauen, das
die Code-Basis beinhaltet. Neben diesem finden Sie <em>apf-configpack-*</em>-Dateien in der Liste der
<int:link pageid="008" />, das einen Satz an Beispiel-Konfigurationen pro Version ausliefert.
</p>
<p>
Suchen Sie für Ihren Einstieg nach Beispiel-Code, so können Sie sich die <int:link pageid="074" /> (Paket:
<em>apf-demopack-*</em>) oder die Beispiel-Pakete <em>apf-calc-example-*</em> (Taschenrechner), <em>apf-modules-example-*</em>
(Einbindung von dynamischen Modulen) oder <em>apf-vbc-example-*</em> - eine Beispiel-Implementierung für
<int:link pageid="086" /> - herunterladen.
</p>
<h3 id="Chapter-4-Ordner-Struktur"><a href="#Chapter-4-Ordner-Struktur">4. Ordner-Struktur</a></h3>
<p>
Wie in <a href="#Chapter-3-1-Was-brauche-ich-fuer-den-Start">Kapitel 3</a> aufgeführt beinhaltet das
<em>apf-codepack-*</em> die Code-Basis des Adventure PHP Framework. Das Paket ist wie folgt aufgebaut:
</p>
<gen:highlight type="code">
APF/
core/
extensions/
modules/
tools/
</gen:highlight>
<p>
Die Ordner <em>core</em> und <em>tools</em> beinhalten die Kern-Bestandteile des Frameworks. In <em>core</em>
befindet sich u.a. die Implementierung von <int:link pageid="098" /> (<em>/APF/core/pagecontroller/</em>) und
<int:link pageid="012" /> (<em>/APF/core/frontcontroller/</em>), in <em>tools</em> u.a. die Implementierung der
<int:link pageid="113" /> (<em>/APF/tools/form/</em>).
</p>
<p>
Der Ordner <em>modules</em> beinhaltet Module, die auf den <em>core</em>- und <em>tools</em>-Komponenten aufsetzen.
Dazu zählen u.a. die <int:link pageid="089" /> und das <int:link pageid="095" />, die in von Ihnen implementierte
Webseiten oder Web-Applikation eingebaut werden können.
</p>
<p>
Details zu den einzelnen Komponenten finden Sie auch in der <int:link pageid="002" />.
</p>
<h3 id="Chapter-5-Aufbau-einer-einfachen-Applikation"><a href="#Chapter-5-Aufbau-einer-einfachen-Applikation">5. Aufbau einer einfachen Applikation</a></h3>
<p>
Das vorliegende Kapitel zeigt Ihnen, wie Sie ausgehend von einem <em>apf-codepack-*</em>-Release vorgehen um eine
einfache Seite aufzubauen.
</p>
<div class="hint">
Weitere Inhalte zum Einstieg in das APF und zum Aufbau einer einfachen Webseite finden Sie auch unter
<int:link pageid="014" />, <int:link pageid="111" /> oder <int:link pageid="048" />. Weitere Tutorials sind auf der
Seite <int:link pageid="071" /> aufgelistet.
</div>
<h4 id="Chapter-5-1-Aufbau-der-Bootstrap-Datei"><a href="#Chapter-5-1-Aufbau-der-Bootstrap-Datei">5.1. Aufbau der Bootstrap-Datei</a></h4>
<p>
Wie in <a href="#Chapter-2-Prinzipien-und-Paradigmen">Kapitel 2</a> beschrieben, setzt das APF das
<em>Bootstrapping</em>-Konzept ein. Dies bedeutet, dass alle Anfragen Ihrer Besucher über eine zentrale Datei
(meist <em>index.php</em>, da diese im Webserver als <em>DirectoryIndex</em> konfiguriert ist) verarbeitet werden.
</p>
<p>
Um eine einfache Applikation zu erstellen, laden Sie sich bitte ein <em>apf-codepack-*</em>-Release herunter und
entpacken dieses in einem Ordner Ihrer Wahl unterhalb des <em>DOCUMENT_ROOT</em> des Web-Servers. Anschließend
erstellen Sie bitte die Datei <em>index.php</em> parallel zum <em>APF</em>-Ordner.
</p>
<p>
Um eine einfache Applikation bzw. Webseite zu erstellen starten Sie mit einem initialen Template, das dann die
unterschiedliche Bereiche Ihrer Applikation aufnimmt. Als Ausgangspunkt können Sie folgenden Inhalt für Ihre
<em>index.php</em> nutzen:
</p>
<gen:highlight type="php">
include('./APF/core/bootstrap.php');
use APF\core\singleton\Singleton;
use APF\core\frontcontroller\Frontcontroller;
$fC = Singleton::getInstance(Frontcontroller::class);
echo $fC->start('APF\site\templates', 'main');
</gen:highlight>
<p>
In der ersten Zeile wird die Datei <em>APF/core/bootstrap.php</em> eingebunden. Diese bindet die notwendigen
APF-Komponenten ein und konfiguriert diese initial.
</p>
<p>
Zeile 5 erstellt eine Instanz des <int:link pageid="012" /> und in der letzten Zeile wird die Request-Verarbeitung
unter Angabe des initialen Template gestartet. Das <em>echo</em> bewirkt, dass die Rückgabe - also die generierte
Seite - an den Benutzer zurückgegeben wird.
</p>
<div class="hint">
Weitere Hinweise zu den Konfigurationsmöglichkeiten in der <em>index.php</em> finden sich unter <int:link pageid="134" />,
<int:link pageid="137" />, <int:link pageid="069" /> und <int:link pageid="023" />.
</div>
<h4 id="Chapter-5-2-Aufbau-Basistemplate"><a href="#Chapter-5-2-Aufbau-Basistemplate">5.2. Aufbau des Basis-Templates</a></h4>
<p>
Templates spielen im Adventure PHP Framework eine zentrale Rolle. Wie im letzten Kapitel beschrieben, besitzt jede
Applikation ein Basis-Template und der <int:link pageid="098" /> nutzt Templates für seine Template-zentrierte
Umsetzung des <em>HMVC</em>-Pattern.
</p>
<p>
Im obigen Beispiel wurde der <int:link pageid="012" /> mit dem Basis-Template <em>main</em> aus dem Namespace
<em>APF\site\templates</em> gestartet. Er erwartet daher eine Datei <em>main.html</em> im Pfad <em>APF/site/templates</em>.
Die Ordner-Struktur ergänzt sich damit wie folgt:
</p>
<gen:highlight type="code">
APF/
core/
extensions/
modules/
site/
templates/
main.html
tools/
</gen:highlight>
<p>
Füllen Sie das Template nun mit
</p>
<gen:highlight type="html">
Meine erste Applikation mit dem APF!
</gen:highlight>
<p>
und rufen im Browser die <em>index.php</em> auf, so erhalten Sie den im Template eingetragenen Text.
</p>
<p>
Das hier besprochene Beispiel geht davon aus, dass die Standard-Konfiguration des APF nicht verändert wurde. Dies
betrifft insbesondere die <em>ClassLoader</em>-Konfiguration. Details zu den Anpassungsmöglichkeiten entnehmen Sie
bitte dem Kapitel <int:link pageid="154" />.
</p>
<div class="hint">
Weiterführende Beispiele zu Templates können den Kapiteln <int:link pageid="014"/> und <int:link pageid="047"/>
entnommen werden, das Tutorial <int:link pageid="048"/> gibt eine Einführung in das Erstellen von Web-Seiten und
-Applikationen.
</div>
<h3 id="Chapter-6-Basiskonfiguration"><a href="#Chapter-6-Basiskonfiguration">6. Basis-Konfiguration</a></h3>
<p>
Das Framework stellt für einige zentral genutzte Parameter eine Konfigurationsmöglichkeit über die
<int:link pageid="067" /> zur Verfügung. Sofern Sie die Parameter für Ihre Applikation anpassen möchten, nutzen Sie
bitte die <em>index.php</em>.
</p>
<p>
Die folgende Liste zeigt die relevanten Parameter im Namespace <em>APF\core</em>:
</p>
<ul>
<li>
<strong>Environment</strong>:
Das Merkmal <em>Environment</em> ermöglicht eine Unterscheidung der Konfiguration hinsichtlich der Umgebung, in
der eine Software eingesetzt wird (z.B. Test- oder Produktions-Umgebung). Details finden Sie im Kapitel
<int:link pageid="134" anchor="Chapter-2-1-Konfigurations-Schema" />.
</li>
<li>
<strong>InternalLogTarget</strong>:
Definiert den Namen des Standard-Log-Ziels für Framework-Fehlermeldungen. Details zur Anwendung und Konfiguration
finden Sie im Kapitel <int:link pageid="023" anchor="Chapter-3-1-Verwalten-von-LogWritern" />.
</li>
<li>
<strong>Charset</strong>:
Definiert den bei Zeichen-Operationen wie beispielsweise <em>htmlspecialchars()</em> verwendeten Zeichensatz.
Der Standard-Wert wird in der <em>boostrap.php</em> auf <em>UTF-8</em> festgelegt.
</li>
</ul>
<p>
Möchten Sie die genannten Parameter ändern, können Sie dies wie folgt in der <em>index.php</em> vornehmen:
</p>
<gen:highlight type="php">
include('./APF/core/bootstrap.php');
use APF\core\registry\Registry;
Registry::register('APF\core', 'Environment', 'TEST');
Registry::register('APF\core', 'InternalLogTarget', 'framework');
Registry::register('APF\core', 'Charset', 'UTF-16');
...
</gen:highlight>
<core:importdesign namespace="APF\modules\comments\pres\templates" template="comment" categorykey="de_013" />