PHP meets Maven – Teil 2

Posted on by

[Teil 1] [Teil 2] [Teil 3] [Teil 4]

Der erste Teil der Serie hat gezeigt, dass Maven den Paradigmen DRY und COC folgt. Aus diesem Grund sollte beim Anlegen eines Projekts die vorgegebene Verzeichnisstruktur eingehalten werden. Es ist durchaus möglich, von dieser Empfehlung abzuweichen, was aber zur Folge hat, dass der Konfigurationsaufwand in der pom.xml erheblich anwächst und sich schnell Fehler einschleichen können. Bild 1 stellt eine einfache Ordnerstruktur für ein typisches Maven-Projekt dar.

Die beschriebene Struktur ist bis auf wenige Abweichungen für sämtliche Maven-Projekte identisch. Der wichtigste Teil ist die pom.xml im Wurzelverzeichnis des Projekts. Das optionale Verzeichnis site enthält alle notwendigen Dateien, um eine Projekt-Homepage durch Maven generieren zu lassen. In src vermuten Sie zu Recht die verschiedensten Quelltextdateien. Im Ordner test befinden sich sämtliche Testdateien. Die resources-Verzeichnisse sind optional und besitzen eine besondere Funktion: Dort werden vor allem Konfigurationsdateien abgelegt, in denen Platzhalter zur Textersetzung eingebunden werden können. Um die Zusammenhänge schneller zu erkennen, sollten Sie einen Blick in die Konfigurationsdatei pom.xml werfen.

Project Object Model

Das Project Object Model (POM) bildet die zentrale Steuereinheit für Maven und enthält alle nötigen Informationen. Eine vollständige Übersicht der Konfigurationsmöglichkeiten kann auf der Maven-Projektwebseite nachgeschlagen werden. Beginnen wir zuerst mit den wichtigsten Einträgen:

<groupId>org.phpmaven</groupID>
<artifactId>php-libary</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>php</packaging>

Diese vier Zeilen sind der essenzielle Bestandteil einer jeden POM. Nun wird auch ersichtlich, was es mit den Platzhaltern $groupID und $artifactID in der Projektstruktur auf sich hat. Die artifactId ist der Projektname, dem eine Version zugeordnet wird. Bei der groupId handelt es sich um die Domain des Projekts.

Diese Informationen benötigt Maven, um die Artefakte im Dependency-Management organisieren zu können. Daraus ergibt sich beim Anlegen eigener Projekte die Forderung, dass die Kombination aus Domäne, Projektnamen und Version nicht mehrfach vergeben werden darf, da sonst vorhandene Artefakte im lokalen Repository ohne Rückfrage sofort überschrieben werden. Da Maven für Java-Projekte konzipiert wurde, nutzte es auch den in Java vorhandenen Mechanismus der Packages. Das bedeutet für den Wert org.phpmaven in groupId, dass Maven den Punkt als Trennzeichen interpretiert und erst org und darunter phpmaven als Verzeichnis erzeugt. Auf diese Weise können Sie Ihre Artefakte im lokalen Repository jederzeit aufspüren.

Für Java-Projekte ist es notwendig, anhand des Package-Namens, der sich aus groupId und artifactId zusammensetzt, eine Ordnerhierarchie zu erzeugen. In PHP-Projekten ist das Anlegen einer solchen Struktur nicht zwingend notwendig. Mit Blick auf künftige Mehrfachverwendung von Artefakten in den verschiedenen eigenen Projekten ist die Verwendung von Namespaces unumgänglich. Das Risiko von Namenskonflikten zwischen den Artefakten steigt mit der Anzahl der verfügbareren Artefakte.

Der Eintrag php weist Maven an, aus den Source-Files ein Phar-Archiv zu erzeugen. Es gibt neben php noch weitere Package-Typen, etwa zip und pom. Der Package-Typ pom erlaubt die Verwendung von Multi-Projekten, auf die später noch eingegangen wird. Listing 1 zeigt eine vollständige POM für ein einfaches PHP-Library-Projekt, das Sie als Abhängigkeit in anderen Projekten nutzen können. Dependencies werden in der POM im Bereich eingetragen. Im Beispiel ist das Test-Framework PHPUnit eingebunden. Die Angabe teilt Maven mit, dass es sich bei diesem Artefakt um ein PHP-Archiv handelt. Ohne diese Konfiguration würde Maven ein Java-Archiv (JAR) erwarten. Der Scope einer Dependency konfiguriert die Sichtbarkeit des Artefakts im Build Lifecycle. Es gibt vier unterschiedliche Scopes:

  • compile: Das Artefakt ist in allen Phasen verfügbar (Default).
  • provide: Das Artefakt ist nur bis zur compile-Phase sichtbar und wird nicht mit deployed. Dieser Scope ist vor allem für Java-Projekte wichtig, um die Ressourcen korrekt zu verlinken.
  • runtime: Diesen Scope verwenden Dependencies, die nur zur Laufzeit benötigt werden, was für PHP-Projekte die Regel darstellt. Artefakte, die mit runtime gekennzeichnet sind, werden mit der Anwendung zusammen deployed.
  • test: Abhängigkeiten, die mit diesem Scope konfiguriert sind, werden nicht mit deployed und sind nur für die test-Phasen des Build-Lifecycles sichtbar.
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.phpmaven</groupId></plugin>
    <artifactId>php-parent-pom</artifactId><plugin>
    <version>2.0-SNAPSHOT</version>
  </parent>
  
  <groupId>com.elmar.dott</groupId>
  <artifactId>validator</artifactId>
  <version>1.0-SNAPSHOT</version>
  <version>2.10</version>
  <packaging>php</packaging>
  
  <build>
		<plugins>
			<plugin>
				<groupId>org.phpmaven</groupId>
				<artifactId>maven-php-plugin</artifactId>
				<version>${phpmaven.plugin.version}</version>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-site-plugin</artifactId>
				<version>3.0</version>
				<inherited>true</inherited>
				<configuration>
					<reportPlugins>
					<plugin>
						<groupId>org.phpmaven</groupId>
						<artifactId>maven-php-plugin</artifactId>
						<version>${phpmaven.plugin.version}</version>
						<reportSets>
							<reportSet>
								<reports>phpdocumentor</reports>
							</reportSet>
						</reportSets>
					</plugin>

					<plugin>
						<groupId>org.phpmaven</groupId>
						<artifactId>maven-surefire-report-plugin</artifactId>
						<version>${phpmaven.plugin.version}</version>
						<reportSets>
							<reportSet>
								<reports>report-only</reports>
							</reportSet>
						</reportSets>
					</plugin>
					</reportPlugins>
				</configuration>
			</plugin>
		</plugins>
	</build>
	
	<dependencies>
		<dependency>
			<groupId>de.phpunit</groupId>
			<artifactId>PHPUnit</artifactId>
			<version>3.6.10</version>
			<type>phar</type>
			<scope>test</scope>
		</dependency>
	</dependencies>  
</project>
XML

Nachdem Sie nun eine Projektstruktur und die dazugehörige POM haben, wird es Zeit, Maven in Aktion zu erleben. Die Idee ist, eine Bibliothek zu erzeugen, die Benutzereingaben validiert. Dieses Artefakt kann dann später von Ihnen dahingehend erweitert werden, in Ihren Projekten an verschiedensten Stellen Benutzereingaben auf Gültigkeit zu überprüfen.

Mögliche Erweiterungen könnten etwa Validierungen von ISBN- und IBAN-Nummern sein. Um ohne Verzögerung zu beginnen, können Sie das fertige Projekt von der Website herunterladen und in einer aktuellen IDE Ihrer Wahl öffnen.

Das Artefakt besteht aus der Klasse Validator mit den beiden Methoden makeSecure() und validate(). Die Methode makeSecure() soll HTML-Tags escapen und Slashes sowie Backslashes aus dem übergebenen String entfernen. validate() prüft eine Eingabe gegen einen regulären Ausdruck auf Gültigkeit. In der Klasse sind bereits einige RegEx als Konstanten definiert. Damit haben wir schon alles, um erste Resultate zu sehen.

Validierungen

Öffnen Sie eine beliebige Konsole und navigieren Sie in das Projektverzeichnis zur POM. Nun müssen sie lediglich mvn package eingeben. Diese Anweisung bewirkt, dass Maven den Build Lifecycle bis zur Phase package abarbeitet. Die nachfolgenden Phasen install und deploy werden nicht aufgerufen. Die Phase install kopiert das erzeugte Artefakt direkt in das lokale Repository und deploy würde zusätzlich das Artefakt in einem Remote-Repository ablegen. Für den Moment genügt es uns, das Phar-Archiv erzeugt zu haben.

Wegen des POM-Eintrags install unterhalb von <build> genügt es, lediglich mvn install in der Konsole zu schreiben, um das erzeugte Artefakt ins lokale Repository zu kopieren. Nachdem mvn package ausgeführt wurde, hat Maven im Projektverzeichnis einen temporären Ordner namens target erzeugt und quittiert die Ausgabe mit BUILD SUCCESS. In dem neu angelegten Verzeichnis sind sämtliche generierten Dateien abgelegt, unter anderem auch das erwünschte Phar-Archiv.

Um negative Synergien zu vermeiden, sollte das target-Verzeichnis vor einem jedem Build gelöscht werden. Das erledigt die Anweisung mvn clean.

Das erzeugte Phar-Archiv lässt sich mit den folgenden Zeilen in eine Applikation einbinden:

require_once 'phar://validator-1.0-SNAPSHOT.phar/index.php';
use de\banaalo\validator\Validator as Validator;

$validator = new Validator();
$input = 12345;

echo $validator->validate
($validator->NUMBER, $input);
PHP

Der Trick besteht darin, sämtliche Klassen des Archivs in der Datei src/main/php/index.php mittels include bekannt zu machen. Bei dieser Herangehensweise muss lediglich die index.php wie in der ersten Zeile des Listings geladen werden. Anschließend ist noch der Namespace aufzulösen und dann können die Klassen des Artefakts wie gewohnt verwendet werden.

Testgetriebene Entwicklung

Dank des Extreme Programming (XP) hat das Testen von Sourcecode mittlerweile einen sehr zentralen Stellenwert im Software-Entwicklungsprozess erhalten. Implementierte Funktionalität wird nicht erst nach Beendigung der Entwicklung auf Korrektheit hin überprüft, sondern schon während der Entwicklungsphase. Eine etablierte Form des Testens sind Unit-Tests, wofür das Framework PHPUnit von Sebastian Bergmann als Dependency in den Maven-Build-Lifecycle eingebunden ist. Die aktuell verwendete Version von PHPUnit ist 3.6.10. Ein ausführliche Übersicht zu PHPUnit bietet das Manual des Frameworks.

Sämtliche Testfälle sind im Verzeichnis test/php abzulegen. Wenn eine Verzeichnisstruktur für die Sourcen erzeugt wurde, sollte diese ebenfalls für die Testfälle übernommen werden. Eine weitere Konvention ist, die Testklassen analog der zu testenden Klassen zu benennen und das Postfix test anzufügen.

Zur Klasse Validator existiert die korrespon-ierende Klasse ValidatorTest, die von PHPUnit_Framework_TestCase abgeleitet ist. Um später in der Test-Auswertung bei Fehlern das betroffene Fragment schneller identifizieren zu können, sollten die Methoden sprechende Namen haben. Im vorgestellten Beispielprojekt wird die Validierung von Zahlen durch den Validator getestet. Dazu existiert die Methode testNumberValidation(). Um Klassen testen zu können, sollte schon während der Implementierung darauf geachtet werden, dass nur ein Einstiegspunkt und ein definierter Ausstiegspunkt vorhanden ist. Mehr als das Erstellen der Testfälle und das Einbinden von PHPUnit als Abhängigkeit ist nicht notwendig. Beim Ausführen von Maven werden nun jedes Mal alle Testfälle abgearbeitet. Falls ein Test fehlschlägt, wird der Build mit einer Fehlermeldung abgebrochen.

API-Dokumentation auf Knopfdruck

Ein weiterer wichtiger Aspekt in der SoftwareEntwicklung ist das Erzeugen einer aussagekräftigen API-Dokumentation. Für diese Aufgabe ist in Maven der Site-Lifecycle vorgesehen. Um den phpDocumentor dem Site-Lifecycle bekannt zu machen, muss die Konfiguration des site-Plug-ins überschrieben werden. In der Beispiel-POM ist dies bereits geschehen und deswegen muss die POM nicht weiter angepasst werden. Wie auch bei PHPUnit ist es nicht notwendig, das Tool phpDocumentor auf dem System zu installieren. Auf der Homepage des php Documentors ist das Werkzeug gut dokumentiert. Auf der Webseite ist unter anderem eine Übersicht der möglichen Annotationen zu finden. Um die Dokumentation zu erzeugen, muss der Site-Lifecycle mit der Anweisung mvn site ausgeführt werden.

Wie alle anderen durch Maven erzeugten Dateien wird auch die fertige API-Dokumentation im target-Verzeichnis abgelegt.

Jedes Mal aufs Neue von Hand eine Projektstruktur anzulegen ist mühsam. Damit das Erzeugen neuer Projekte automatisiert geschehen kann, bietet Maven den Mechanismus der Archetypen. Ein Archetyp erzeugt eine vorgegebene Verzeichnisstruktur und die dazugehörige POM. Für PHP existieren derzeit drei verschiedene Archetypen: library, web und zend, die im Lauf der Zeit noch erweitert werden. Der nachfolgende Code-Ausschnitt zeigt die benötigte Anweisung, um einen Archetyp auszuführen:

mvn archetype:generate \
  -DarchetypeGroupId=org.phpmaven \
  -DarchetypeArtifactId=php5-lib-archetype \
  -DarchetypeVersion=2.0.0-beta-3\
  -DgroupId=de.banaalo \
  -DartifactId=validator \
  -Dversion=1.0-SNAPSHOT
Bash

Falls Sie aus einem bereits bestehendem Projekt einen Archetyp erzeugen wollen, können Sie mvn archetype:create-from-project ausführen. Es kann auch vorkommen, dass anschließend der generierte Archtyp von Maven nicht gefunden wird. Der Grund ist in der Datei archetypecatalog.xml zu suchen. Um den neuen Archetyp in den Katalog aufzunehmen, ist die Anweisung mvn archetype:crawl auszuführen. Ein manuelles Editieren dieser Datei ist nicht notwendig.

Fazit

Library-Projekte sind Artefakte, die Funktionalitäten kapseln und diese Funktionalitäten in anderen Projektformen als Abhängigkeit zur Verfügung stellen. Im nächsten Teil der Serie wird gezeigt, wie Homepage-Projekte mit Maven verwaltet werden können, die wiederum Artefakte einbinden. In diesem Zusammenhang wird auch auf Multi-Projekte und deren Verwendung eingegangen. Sie erfahren auch, wie Sie erzeugte Artefakte für andere Entwickler in einem Remote-Repository verfügbar machen.

Maven: Überblick für Entwickler

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert