Phing und Freunde
Ein Vorschlag für ein Projektsetup, dass die Vorzüge der verwendeten Tools gut nutzt und einfach in einem Versionskontrollsystem wie CVS oder SVN verwaltet werden kann.
Hier möchte ich ein kleines Beispiel geben wie ein Projektsetup für ein PHP-Projekt aussehen könnte, dass Phing für den Build-Prozess und PHPUnit 2 für Unittests und Testreports (Beispiel) verwendet. Zur Dokumentation der Schnittstellen und des Codes soll PHPDocumentor verwendet werden. Auch das Verpacken des Projekts zur Weitergabe als zip- oder tar.gz-Datei soll möglich sein.
Zum Verständnis
Die einzelnen Tools und deren Bedienung werden hier nicht weiter erörtert. Es geht darum das Zusammenspiel der Tools in einem möglichen Projektsetup zu betrachten. Die Tools, zumindest Phing, sollten also schon bekannt sein.
Phing
Phing ist ein Build-Tool, ähnlich Make für C++ oder Ant für Java, dass einen automatisierten Build-Prozess für PHP-Projekte ermöglicht. Da Phing vollständig in PHP implementiert ist, ist es auf jeder Plattform mit PHP-Interpreter ausführbar. Dies hat den Vorteil, dass den Entwicklern bezüglich des Betriebssystems keine Vorgaben mehr gemacht werden müssen. Es wird lediglich eine funktionierende Phing Installation benötigt um das Projekt aus den Quellen zu erzeugen. Phing installiert man am einfachsten über PEAR. Der Befehl dazu ist pear install phing-2.0.0b1-pear.tar.gz
PHPUnit 2
PHPUnit 2 ist ein Port des JUnit-Frameworks nach PHP5 von Sebastian Bergmann. Grade im Bereich von Skriptsprachen sind Unittests für größere Projekte nahezu unentberlich, da alle Programmierfehler bei diesen Sprachen erst zu Laufzeit auftreten. Es gibt keine Einrichung wie einen Compiler, der viele Fehler im Vorfeld findet. Auch PHPUnit 2 ist als PEAR-kompatibles Projekt erhältlich. Der Befehl zu Installation ist pear install PHPUnit2
PHPDocumentor
Der phpDocumentor ist ein Tool, dass so ähnlich wie javadoc funktioniert. Im Code können Kommentare in einem bestimmten Format hinterlassen werden. Aus diesen Kommentaren kann dann weitere Entwicklerdokumentation und im Falle von phpDocumentor sogar Dokumentation für den Endbenutzer generiert werden. PHP-Documentor ist ein PEAR-kompatibles Projekt. Nachdem man es heruntergeladen und entpackt hat, kann es über den Befehl pear install /path/to/phpDocumentor-1.2.2/package.xml installiert werden. Eine Referenz der möglichen Dokumentationstags findet sich unter http://phpdoc.org.
Das Projektsetup
Die vorgeschlagene Verzeichnisstruktur ist zum Teil an die Vorschläge des Maven-Projektes angelehnt. Es gibt zwei parallel zu pflegende Quellcodeverzeichnisse. Alle weiteren Resourcen werden im Zuge des Build-Prozesses mit dem Quellcode zusammen verpackt.
Die wichtigsten Verzeichnisse des Setups sind:
src/
php/
classes/
res/
tests/
classes/
res/
res/
lib/
dev-lib/ (optional)
target/
build/
docs/
dev-docs/
compile-help.txt
build.properties-template
design-docs
...
build.xml
build.properties
Es gibt mit php/ und tests/ zwei parallele Verzeichnisse unterhalb von src/. Hier werden Quellcode, Testcode und Konfigurationsdateien abgelegt. Augeliefert wird nur das src/php Verzeichnis. Das gesamte src/-Verzeichnis steht voll unter Versionskontrolle. Das Verzeichnis res/ enthält Resourcen wie zum Beispiel Grafiken oder auch Templates etc. Das Verzeichnis lib/ enthält externe Bibliotheken, die benötigt werden. dev-lib/ ist optional. Hier können Bibliotheken einbezogen werden, die nur für den Buildprozess benötigt werden. In das Verzeichnis target wird das vollständig generierte Projekt, die Dokumentation und die Testergebnisse geschrieben. Dieses Verzeichnis steht nicht(!) unter Versionskontrolle, da alle Inhalte aus dem Quellcode generiert werden. Die Datei build.xml steuert den Buildprozess mit Phing. build.properties enthält platformspezifische Parameter, die jeder Entwickler individuell pflegt. Die Datei build.properties steht nicht unter Versionskontrolle. Sie ist für jede Arbeitskopie individuell zu erstellen.
Der Buildprozess
Es gibt in jedem Projekt viele verschiedene sogenannte Build-Targets. Das sind automatisierte Skripte, die ein bestimmtes Artifakt erzeugen. Das Beispielprojekt versteht, sofern alle Tools korrekt installiert sind, die folgenden Befehle:
phing clean- Säubern des Projekts. Löschen destarget-Verzeichnisses.phing tests- Ausführen der Unittestsphing testreport- Erzeugen der Testreportsphing build- Den Anwendungscode nachtarget/buildkopierenphing docs- Die API-Docs erzeugenphing all- Alles ausführen.phing dist- Zip- und tar.gz-Dateien erzeugen
Die Aktionen des Buildprozesses dist in chronologischer Reihenfolge:
- Löschen des
target/-Verzeichnisses - Neu erstellen des
target/-Verzeichnisses - Ausführen der Tests
- Generieren von Testreports im Targetverzeichnis
- Generieren der Dokumentation
- Zusammenkopieren des Anwendungscodes und der Bibliotheken in das
target/-Verzeichnis - Erstellen von ZIP- und tar.gz-Dateien
Download
Das Beispielprojekt tut selbst nichts sinnvolles. Es geht schließlich um ein beispielhaftes Projektsetup und nicht unbedingt um den Code. Enthalten sind lediglich eine Klasse und eine korrespondierende Testklasse. Gezeigt wird eine benutzbare build.xml, die die Möglichkeiten der eingesetzten Tools recht gut ausnutzt. Das Verzeichnissetup ist recht gut mit CVS oder SVN einsetzbar.
In der Datei build.properties, die die Anpassungen für die einzelnen Arbeitskopien enthält ist noch der Pfad zur eigenen Phing-Installation anzugeben.
Was bleibt?
Kennt man die Tücken der einzelnen Tools, die in den Buildprozess eingebunden sind, kann man ein funktionales, einfaches und zugleich portables Projektsetup erstellen, das sowohl die Möglichkeiten des Buildtools als auch die des Versionskontrollsystems gut ausnutzt. Auf dem Weg zum wirklich guten Projektsetup fehlen allerdings noch einige Kleinigkeiten:
- Support für Code-Coverage Reports.
- Einen Zwischenschritt in den Build einbauen. Zum Beispiel um Textersetzungen am Code vorzunehmen oder gar um Code zu generieren.
- Support für Integrations- bzw. Akzeptanztests
- <InsertAFeatureHere>
Als Gundlage für eine eigene, projektspezifische Entwicklung sollte dies aber reichen. Kommentare, Kritik, Vorschläge zu diesem Setup an adam<dot>mansfeld<at>gmx<dot>de.