Bevor es mit der eigentlichen Entwicklung losgehen kann, müssen die eZ Components installiert werden. In diesem Kapitel wird die Installation und Einrichtung vorgenommen und die wichtigsten Konzepte in eZ Components werden erläutert.

2 Einführung in eZ Components

Die Installation der eZ Components-Bibliothek benötigt nur geringen Aufwand, bis eine funktionsfähige Umgebung bereitsteht. Allerdings gibt es hier, wie so oft, mehrere Wege die nach Rom führen, sowie verschiedene Versionen der Bibliothek, zwischen denen Sie entscheiden können. Sowohl die Installations- als auch die Versionsvarianten werden in diesem Kapitel vorgestellt. Im Anschluss daran werden Sie sehen, welche Konfigurationsschritte noch nötig sind, um eZ Components einzubinden, und wie Sie den integrierten Autoload-Mechanismus für Ihre eigenen Projekte nutzen können. Zusätzlich werden Sie mehr erfahren über den Inhalt der Base-Komponente, wie die weiteren Komponenten darauf zugreifen und was Sie selbst mit den enthaltenen Features anfangen können. Hierin inbegriffen ist eine Vorstellung der wichtigsten Konzepte, die Sie an vielen Stellen in eZ Components wiederfinden. Schließlich werden wir eine Einführung in die online verfügbare Dokumentation für eZ Components sowie einige praktische Hinweise geben, wie Sie sich selbst an eZ Components beteiligen können.

2.1 eZ Components installieren

Zur Installation von eZ Components haben Sie die Wahl zwischen drei Varianten. Zum einen können Sie einzelne Komponenten oder das komplette Paket mit Hilfe des PEAR-Installers installieren. Die zweite Möglichkeit ist, das Komplett-Paket der eZ Components von der eZ Systems-Webseite herunterzuladen und manuell zu installieren. Schließlich bleibt Ihnen die Wahl, einzelne Komponenten in beliebiger Version, eingeschlossen die aktuelle Entwicklungsversion oder das Gesamtpaket direkt aus dem Subversion-Repository (SVN) auszuchecken. Zunächst sollen Sie aber etwas über das Versionierungsschema der Bibliothek erfahren, um sich für eine Version entscheiden zu können.

Die in diesem Buch vorgestellte Version des Komplettpakets ist 2007.1. Sie finden den kompletten Sourcecode sowie die Onlinedokumentation auch auf der beiliegenden CD und können diese Version installieren, wie in Abschnitt 2.1.3, »Das Gesamtpaket herunterladen«, beschrieben.

2.1.1 Versionierung

eZ Components folgen zwei unterschiedlichen Versionierungsschemata: Jede Komponente trägt eine eigene Versionsnummer, und das Gesamtpaket, in dem alle stabilen Komponenten enthalten sind, trägt ebenfalls eine eigene Nummer. Beide Versionsnummern folgen unterschiedlichen Formaten.

Die Versionsnummer einer einzelnen Komponente besteht aus drei Zahlen, getrennt jeweils durch einen Punkt. Die erste Nummer gibt an, in welchem Haupt-Release-Zyklus (englisch: major realease cycle) sich die Komponente befindet. Nur bei Änderung dieser Versionsnummer darf sich die API der Komponente verändern, ansonsten müssen alle Funktionen, Klassen und Methoden genau so funktionieren, wie es in den Vorgängerversionen der Fall war. Zwar dürfen jederzeit Features hinzukommen, bereits vorhandene Features sind aber von Änderungen ausgenommen. Die zweite Nummer identifiziert das sogenannte Feature-Release. Erhöht sich dessen Zahl, bringt das Release neue Features mit sich, ganz im Gegensatz zur dritten Zahl, welche den Namen Minor-Release trägt. Wird die Minor-Release-Zahl erhöht, handelt es sich um ein Release, das lediglich der Fehlerbereinigung dient (englisch: bug fixing release).

Handelt es sich nicht um ein stabiles Release, wird der Versionsnummer noch der Status der Komponente in diesem Release angehängt sowie die laufende Nummer in diesem Status. Gebräuchliche Statusnamen sind z. B. beta1 für das erste Beta-Release einer neuen Version oder rc2 für den zweiten Release-Kandidaten. ConsoleTools-1.3.0beta1 bezeichnet also die erste Beta-Version des Feature-Release 3 der Komponente ConsoleTools, welche sich im Haupt-Release-Zyklus 1 befindet, und Cache-1.1.4 bezeichnet das vierte Bugfix-Release der ersten Feature-Erweiterung im ersten Haupt-Release für die Cache-Komponente.

Das zweite Versionierungsschema betrifft das Komplettpaket eZ Components, welches jeweils die aktuellsten Versionen aller stabilen Komponenten zusammenfasst und zwei Mal im Jahr erscheint: Einmal Ende des Jahres und einmal um die Mitte des Jahres, meist zur eZ Conference. Die Release-Zyklen der einzelnen Komponenten orientieren sich grob an diesen beiden Release-Terminen, können aber auch unabhängig vom Hauptpaket herausgegeben werden, was meist zur Fehlerbereinigung geschieht.

2.1.2 Installation per PEAR

Das PEAR-Projekt [http://pear.php.net ] bietet neben einer großen Zahl an teils sehr ausgefallenen PHP-Klassen auch eine generelle Installationsinfrastruktur an, mit der sowohl in PHP geschriebener Programmcode als auch PHP-Erweiterungen, welche in C oder C++ geschrieben sind, installiert werden können. Seit PHP-Version 4.3 wird der PEAR-Installer standardmäßig mit jeder Distribution der Sprache ausgeliefert und muss explizit deaktiviert werden, wenn er nicht gewünscht wird. Der Installer funktioniert sowohl unter Windows als auch auf allen Unix- und Unix-ähnlichen Systemen, wie zum Beispiel Linux oder Mac OS X. Im Folgenden werden wir, der Einfachheit halber, nur noch von Unix-Systemen sprechen, wenn eine Unterscheidung gegenüber Windows benötigt wird.

Der übliche Weg mit dem PEAR-Installer zu arbeiten, führt über die Konsole und das Programm pear beziehungsweise pear.bat unter Windows. Es existieren auch graphische Bedienoberflächen für den Installer, welche aber alle recht instabil und schlecht gepflegt sind. Die reine Eingabe dieses Kommandos auf Ihrer Konsole sollte zur Ausgabe eines Hilfetextes führen, der Sie über die Funktionen des PEAR-Installers aufklärt. Ist dies nicht der Fall, kann es entweder sein, dass PEAR gar nicht installiert ist (was in den wenigstens Fällen vorkommt) oder die Programmdatei im aktuellen Pfad nicht gefunden wurde. Ist dies der Fall, können Sie entweder versuchen selbst herauszufinden, wo in Ihrem System PEAR installiert ist, oder PEAR manuell neu installieren, was im PEAR-Handbuch [http://pear.php.net/manual/de/installation.getting.php ] ausführlich beschrieben ist.

Sollten Sie es nicht auf Anhieb schaffen, Ihren PEAR-Installer zu starten, empfehlen wir Ihnen, auf eine der anderen Installationsmethoden zurückzugreifen. Diese sind ebenso einfach und benötigen kein spezielles Installationsprogramm.

Im Folgenden setzen wir voraus, dass der PEAR-Installer korrekt auf Ihrem System funktioniert. Ist dies nicht der Fall, gibt der Kasten zum Thema »PEAR-Installer« einige Hilfestellungen. Zur Installation des aktuellen Komplettpakets geben Sie auf Ihrer Konsole die folgenden Befehle ein:

$ pear channel-discover components.ez.no
$ pear install ezc/eZComponents

Das $ Zeichen steht hierbei für Ihren Konsolen-Prompt, der von System zu System unterschiedlich aussehen kann. Unter Windows sehen Sie vermutlich etwas wie C:\ >, auf Unix-Systemen ist ein Prompt der Art dotxp@tango ~ $ gebräuchlich.

Die erste Zeile fügt den eZ Components-Kanal, welcher die Komponentenpakete bereitstellt, Ihrer PEAR-Installation hinzu. Dieses Kommando brauchen Sie nur einmalig auf jedem System auszuführen. Mit dem zweiten Kommando installieren Sie das komplette eZ Components-Paket in der aktuellsten, stabilen Version. Wollen Sie nur einzelne Komponenten und nicht das komplette Paket installieren, so ist dies mit PEAR ebenfalls möglich. Dazu wandeln Sie die zweite Kommandozeile ab und verlangen statt des Pakets eZ Components ein Komponentenpaket über den Namen der Komponente. Wissen Sie den Namen der benötigten Komponente nicht, können Sie den PEAR-Installer anweisen, Ihnen alle Pakete des eZ Components-Kanals anzuzeigen:

$ pear remote-list -c ezc

Als zusätzliche Information erhalten Sie jeweils die aktuelle Versionsnummer zu jeder Komponente. Der Befehl

$ pear install ezc/ConsoleTools

installiert dann beispielsweise die Komponente ConsoleTools auf Ihrem System. Entsprechend können Sie mit anderen Komponenten verfahren. In einigen wenigen Fällen hängen Komponenten von anderen Komponenten ab und der PEAR-Installer verweigert standardmäßig die Installation, solange nicht alle Abhängigkeiten erfüllt sind. Man kann das Installationsprogramm anweisen, alle benötigten Pakete direkt mit zu installieren, wozu der Schalter -a dient. Zum Beispiel installieren Sie die Komponente ImageConversion und die von ihr benötigte Komponente ImageAnalysis zusammen folgendermaßen:

$ pear install -a ezc/ImageConversion

Eine weitere Möglichkeit besteht darin, eine Komponente in einer bestimmten Version zu installieren, falls Sie nicht die aktuellste Version wünschen. So ist es nicht nur möglich, ältere Versionen einer Komponente, sondern ebenfalls instabile Versionen zu installieren, obwohl Ihr PEAR-Installer Letzteres in der Standardeinstellung normalerweise nicht tut und sich auf stabile Versionen beschränkt.

Das Kommando

$ pear install Graph-1.0

installiert die Komponente Graph in der Version 1.0, während der Befehl

$ pear install Graph-beta

die letzte verfügbare Beta-Version installiert.

Ein weiteres praktisches Feature des PEAR-Installers erlaubt es Ihnen, alle installierten Pakete auf einen Schlag zu aktualisieren, falls Updates zur Verfügung stehen. Dies ist wohl der größte Vorteil der Installation über PEAR. Statt auf ein neues Gesamtpaket warten zu müssen, können Sie automatische Updates laufen lassen. Für den eZ Components-Kanal benutzen Sie dazu den folgenden Befehl:

$ pear upgrade-all -c ezc

Wenn Sie nun eZ Components erfolgreich mittels PEAR-Installer auf die Festplatte geholt haben, müssen Sie nur noch sicherstellen, dass der Pfad zu Ihrer PEAR-Installation zum Inkludieren von PHP-Dateien zur Verfügung steht. Am einfachsten ist dies, wenn der Pfad in der PHP-Direktive include_path enthalten ist. Mit folgenden Befehlen können Sie herausfinden, ob dies zutrifft:

$ pear config-show
$ php -r 'echo ini_get( "include_path" );'

Der erste Aufruf zeigt die aktuellen Konfigurationseinstellungen des PEAR-Installers, bei denen Sie nach dem Wert für php_dir suchen, denn diese Einstellung enthält das Verzeichnis, in das der PEAR-Installer seine Pakete installiert. Der zweite Aufruf gibt die include_path-Direktive Ihrer PHP-Installation aus, wie sie in der Datei php.ini definiert ist. Diese Einstellung kann mehrere Pfade enthalten, die auf Unix-Systemen jeweils durch einen Doppelpunkt, in Windows durch ein Semikolon getrennt sind. Exemplarisch könnte eine entsprechende Ausgabe (an dieser Stelle gekürzt) so aussehen:

$ pear config-show
Configuration (channel pear.php.net):
=====================================
Auto-discover new Channels     auto_discover    <not set>
Default Channel                default_channel pear.php.net
[...]
PEAR directory                 php_dir          /usr/share/php
[...]
$ php -r 'echo ini_get( "include_path" );'
.:/usr/share/php

Listing 2.1 Ausgabe des PEAR-Installers

Im dargestellten Fall ist alles in bester Ordnung, da der include_path nur das aktuelle Arbeitsverzeichnis und das PEAR-Verzeichnis enthält. Wichtig für Ihren Check ist, dass Letzteres zutrifft. Ist dies nicht der Fall, gibt es verschiedene Wege, damit umzugehen: Zum einen können Sie Ihre php.ini-Datei anpassen, zum anderen die include_path-Direktive mittels ini_set() am Anfang Ihres Programms manipulieren oder einfach über den absoluten Pfad die benötigte Datei der Base-Komponente laden. Mehr dazu erfahren Sie in Abschnitt 2.2, »Autoload konfigurieren«.

Bei einer Installation mittels PEAR-Installer unterscheidet sich die Verzeichnisstruktur von der aller anderen Installationsvarianten, bedingt durch die vom Projekt vorgeschriebenen Strukturen. Den Quellcode der eZ Components finden Sie im Unterverzeichnis ezc/ unterhalb des PEAR-Basisverzeichnisses, was Sie beim Einbinden der Base-Komponente unbedingt beachten müssen. Des Weiteren befindet sich die Dokumentation der einzelnen Komponenten, nicht wie sonst üblich im Quellcode-Verzeichnis der Komponente selbst, sondern im gesonderten Verzeichnis docs/.

Wie Sie sehen, ist die Installation mittels PEAR-Installer recht einfach und hat den Vorteil, dass Pakete automatisiert aktualisiert werden können. Allerdings bringt sie auch Nachteile mit sich, falls der PEAR-Installer einmal nicht wie erwartet funktioniert, und es kann umständlich sein, den korrekten include_path für Ihre Installation zu ermitteln.

2.1.3 Das Gesamtpaket herunterladen

Die zweite Möglichkeit, eZ Components zu installieren, besteht darin, das aktuelle Komplettpaket direkt von der eZ Systems-Webseite herunterzuladen. Hierbei haben Sie allerdings nicht die Wahl, nur einzelne Komponenten zu installieren, sondern müssen immer das Komplettpaket nehmen. Sie finden den Download-Bereich unter http://ez.no/ezcomponents/download.

Auf dieser Seite finden Sie sämtliche bisher verfügbaren Komplettpakete von eZ Components; die aktuelle, stabile Version zu oberst. Für Ihre ersten »Gehversuche« sollte die hier besprochene Version 2007.1 passend sein. Sie können aber auch eine aktuellere Versionsnummer verwenden. Weiter unten auf der Seite im Bereich Unsupported eZ Components finden Sie auch Beta-Versionen und Release-Kandidaten. Die Bezeichnung unsupported sagt hierbei lediglich aus, dass für diese Versionen kein kommerzieller Support verfügbar ist, da sie nicht als stabil und voll funktionsfähig erachtet werden und somit nicht für den produktiven Einsatz gedacht sind. Allerdings ist selbst die Qualität der Beta-Versionen schon recht hoch, sodass Sie zum späteren Testen ruhig mal einen Download riskieren sollten.

Um loszulegen wählen Sie das für Sie am besten geeignete Archiv-Format aus und laden das aktuelle Komplettpaket herunter. Für Windows-Benutzer ist das geeignetste Format vermutlich ZIP, unter Unix neigt man eher zu TAR-Archiven, die mit BZIP2 komprimiert wurden. Nach dem erfolgreichen Herunterladen entpacken Sie das Paket in einen Ordner Ihrer Wahl.

In diesem Ordner finden Sie nach dem Entpacken nicht nur alle Komponenten in jeweils einem eigenen Unterordner, sondern auch die Dateien ChangeLog, description.txt und LICENSE. ChangeLog enthält alle Änderungen seit dem letzten Gesamtpaket-Release, sortiert nach Komponenten, deren Beschreibungen in der Datei description.txt zu finden sind. LICENSE enthält eine Kopie der New-BSD-Lizenz, unter der eZ Components herausgegeben werden.

In jedem Komponenten-Ordner befinden sich jeweils drei weitere Unterordner sowie ebenfalls ChangeLog und description.txt, zusammen mit einer Datei CREDITS, welche alle an der Komponente mitwirkenden Personen auflistet. In einigen Fällen ist daneben noch eine README-Datei enthalten, die Sie auf Besonderheiten und gegebenenfalls auf Limitierungen der Komponente hinweist. Die drei Verzeichnisse enthalten den eigentlichen Quellcode der Komponente (src/), Beispiele und ein ausführliches Tutorial im Verzeichnis docs/ sowie die Unit-Tests der Komponente unter tests/. Ein zusätzlicher Ordner autoload/ auf gleicher Ebene wie die Komponenten-Verzeichnisse enthält die Autoload-Dateien für alle Komponenten. Mehr zum Thema Autoload können Sie in Abschnitt 2.2, »Autoload konfigurieren«, erfahren, welcher sich im Detail mit diesem Thema beschäftigt.

Auch bei dieser Methode der Installation sollten Sie darauf achten, dass der eZ Components-Ordner in Ihrer PHP-include_path-Direktive eingetragen ist. Ansonsten müssen Sie später die Base-Komponente über ihren kompletten Pfad referenzieren oder die Direktive mittels ini_set() im Programm anpassen.

Der Vorteil dieser Installationsvariante ist ihre Einfachheit, denn das bloße Herunterladen und Entpacken reicht aus, um eZ Components zu installieren. Allerdings hat auch diese Variante Nachteile: Für jedes Update von eZ Components müssen Sie diesen Vorgang manuell wiederholen und Sie können ausschließlich Releases des Gesamtpakets installieren, jedoch keine einzelnen Komponenten oder spezielle Updates.

2.1.4 SVN

Die letzte Methode, eZ Components zu installieren, benutzt Subversion (SVN), ein Programm zum Verwalten von unterschiedlichen Entwicklungsständen und Versionen einer Software. Sollten Sie keine Erfahrung mit Subversion haben, empfehlen wir Ihnen einen Besuch auf http://subversion.tigris.org/. Subversion muss auf Ihrem Rechner installiert sein, um die folgenden Installationsschritte nachzuvollziehen.

Zunächst müssen Sie sich entscheiden, welche Version von eZ Components Sie installieren möchten. Neben der aktuellen Entwicklungsversion trunk stehen Ihnen alle bisher veröffentlichten Versionen zur Verfügung. Eine Übersicht über den Inhalt des SVN-Repositories finden Sie im entsprechenden Kasten. An dieser Stelle gehen wir davon aus, dass Sie die aktuelle Entwicklungsversion installieren möchten. Bevor Sie daran gehen, diese Version auszuchecken, also aus dem Internet herunterzuladen, sollten Sie ein Verzeichnis erstellen, in dem Sie arbeiten möchten, zum Beispiel components/. Begeben Sie sich auf der Konsole in diesen Ordner und benutzen Sie den folgenden Befehl, um die aktuelle Entwicklungsversion herunterzuladen:

$ svn co http://svn.ez.no/svn/ezcomponents/trunk

Dieser Vorgang kann durchaus einige Minuten dauern, Sie werden aber stets über den Status des Downloads informiert. Anschließend haben Sie ein Unterverzeichnis namens trunk/ innerhalb Ihres Arbeitsverzeichnisses, in dem sich für jede Komponente ein Unterverzeichnis befindet. Die Verzeichnisstruktur entspricht größtenteils der des Gesamtpakets, wie in Abschnitt 2.1.3, »Das Gesamtpaket herunterladen«, beschrieben, bis auf den Ordner autoload/, der in der SVN-Version nicht existiert und nun noch angelegt werden muss. Zum Glück existiert hierfür ein Skript, das Ihnen die Arbeit abnimmt. Allerdings ist das Skript nicht in trunk/ enthalten und muss daher zunächst aus einem anderen Teil des SVN ausgecheckt werden. Gehen Sie dazu auf der Konsole wiederum in Ihr Arbeitsverzeichnis und benutzen Sie das folgende Kommando

$ svn co http://svn.ez.no/svn/ezcomponents/scripts

Es wird ein weiterer Ordner erzeugt; der Download sollte aber diesmal verhältnismäßig schnell erfolgen. Unterhalb dieses neuen Ordners scripts/ finden Sie eine Vielzahl von kleinen Programmen, mit denen Standardaufgaben bei der eZ Components-Entwicklung abgedeckt werden. Ein Blick in diese Trickkiste ist bestimmt spannend, soll aber an dieser Stelle nicht geschehen. Interessant ist nur das Skript scripts/setup-env.sh, falls Sie auf einem Unix-System arbeiten, beziehungsweise scripts/setup-env.bat, falls Sie Windows benutzen.

Zum Erzeugen der benötigten Autoload-Struktur begeben Sie sich wieder nach trunk/ und rufen von dort aus das soeben heruntergeladene Skript für Ihre Plattform auf. Auf Unix-Systemen sollten Sie vorher überprüfen, ob das Programm ausführbar ist und falls nötig entsprechende Rechte vergeben. Für jede Komponente sollte nun eine Statusmeldung darüber ausgegeben werden, dass die Autoload-Datei erzeugt wurde. Nach erfolgreichem Abschluss finden Sie einen neuen Ordner autoload/ unter trunk/. Wie in Abschnitt 2.1.2 beschrieben, enthält er die Autoload-Dateien aller Komponenten. Unter Windows finden sich hier Kopien dieser Dateien, auf Unix-Systemen werden Symlinks verwendet. Aus diesem Grund sollten Sie unter Windows das Skript zum Erzeugen der Autoload-Umgebung bei jedem Update von eZ Components erneut ausführen, um alle Änderungen zu übertragen. Unter Unix muss dies nur geschehen, falls neue Komponenten seit dem letzten Update hinzugekommen sind. Updates der SVN-Verzeichnisse erreichen Sie über den Befehl $ svn up, den Sie unterhalb des Verzeichnisses trunk/ oder eines der anderen SVN-Verzeichnisse eingeben müssen.

Nach diesem Schritt ist Ihre eZ Components-Umgebung auf dem gleichen Stand, wie in den vorherigen beiden Abschnitten beschrieben. Allerdings müssen Sie an dieser Stelle aufpassen, dass Sie das Verzeichnis trunk/ in die include_path-Direktive aufnehmen und nicht das darüber liegende Verzeichnis.

Sie sollten den trunk/-Zweig des Repositories niemals für den produktiven Einsatz verwenden, da es hierbei in seltenen Fällen vorkommen kann, dass ungetesteter und instabiler Code enthalten ist. Zwar folgen eZ Components dem Paradigma des Test-Driven-Developments (Test-getriebene-Entwicklung), dennoch kann nicht jeder Testfall vorhergesehen werden. Für den Einsatz in Live-Umgebungen empfehlen wir Ihnen, eine stabile Version der benötigten Komponenten aus dem SVN auszuchecken (siehe Kasten »Das Repository im Überblick«) oder auf eine der anderen Installationsvarianten zurückzugreifen.

Der Vorteil gegenüber den anderen Methoden liegt klar darin, dass Sie in Ihrer Entwicklungsumgebung immer auf dem allerneusten Stand der eZ Components-Entwicklung sind und neue Features umgehend testen können.

Ihr Kommentar