Unter Mac OS X entwickeln macht Spaß. Und das eigenen System einzurichten geht erstaunlich schnell, da Mac OS X bereits mit einem Apache 2.2 Webserver, PHP 5 und auch mit einem SVN Server ausgeliefert wird. Wie diese unkompliziert eingerichtet werden können soll hier gezeigt werden.

Apache Webserver unter Mac OS X starten

Den Apache Webserver zu starten geht erstaunlich einfach. Dazu kann entweder unter Systemeinstellungen > Freigaben die so genannte Webfreigabe aktiviert werden. Ich empfehle, den Apache Server auf diesem Wege zu starten. Natürlich kann man im Terminal kann auch folgenden Befehl eingegeben, doch fehlt dann der entsprechende visuelle Status unter Systemeinstellungen.

sudo httpd -k start

Das so genannte htdocs Verzeichnis (das Verzeichnis, dass von außen über den Apache 2 Server angesprochen wird) findet sich standardmäßig unter /Library/Webserver/Documents.

PHP 5 unter Mac OS X einrichten

Wer mit PHP 5 entwickeln möchte, der muss das entsprechende Apache Modul zunächst aktivieren. Dazu muss die httpd.conf Datei editiert werden. Sie findet sich unter /etc/apache2. Um auf die Systemverzeichnisse wie beispielsweise etc oder usr über den Finder zuzugreifen wählt man im Menu des Finders Gehe zu > Gehe zu Ordner. Alternativ kann natürlich auch über das Terminal und cd Befehlen zu den entsprechenden Verzeichnissen navigiert werden.

In der httpd.conf Datei muss die Zeile 116

LoadModule php5_module        libexec/apache2/libphp5.so

entkommentiert werden. Wer möchte kann in Zeile 215 einstellen, dass .htaccess Dateien Parameter ändern können. Das ist für die reibungslose Funktion von mod_rewrite notwendig.

<Directory /Library/WebServer/Documents>
  AllowOverride All
</Directory>

In Zeile 230 muss hinzugefügt werden, dass auch index.php Dateien als Directory Indexes erkannt werden:

<IfModule dir_module>
  DirectoryIndex index.html index.php
</IfModule>

Zu guter letzt muss der Webserver neu gestartet werden. Dies kann über die Systemeinstellungen (siehe oben) oder mit folgendem Befehl geschehen:

sudo httpd -k restart

Um zu testen, ob PHP läuft kann eine index.php und folgendem Inhalt im htdocs Verzeichnis abgelegt werden. Mit http://localhost/index.php im Browser sollte eine Übersicht über das installierte PHP Modul erscheinen.

<?php phpinfo(); ?>

Um Default-Eigenschaften zu überschreiben (error reporting, max upload etc.) muss eine php.ini Datei unter /etc/ angelegt werden. Meine php.ini enthält das Folgende:

max_execution_time = 60
memory_limit = 256M
display_errors = On
post_max_size = 32M
upload_max_filesize = 32M
date.timezone = Europe/Berlin

MySQL unter Mac OS X einrichten

Einen MySQL-Server unter Mac OS X einzurichten geht denkbar einfach. Hierfür gibt es fertige Installer, die über http://dev.mysql.com/downloads/mysql/ bezogen werden können. Zusätzlich kommt das MySQL Package mit einem Startup-Item. Wird es installiert, so startet MySQL bei jeden Systemstart automatisch. Installiert wird mysql unter /usr/local/mysql. Um MySQL manuell zu starten genügt folgender Befehl:

sudo mysqld_safe

Um einen unkomplizierten Umgang mit MySQL zu gewährleisten empfehle ich, das /usr/local/mysql/bin Verzeichnis zur $PATH hinzuzufügen. Tut man dies nicht, wird der mysql Befehl im Terminal nicht gefunden. Diese drei Schritte helfen:

1. Eine neue Datei /etc/paths.d/mysql erzeugen:

sudo touch /etc/paths.d/mysql

2. Die Datei bearbeiten und das MySQL bin Verzeichnis erstellen:

sudo vim /etc/paths.d/mysql

3. Den  MySQL-bin Pfad einfügen und speichern.

/usr/local/mysql/bin

Wer mit vim noch nicht gearbeitet hat: i drücken um in die Datei zu schreiben, den Pfad eingeben, ESC drücken und dann :wq eingeben und mit Enter bestätigen. Nach einem Neustart sind alle im /usr/local/mysql/bin Verzeichnis befindenden Programme auffindbar.

Achtung: Anfangs besitzt der MySQL root Account kein Passwort! Zur einfachen Verwaltung empfehle ich phpmyadmin – ein WebGUI.

Einen SVN Server unter Mac OS X einrichten

SVN wird bereits mit Mac OS X ausgeliefert. Damit der SVN Server auch von außen ansprechbar ist muss in erster Linie der Apache Webserver konfiguriert werden. Ich verwalte meine SVN Repositories im Ordner /usr/local/svn/. Um die Repositories von außen ansprechbar zu machen muss eine Datei namens svn.conf im Ordner /etc/apache2/other angelegt werden. Sie besitzt folgenden Inhalt:

LoadModule dav_svn_module /usr/libexec/apache2/mod_dav_svn.so
<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
</Location>

Nachdem Apache neu gestartet wurde sind die Repositories in /usr/local/svn/ unter http://localhost/svn ansprechbar. Beim Anlegen eines neuen Repositories namens foo mit

sudo svnadmin create /usr/local/svn/foo

Muss darauf geachtet werden, dass Apache und das SVN Modul auch darauf zugreifen können. Dazu ändern wir zuvor den Besitzer der Dateien in www um:

sudo chown -R www:www /usr/local/svn

Damit ist SVN bereits fertig eingerichtet. Ich empfehle die Absicherung des SVN Verzeichnisses. Dazu muss zunächst eine htpasswd Datei erzeugt werden:

htpasswd -cm /etc/apache2/svn.auth benutzername

Die svn.conf Datei muss um folgendes erweitert werden:

LoadModule dav_svn_module /usr/libexec/apache2/mod_dav_svn.so
<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  AuthType Basic
  AuthName "Subversion Login"
  AuthUserFile /etc/apache2/svn.auth
  Require valid-user
</Location>

Die Repositories sind jetzt unter http://localhost/svn erreichbar. Zur einfachen Verwaltung empfehle ich WebSVN – ein WebGUI.

Update: Sollte der Apache Server mit der obigen svn Konfiguration nicht mehr starten, muss darauf geachtet werden, dass die Apache Module mod_dav.so und mod_dav_fs.so auch geladen werden. Danke an Alexander für diesen Tip.

You’ll find quite a lot of guides showing you how to install an svn server on your Mac OS X machine. But most of them don’t tell you, that Mac OS X ships with a fully functional svn system. This is how you configure it.

Start of by opening Terminal and creating a new folder holding your future svn repositories:

sudo mkdir /usr/local/svn

Make sure you change the folder’s owner to “www” in order to make it accesable through apache:

sudo chown -R www:www /usr/local/svn

Now create a new repository:

sudo svnserve create /user/local/svn/foo

where foo is your repository’s name.

Make sure, apache is running by checking your system preferences and enabling web sharing.

Now create a new file named svn.conf and place it in /etc/apache2/other. Type the following into the file:

LoadModule dav_svn_module /usr/libexec/apache2/mod_dav_svn.so
<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
</Location>

Restart apache by typing

sudo apachectl graceful

into your terminal. And you’re ready and set. Access your repository through http://localhost/svn.

In dieser Reihe von Publizierungen werden alle notwendigen Schritte beschrieben, eine professionelle Entwicklungsumgebung aufzusetzen mit welcher mit dem Zend Framework entwickelt werden kann. Als ZF-Projekt soll beispielhaft ein Gästebuch mit Administrationsbereich erstellt werden.

Hierfür wird zuerst auf dem System (Windows 7) Apache, MySQL und PHP installiert (Zend Community Server) und der Apache entsprechend konfiguriert, dass das zukünftige Projekt über Virtual Hosts ansprechbar ist. Um den Code komfortabel zu verwalten verwenden wir das Versionskontrollsystem Subversion welches wir gegen unbefugte Benutzung absichern werden. Anschließend wird eine Entwicklungsumgebung (Zend Studio für Eclipse) installiert, welche komfortabel mit der Versionsverwaltung und dem Server zusammenarbeiten kann.

Letzlich wird begonnen das eigentliche Projekt, die Programmierung des Gästebuchs, mit Hilfe von verschiedenen Pattern (z.B. MVC) umzusetzen.

Was ist das Zend Framework

Das Zend Framework (oft abgekürzt mit ZF) ist ein komponentenorientieres Framework für PHP 5, welches zahlreiche Klassen bereit stellt mit welchen sehr komfortabel Anwendungen entwickelt werden können.
Komponentenorientiert in diesen Zusammenhang heißt, dass neue Anwendungen komplett auf dem Framework bassierend entwickelt werden können- alternativ können zu bestehenden Anwendungen aber auch nur bestimmte Funktionen, z.B. Cacheing, Authentifizierung, von dem Framework genutzt werden.
Im März 2006 wurde die erste Pre-Alpha-Version 0.1.1 vorgestellt und wird seit dem stetig von Zend Technologies – den Entwicklern von PHP – weiterentwickelt.

Warum das Zend Framework

Frameworks sind mehrere dutzende verfügbar, eine Wahl fällt hier auf den ersten Blick sehr schwer. Stellt man jedoch eine Reihe von Kriterien auf, wird die Auswahl schnell auf wenige eingeschränkt. Ich möchte hier nur ein Paar der zahlreichen Vorteile listen, welche ich bei dem Zend Framework gegenüber anderen Frameworks sehe:

• Komponentenbasierend
  Wie bereits im Paragraphen “Was ist das Zend Framework” beschrieben. Um das ZF zu nutzen müssen bestehende Anwendungen nicht neu geschrieben werden, sondern es können bestimmte Funktionalitäten ohne großen Aufwand genutzt werden.
  Zahlreiche Standardaufgaben wie Formularerstellung und -validierung, E-Mailversandt oder Templates werden durch die Komponenten abgedeckt.
  Durch durchgehend benutzte Design Patterns (“Entwicklungsmuster”) und Adapter (ein Art abkopelbarer Zwischenschritt) können sehr schnell durch wenige Zeilen Code große Teile der Anwendung umgeschrieben werden.  So ist es z.B. innerhalb weniger Sekunden möglich die Anwendung so umzuschreiben, dass diese zukünftig in einer ini-/ xml-Datei oder SQLite-DB statt in einer Oracle-/ MySQL-Datenbank Fehlermeldungen protokolliert.

• Community
  Das ZF hat eine sehr große Community die von Zend selbst wiederum stark gefördert wird (siehe Zend Framework Wiki). Es existieren zahlreiche, natürlich auch deutschsprachige, Foren, Blogs und Tutorials die sich mit dem ZF beschäftigen.

• Dokumentation
  Das ZF ist vorbildhaft dokumentiert. Die Dokumentation wird von Zend selbst immer auf den neusten Stand gehalten, ist in zahlreichen Sprachen verfügbar und verfügt über zahlreiche Beispiele und Tutorials.

• Web 2.0
  Es stehen zahlreiche Klassen bereit, mit welchen man die Services von Google, Delicous, YouTube, Flickr, Yahoo, Amazon etc. ohne hohe Einarbeitungszeit nutzen kann.

• Ajax
  Das Dojo Toolkit ist in das ZF integriert. Hierdurch können sehr schnell Ajax-Applikationen erstellt werden.
  Auch hier gilt wieder – Dojo kann verwendet werden, muss aber nicht. Sind sie bereits ein anderes Framework gewohnt, können Sie dieses ebenfalls mit dem ZF nutzen.

• Weiterentwicklung
  Da hinter dem ZF die Zend Technologies steht, ist eine in Zukunft Weiterentwicklung gesichert – ein großer Pluspunkt im Vergleich zu anderen Frameworks.

• Lizenzierung/Kosten
  Das ZF steht unter der BSD-Lizenz. Kosten entstehen also nicht.

• Testbasis
  Alle Komponenten werden über Unit-Tests getestet. Auch ist es so dem Entwickler möglich, mit relativ wenig Aufwand Tests für seine Applikation zu schreiben.

Warum Zend-Software

In der Einleitung war schon abzulesen, dass hier fast nur Software von Zend verwendet wird. Hintergrund für diese Wahl ist, dass ich persönlich von den Zend-Produkten überzeugt bin: sie zeichnen sich aus durch eine komfortable, leicht zu erlernende Bedienung und zahlreiche kleine Tools welche die tägliche Arbeit stark erleichtern.

Vorteile

So ist es z.B. beim Zend Server möglich über eine Web-GUI schnell die Konfiguration zu ändern (z.B. bestimmte PHP-Extensions oder Error-Logging zu (de)aktivieren) und weil alles “aus einer Hand” kommt wird beim ersten Start von Zend Studio (nur eines von zahlreichen weiteren Beispielen) automatisch der Zend Server gefunden und das Debugging konfiguriert. Natürlich stell Zend Studio auch zahlreiche Tools bereit welche das Arbeiten mit dem ZF noch mehr beschleunigen. Mit Zend Tools ist übrigens ein Server-debugging möglich, das heißt der Code kann auf dem Server selbst, unabhängig vom Code in der Entwicklungsumgebung inspiziert werden.
Zend Studio setzt auf Eclipse auf – es können also die Plugins welche man bereits in Eclipse verwendet hat bzw. kennt, auch in Zend Studio verwenden.

Nachteile

Nach viel Lob und Tadel sollen natürlich auch die negativen Aspekte beleuchtet werden: Zend Studio (Eclipse)  benötigt relativ viel Arbeitsspeicher. Sind mehrere große Projekte parallel geöffnet kann dies den Rechner schon stark belasten (insbesondere wenn Tools wie der HTML-Validator aktiv sind).
Zahlreiche Kinderkrankheiten wurden in Verison 7.1 behoben, welches ein Update auf diese Version obligatorisch ist.
Eine offizielle 64-Bit Version für Linux ist noch nicht verfügbar – zwar kann man die 32-Bit Version installieren, dies läuft aber instabil.
Die Entwicklungsumgebung mag hin und wieder ein wenig oversized wirken: man kann wirklich alles damit machen. Über SSH auf einen Server zugreifen und direkt Remote Dateien editieren oder direkt Datenbanken entwickeln – dies ist aber manchmal einfach zuviel des guten wenn man nur “ein paar Zeilen Code” schreiben will.
Auch arbeiten manche Funktionen, z.B. die Codevervollständigung in Javascript, nicht fehlerfrei; andere Funktionen welche z.B. den Code auf (logische) Korrektheit prüfen arbeiten suboptimal, sodass nach einem Import eines Projektes mehrere 1000 angbliche Fehler gelistet werden – dabei steht aber z.B. der schließende Tag in einer includeten-Datei, was Zend natürlich nicht weiß.

Kosten

Der Zend Server ist in der sog. Community Edition (eingeschränkter Fuktionsumfang) kostenlos erhältich. Für die Entwicklung reichen die Funktionen jedoch voll und ganz aus. Zend Studio kostet mit einem 1-Jahres-Abo für Updates und Support 399€, dies ist jedoch verglichen mit Funktionsumfang ok. Eine Testversion für 30 Tage ist verfügbar.

Ausblick

Im nächsten Beitrag werden wir den Zend Server CE herunterladen und installieren. Es wird ein kurzer Überblick über die Funktionen gegeben. Anschließend werden wir noch zwei Virtual Hosts einrichten (live, development) über welche unsere zukünftige Anwendung dann erreichbar sein wird.

Wichtige Links

• http://www.zend.com/de/ – Zend Technologies, Download von Zend Studio und Zend Server CE.
• http://framework.zend.com - Zend Framework, die offizielle Seite von ZF. Mit Links zur Dokumentation, Tutorials und dem ZF Wiki.
• http://www.dojotoolkit.org/ – Dojo Toolkit, das in ZF integrierte Ajax-Toolkit
• http://www.zfforums.com/ – ZF Forum, englischsprachiges ZF Forum.
• http://www.ralfeggert.de/ – Blog von Ralf Eggert, blogt über das ZF und PHP allgemein.

Eines meiner etwas zurückliegenden Projekte zwang mich externe Bilder durch meinen Server zu laden, zu verkleinern und schließlich auch die Durchschnittsfarbe zu berechnen. Aus Gründen der Performancesteigerung war ich nie ein Fan davon die Durchschnittsfarbe Pixel für Pixel des Originalbildes zu berechnen. Es gibt eine viel elegantere und fast genauso exakte Lösung:

Unser Ziel: Wir möchten ein Bild (jpg, gif, png) über einen HTTP-Stream laden, dieses lokal auf dem Server speichern, ein entsprechendes Thumbnail (eine verkleinerte Version) erzeugen, speichern und schlussendlich die dominierende – oder auch durchschnittliche – Farbe im Bild berechnen und abspeichern. Eventuell möchten wir zusätzlich alles in einer Datenbank hinterlegen – das soll aber zunächst außerhalb unserer Betrachtung liegen.

Für das Berechnen der Durchschnittsfarbe gibt es einen wunderbar einfachen Trick. Doch dazu später mehr. Beginnen wir zunächst einmal mit einer Konstante und einer Funktion, die wir später noch benötigen:

DEFINE('CTX', stream_context_create(array(
    'http' => array(
        'timeout' => 20,
        'method' => 'get',
        'header' => 'Referer: XYZ'
    )
)));

Unsere Konstante CTX ist also ein array. Wir benötigen es für unsere HTTP-Anfrage, mit der wir das gewünschte Bild auf unseren Server laden. Für diese Anfrage verwenden wir die HTTP-GET-Methode, definieren einen Timeout von maximal 20 Sekunden und senden einen Referer im Header, den ich hier mal einfach nur “XYZ” genannt habe.

function randomstring_creator($len = 20) {
    $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    $string = '';
    mt_srand((double) microtime() * 1000000);
    for($i = 0; $i < $len; $i++) {
        $string .= $chars{mt_rand(0, strlen($chars))};
    }
    return($string);
}

Die Funktion randomstring_creator() generiert uns eine zufällige Zeichenfolge mit einer beliebigen Länge. Wir benötigen diese Funktion, da wir in diesem Beispiel die Bilder lokal unter einem zufälligem Namen speichern werden.

Weiter geht es mit unseren Klassen. Beginnen wir mit der Klasse Image:

class Image {
    var $img;
    var $source;
    var $local;
    var $dimX;
    var $dimY;
    var $avg_colour;
    function get($source, $quality = 90) {
// siehe unten
    }
    function calc_avg_colour() {
// siehe unten
    }
}

Unsere Klasse besitzt also die Eigenschaften source (die Url, von der das Bild stammt), local (den lokalen Speicherpfad), dimX, dimY (die Abmessungen des Bildes in Pixel) und avg_colour (den farblichen Durchschnittswert als HEX-Code in der Form rrggbb). Die Eigenschaft img ist eine Referenz auf das Image-Objekt, dass ich aber später noch näher beleuchten werde.

Die beiden Funktionen get() und calc_avg_colour() der Klasse sollten selbsterklärend sein. Mit der Funktion get(), die gleichzeitig auch als Konstruktor dient, laden wir das Bild, dass unter source zu finden ist, auf unseren Server und speichern es in der gewünschten JPEG-Qualität (90 als Standard) lokal.

calc_avg_colour() berechnet – wie der Name schon sagt – die Durchschnittsfarbe des in der Eigenschaft img gespeicherten Bildes.

Wir wollen zusätzlich aber auch kleine Abbilder des Originalbildes erstellen und erweitern dazu unsere Image-Klasse um die Klasse Thumbnail:

class Thumbnail extends Image {
    function create($parent, $X = 300, $Y = 300, $quality = 60) {
// siehe unten
    }
}

Diese Erweiterung besitzt zunächst nur eine Funktion, mit der das Thumbnail erstellt wird. Die übergebene Variable parent enthält dabei eine bereits existierende Image-Klasse, die herunterskaliert werden soll. Die maximale Breite und Höhe werden mit den Variablen X und Y (standard bei 300 Pixel) übergeben. Die JPEG-Qualität beträgt standardmäßig nur 60.

Das eigentliche Programm sieht dann nur noch so aus:

$imgurl = 'original.jpg';
// neues Objekt der Klasse Image erzeugen
$img = new Image;
// Bild aus der imgurl laden
if($img->get($imgurl)) {
    // ein Objekt der Klasse Thumbnail erzeugen
    $thumb = new Thumbnail;
    // und ein Thumbnail des oben definierten Objektes der Klasse Image generieren
    $thumb->create($img, 300, 300);
    // dann noch die Durschschnittsfarbe berechnen
    $thumb->calc_avg_colour();
    // und Daten ausgeben... fertig
    echo('Image: ' . $img->source . "\n");
    echo('Thumbnail: ' . $thumb->source . "\n");
    echo('Average colour: #' . $thumb->avg_colour . "\n");
} else {
    echo('Could not get the image.');
}

So, dann sehen wir uns also mal unsere Funktionen der Klassen an. Beginnen wir mit der Funktion get():

function get($source, $quality = 90) {
    $this->source = $source;
    // wir laden das Bild von $source:
    if(($file = file_get_contents($this->source, false, CTX))) {
        // wenn erfolgreich, erzeugen wir mit den geladenen Daten
        // ein neues Bild und speichern dieses in der Eigenschaft img
        $this->img = imagecreatefromstring($file);
        // wir lesen die Höhe und Breite des Bildes aus
        $this->dimX = imagesx($this->img);
        $this->dimY = imagesy($this->img);
        // und speichern das Bild unter zufälligem Namen mit imagejpeg lokal im Ordner "raw"
        $this->local = 'raw/' . randomstring_creator() . '.jpg';
        imagejpeg($this->img, $this->local, $quality);
        // bei Erfolg true zurückgeben
        return(true);
    } else {
        // false, wenn das Bild nicht geladen werden konnte
        return(false);
    }
}

Ein Thumbnail erzeugen wir mit dieser Funktion der Klasse Thumbnail:

function create($parent, $X = 300, $Y = 300, $quality = 60) {
    // zunächst die vorläufigen Abmessungen speichern
    $this->dimX = $X;
    $this->dimY = $Y;
    // die Abmessungen und deren Verhältnis des Originalbildes holen
    $origX = $parent->dimX;
    $origY = $parent->dimY;
    $ratio = $origX / $origY;
    // wenn das Originalbild breiter als hoch ist, kürzen wir die Höhe
    if($X / $Y > $ratio) {
        $this->dimX = $Y * $ratio;
    } else {
    // wenn das Originalbild höher als breit ist, kürzen wir die Breite
        $this->dimY = $X / $ratio;
    }
    // hier erstellen wir ein neues Bild mit den oben berechneten Abmessungen
    $this->img = imagecreatetruecolor($this->dimX, $this->dimY);
    // und kopieren das Originalbild einfach in das eben erstellte kleinere, dabei wird es verkleinert
    imagecopyresampled($this->img, $parent->img, 0, 0, 0, 0, $this->dimX, $this->dimY, $origX, $origY);
    // jetzt speichern wir das neue Thumbnail noch unter zufälligem Namen im Ordner "thumb"
    $this->source = $parent->local;
    $this->local = 'thumb/' . randomstring_creator() . '.jpg';
    imagejpeg($this->img, $this->local, $quality);
}

Das Herzstück: Wir wollen die Durchschnittsfarbe ermitteln. Dazu könnten wir einfach alle Farbwerte aller Pixel zusammen addieren und dann durch die Anzahl der Pixel teilen. Bei einem Thumbnail von der Größe 300 x 300 Pixel, würden wir aber eine Schleife mit 90.000 Durchläufen benötigen. Es gibt einen besseren Weg – einen ganz logischen Trick.

Durchschnittsfarbe berechnen

Wir haben oben beim Erstellen des Thumbnails die Funktion imagecopyresampled() verwendet. Was wenn wir unser Thumbnail einfach auf eine Größe von 1×1 Pixel skalieren? Genau: Es bleibt ein Pixel mit der Durschnittsfarbe übrig. Dessen Farbe auszulesen ist mit imagecolorat() dann nur noch eine Kleinigkeit. Los gehts:

function calc_avg_colour() {
    // ein temporäres Bild mit den Abmessungen 1x1 Pixel erstellen
    $avrg = imagecreatetruecolor(1, 1);
    // Das Thumbnail einfach reinkopieren, dabei auf 1x1 Pixel skalieren
    imagecopyresampled($avrg, $this->img, 0, 0, 0, 0, 1, 1, $this->dimX, $this->dimY);
    // Die Farbe des verbleibenden Pixels auslesen
    $rgb = imagecolorat($avrg, 0, 0);
    // Das temporäre Bild wieder löschen
    imagedestroy($avrg);
    // Und die Farbe in HEX umwandeln
    $r = dechex($rgb >> 16);
    $g = dechex($rgb >> 8 & 255);
    $b = dechex($rgb & 255);
    if(strlen($r) < 2) $r = 0 . $r;
    if(strlen($g) < 2) $g = 0 . $g;
    if(strlen($b) < 2) $b = 0 . $b;
    // tataaaa... da ist unsere Durchschnittsfarbe:
    $this->avg_colour = $r . $g . $b;
}

Super. Das wäre es. Ende und aus.

Die ersten drei Teile dieser Reihe hatten sich mit der theoretischen und praktischen Implementierung des User Consent Flow Prozesses, der für die Authentifizierung des Nutzers mit und der Verwendung der eBay Trading API notwendig ist, befasst. Im vierten und letzten Teil sollen die Implementierungen der letzten drei Teile (Teil 1, Teil 2, Teil 3) dieser Reihe in die Controller und Views umgesetzt und so ein visueller Anmelde- und Authentifizierungsprozess geschaffen werden.

Was wird Teil 4 dieses Guides zeigen?

Wir werden einen Prozess schaffen, der es dem Nutzer erlaubt den eBay User Consent Flow mit Hilfe unserer Webapplikation zu durchschreiten. Dieser Prozess soll möglichst unkompliziert, direkt und intuitiv bedienbar sein. Ich empfehle also die Verwendung von Ajax-Methoden um das User Interface und den darzustellenden Prozess zu visualisieren. Wie das Zend Framework mit Ajax Anfragen umgehen kann wird hier also auch Thema sein.

Warum Ajax?

Wenn wir uns eben an den Ablauf des (in Teil 1 ausführlich beschriebenen) Consent Flow Prozesses erinnern: Der Benutzer muss selbst nur wenige Klicks und Eingaben machen – namentlich die Anmeldung auf der eBay Login-Seite zu der er weitergeleitet wird. Im Hintergrund muss unsere Applikation allerdings zwei Anfragen machen. (1) Eine SessionID von der eBay trading API anfragen und (2) nach der Rückkehr des Benutzers zur Applikation den mit der SessionID verknüpften Auth-Token anfragen.

Hier empfehle ich Ajax: Dem Benutzer soll visualisiert werden, dass sich hinter den Kulissen etwas tut und nicht lange auf den Seitenaufbau warten müssen (die API-Anfragen dauern ein paar wenige Sekunden). Wir werden also die Seite ausliefern, und von dieser eine Ajax-Anfrage starten, die die getSessionID und später die fetchToken Actionen anstoßen wird. Der Benutzer wird ein Lade-Grafik sehen und damit merken, dass sich etwas tut. Die Weiterleitung soll vollautomatisch erfolgen. Das Ergebnis sieht also keinerlei Actionen vom Benutzer auf unserer Applikation vor. Er muss lediglich warten bis er zu eBay weiter geleitet wird und sich dort anmelden kann.

Die benötigten Actions

Wie in Teil 2 bereits aufgestellt brauchen wir neben dem Ebayauth Controller folgende fünf Actions:

• index (stößt den Consent Flow an)
  
• step1 (ist Ziel eines Ajax-Requests – übernimmt getSessionID)
• success (bei erfolgreichem Login auf eBay wird der Benutzer hierhin weitergeleitet)
• step2 (ist Ziel eines Ajax-Requests – übernimmt fetchToken)
• und denied (bei fehlgeschlagenem oder abgebrochenen Login)
  

und vier Views für den Controller Ebayauth:

• index.phtml
• step1.ajax.phtml
• success.phtml
  
• step2.ajax.phtml
• und denied.phtml

Ajax Requests erkennen und entsprechend handeln

Um die Unterscheidung zwischen ‘normalem’ Request und einem Ajax-Request können wir einen Context-Switcher verwenden, den uns das Zend Framework zur Verfügung stellt. Dieser muss in der init()-Methode des Controllers initialisiert werden uns sieht in unserem Fall so aus:

$contextSwitch = $this->_helper->getHelper('AjaxContext');
$contextSwitch->addActionContext('step1', 'html') // wir geben html zurück
              ->addActionContext('step2', 'html') // möglich wäre auch xml oder json
              ->initContext();

// Das übrige Layout abschalten
if($this->_request->isXmlHttpRequest()) {
     $this->_helper->layout->disableLayout();
}

Unsere zwei step Actions benötigen noch eine kleine Fallunterscheidung. Wir möchten sie nur ausführen lassen, wenn es sich tatsächlich um einen Ajax-Request handelt:

if(!$this->_request->isXmlHttpRequest()) {
    $this->_redirect('/ebayauth/index'); // zum Start des Auth-Prozesses umleiten
}

Der Controller Ebayauth

Springen wir gleich in den Code:

public function indexAction() {}

public function step1Action()
{
    if(!$this->_request->isXmlHttpRequest()) {
        $this->_redirect('/ebayauth/index');
    }

    // die getSessionID API-Anfrage durchführen
    $tokenAdapter = new Ebay_Auth_ConsentFlow();
    $return = $tokenAdapter->getSessionID();

    // Wir müssen die SessionID in einer Datenbank oä. zwischenspeichern
    $modelAccount = new Model_Account();

    if($return != false) {
        // zwischenspeichern - bitte durch eigenen Implementierung ersetzen
        $modelAccount->writeEbaySessionId($this->accountID, $return['sessionId']);
        if(isset($return->ShortMessage)) {
            // bei Fehler ist ShortMessage teil der API Rückgabe
            $this->view->error = (string)$return->ShortMessage;
        } else {
            $this->view->redirectURL = $return['redirectUrl'];
        }
    } else {
        $this->view->error = 'Keine Verbindung zu eBay.';
    }
}

public function successAction() {}

public function step2Action()
{
    if(!$this->_request->isXmlHttpRequest()) {
        $this->_redirect('/ebayauth/index');
    }

    // die im step1 zwischengespeicherte SessionID aus der Datenbank holen
    $modelAccount = new Model_Account();
    $sessionId = $modelAccount->getEbaySessionId($this->accountID);

    // die fetchToken API Anfrage ausführen
    $tokenAdapter = new Ebay_Auth_ConsentFlow();
    $return = $tokenAdapter->getToken($sessionId);

    if($return != false) {
        // auch hier wieder eigenen Implementierung Verwenden
        $modelAccount->writeEbayTokenId($this->accountID, $return['token'], $return['expiration']);
        if(isset($return->ShortMessage)) {
            $this->view->error = (string)$return->ShortMessage;
        } else {
            // Hier festlegen wohin umgeleitet werden soll
            $this->view->redirectURL = '/'; // zurück zur Startseiten
            $this->view->expiration = $return['expiration'];
        }
    } else {
        $this->view->error = 'Keine Verbindung zu eBay';
    }
}

public function deniedAction() {}

Die drei Actions index, success und denied benötigen keine Methoden im Controller. Der JavaScript, der den Ajax-Request anstößt coden wir einfach fest in die views ein.

Die Views

Das hier ist der index view (index.phtml). Wir binden ein JavaScript ein und rufen die Funktion shootAjaxHtml() auf.

<div>
    <div id="loader" class="redirect"><img src="/images/preloader.gif" /> Weiterleitung an eBay wird vorbereitet ...
        <script type="text/javascript">shootAjaxHtml('/ebay/step1', 'loader')</script>
    </div>
</div>

Der step1.ajax.phtml View:

<?php if(isset($this->redirectURL)) { ?>
<p>Automatische Weiterleitung zu eBay in wenigen Sekunden. <a href="<?php echo($this->redirectURL); ?>" title="Weiterleitung">Oder hier klicken.</a></p>
<script type="text/javascript">window.location = '<?php echo($this->redirectURL); ?>';</script>
<?php } elseif(isset($this->error)) { ?>
<p class="error"><strong>Fehler:</strong> <?php echo $this->error; ?></p>
<?php } ?>

success.phtml:

<div>
    <div id="loader" class="redirect"><img src="<?php echo SKINPATH; ?>/images/preloader.gif" /> eBay Anmeldung wird abgeschlossen ...
        <script type="text/javascript">shootAjaxHtml('/ebay/authgettoken', 'loader')</script>
    </div>
</div>

Und step2.ajax.phtml:

<?php if(isset($this->redirectURL)) { ?>
<p class="info">Die Verknüpfung des Benutzerkontos mit eBay verliert am <?php echo date('d.m.Y', strtotime($this->expiration)); ?> um <?php echo date('H:m', strtotime($this->expiration)); ?> Uhr seine Gültigkeit.</p>
<p><a href="/ebay" class="black" title="Zurück zur Startseite">Weiter</a></p>
<?php } elseif(isset($this->error)) { ?>
<p class="error"><strong>Fehler:</strong> <?php echo $this->error; ?></p>
<?php } ?>

Im denied View gebe ich nur eine Fehlermeldung wie “Anmeldung fehlgeschlagen”.

Der JavaScript (mit mootools):

function shootAjaxHtml(action, loaderid)
{
    var remote = new Request.HTML({
        url: action + "?format=html",
        onSuccess: function(html) {
            $(loaderid).getParent('div').empty().adopt(html);
        },
        onFailure: function(xhr) {
            $(loaderid).getParent('div').empty().adopt(new Element('p').set('text', 'Es ist ein Fehler aufgetreten: ' +xhr.status +' ' +xhr.statusText).addClass('error'));
        }}).get();
}

Und damit sind wir auch schon fertig.

Ich hoffe die ersten drei Teile dieser Einführung in eine Mögliche Implementierung des Consent Flows der eBay trading API in eine Webapplikation mit dem Zend Framework waren gut verständlich und konnten einen guten Überblick über die benötigten Implementierungsschritte geben. Teil vier hat anhand von Codebeispielen gezeigt, wie man den Consent Flow möglichst benutzerfreundlich umsetzen kann.

Empfehlungen, Anmerkungen, Verbesserungsvorschläge? Dazu sind die Kommentare da!

Man stelle sich folgendes Szenario vor: Es existiert eine Webseite, die eine Vielzahl von Grafiken, die auf dem gleichem Server hinterlegt sind, einbindet. Diese Webseite wird erfahrungsgemäß eine überdurchschnittlich lange Ladezeit haben. Aber nicht nur aufgrund der zu übertragenen Datenmengen, sondern auch aufgrund der maximalen Anzahl von Verbindungen, die ein Browser auf ein und denselben Server erlaubt. Hier werde ich etwas über die Beschleunigung vom Aufbau von Webseiten schreiben. Dabei verwende ich gewisse DNS Einstellungen, so genannte CNAME-Records mit denen ich serverseitig mehrere parallele HTTP-Verbindungen erlauben kann und so das Laden der Webseite durch den Browser des Nutzers beschleunige.

Standardmäßig sind moderne Browser mit maximalen Anzahl von sechs Verbindungen (IE 6 und IE 7 maximal zwei Verbindungen) zu ein und demselben Host begrenzt. Das führt dazu, dass das Laden von Dateien (Bilder, HTML-Seiten, JavaScripts oder Stylesheets) von einer Webseite in Blöcken unterteilt wird. Dabei würde es um einiges schneller gehen können, wenn ich die zu ladenden Dateien auf verschiedene Hostnamen verteile. So können für jeden Hostnamen mehr Verbindungen gleichzeitig ermöglicht werden.

Man betrachte zum Beispiel Google Maps. Die angezeigte Karte besteht aus einer vielzahl von so genannten Tiles. Tiles sind einfach Kacheln. Jede Kachel stellt einen Kartenausschnitt dar:

Damit die Karte schnellstmöglich trotz der Browserbegrenzung von sechs Verbindungen geladen werden kann, verteilt Google Maps die zu ladenden Kacheln auf verschiedene Hostnamen (Subdomains). Google verwendet vier Subdomains: mt0, mt1, mt2 und mt3.google.de:

Grundsätzlich ist es kein großes Problem verschiedene Subdomains anzulegen und die Dateien einer Webseite auf diese Subdomains zu verteilen. Allerdings besteht so recht schnell die Gefahr, dass man als Administrator den Überblick verliert, wo welche Dateien abgespeichert sind. Einfacher wäre es, zB. alle Mediendateien (zB. Bilder, Videos) unter einer Subdomain abzuspeichern. Um das Laden der Startseite erheblich zu beschleunigen, aber ohne zahlreiche Subdomains zu arbeiten kann man wie folgt vorgehen:

1. Ich lege unter der Hauptdomain eine einzige subdomain namens media.domain an. Hier speichere ich alle Bilder ab.
2. Ich lege so genannte CNAMES Einträge in meinen DNS Einstellungen an. Ein CNAME ist – einfach erklärt – ein Domain-Alias. In meinem Fall wähle ich zwei CNAME-Einträge namens “media0.domain.de” und “media1.domain.de” an. Am einfachsten geht es über die Adminoberfläche Plesk und sieht folgendermaße aus:
3. Diese beiden Einträge bewirken, dass media0.domain.de und media1.domain.de auf die gleiche subdomain media.domain.de umleiten. Ich habe jetzt also eine Subdomain, die auf drei unterschiedliche Weisen erreicht werden kann. Der Browser des Nutzers interpretiert die drei Domains als drei unterschiedliche Adressen, die aber auf den gleichen Speicherort verweisen. So sind drei mal so viele Verbindungen zum eigentlich gleichen Host möglich. Der Browser wird einfach ausgetrickst.
4. Bei der Einbindung der Bilder in die Webseite muss ich jetzt nur die zwei verschiedenen “subdomains” media0 und media1 verteilen. Ich löse das über einen Zufallsgenerator in meinem PHP Script, dass den HTML-Code generiert. Dieser könnte zB. so aussehen:

$media_domains = array('media0', 'media1');
foreach($bilder as $bild) {
  shuffle($media_domains);
  echo('<img src="' . $media_domains[0] . '.domain.tld/img/'. $bild . '" />');
}

Und fertig. Kommentare, Verbesserungsvorschlage? Dazu sind die Kommentare da.

In den beiden ersten Teilen dieses Guides habe ich einen Überblick über die Funktionsweise und den Aufbau des user Consent Flow von eBay Applikationen in Verbindung mit der eBay trading API geschaffen (zum ersten Teil dieses Guides) und den Aufbau unseres Ebay API Adapters und die Implementierung mit Hilfe des Zend Frameworks erläutert (zum zweiten Teil dieses Guides).

Was werde ich hier in Teil 3 beschreiben?

Dieser Teil beschäftigt sich mit der Implementierung des Auth bzw. des Consent Flow Prozesses der eBay trading API. Wir werden uns einen Überblick über die benötigten Klassen und Methoden schaffen und diese dann mit Hilfe des Zend Frameworks in unser bereits vorhandenes Projekt implementieren. Unsere Aufmerksamkeit widmen wir der Ebay_Auth_ConsentFlow Klasse und deren Methoden GetSessionID() und fetchToken(). Außerdem werden wir anhand dieser zwei API-Anfragen die API-Rückgabe untersuchen.

Die Klasse Ebay_Auth_ConsentFlow

Wir benötigen die Klasse Ebay_Auth_ConsentFlow um das Ziel, einen validen AuthToken von der eBay trading API zu erhalten. Wie in Teil 1 dieses Guides beschrieben läuft der eBay User Consent Flow in drei Schritten ab: (1) Session ID anfragen, (2) User zum eBay Anmeldeformular weiterleiten und (3) AuthToken anfragen. Erst mit dem AuthToken können wir im Namen des Nutzers Aktionen mit der eBay trading API durchführen.

Auf Schritt 2 haben wir mit unserer Implementierung keinen Einfluss. Viel mehr müssen wir uns um die beiden API-Anfragen GetSessionID (1) und ConsentFlow (2) kümmern. Die GetSessionID Anfrage implementieren wir in gleichnamiger Methode unserer Ebay_Auth_ConsentFlow Klasse. Die FetchToken Anfrage werden wir analog in der Methode fetchToken() unterbringen. Hier noch einmal der Ablauf:

1. Ebay_Auth_ConsentFlow->getSessionID() aufrufen
   und bei der trading API eine sessionID anfragen
2. Ebay_Auth_ConsentFlow->fetchToken($sessionID)  aufrufen
   und – vorausgesetzt der Benutzer hat sich erfolgreich auf eBay eingelogged – den zur sessionID gehörigen AuthToken erhalten

Zur Erinnerung:

• Die getSessionID Methode wird direkt vom Controller aufgerufen und muss im Erfolgsfall die eBay Signin URL – an die der Benutzer weiter geleitet werden soll – zurück geben.
• Die callApi Methode erwartet die folgenden Parameter:

  callApi($verb, $request, $aditionalXml = true, $requestCredentials = true, $serverUrl = null)
  

  Die GetSessionID Anfrage benötigt keine zusätzlichen XML Paramter und auch keine requestCredentials.

• Die callApi Methode gibt ein zweielementiges Array zurück. Einen Statusflag (‘Success‘) und die Originalantwort (‘Response‘) der eBay API.

Die Implementierung der getSessionID Methode

Werfen wir nun einen Blick auf die getSessionID() Methode:

class Ebay_Auth_ConsentFlow extends Ebay_Abstract
{
    public function getSessionID()
    {
        $callVerb = 'GetSessionID';
        $xmlBody  = '<RuName>' . $this->_apiAdapter->_ruName . '</RuName>';
        $response = $this->_apiAdapter->callApi($callVerb, $xmlBody, false, false);

        if($response['Success'] == false) {
            $return = $response['Response']->shortMessage;
        } else {
            $return = array(
                'redirectUrl' => $this->_apiAdapter->_signinUrl .
                                 '&RuName=' . $this->_apiAdapter->_ruName .
                                 '&SessID=' . $response['Response']->SessionID,
                'sessionId'   => $response['Response']->SessionID
            );
            return $return;
        }
    }
}

Der Vollständigkeit halber und um die Referenz auf $this->_apiAdapter in Zeile 6 erklären zu können hier noch die rudimentäre Ebay_Abstract Klasse. Ebay_Auth_ConsentFlow und alle anderen Ebay API Request Klassen erben den folgende Konstruktor:

class Ebay_Abstract
{
    protected $_apiAdapter;

    public function __construct()
    {
        if(!isset($this->_apiAdapter)) {
            $this->_apiAdapter = Ebay_Api_Adapter::getInstance();
        }
    }
}

Wie zu sehen ist, ist der eigentliche Aufbau des API-Request denkbar einfach.  Wir erstellen den XML-String und setzen mit $callVerb (Zeile 5) den korrekten Anfragen-Namen. Alles weitere macht unsere CallApi Methode der Klasse Ebay_Api_Adapter. Die getSessionID Anfrage benötigt als einzigen Paramter den ruNamen der Applikation um das mit der SessionID verknüpfte eBay Login-Formular mit dem Logo und der Beschreibung unserer Applikation zu versehen.

Als Rückgabe an den Controller sollte uns die getSessionID() Methode eine Sandbox Signin-URL der Form https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RuName=ruNameDerApplikation&SessID=dieAngefragteSessionID zurückgeben.

Wie der Controller und die Views aussehen erkläre ich später in Teil 4 dieses Guides. Nur so viel vorweg: Ich muss zwangsläufig die SessionID mit dem Benutzer Account verknüpfen, damit später sichergestellt werden kann, dass die korrekte SessionID des Benutzers der Methode fetchToken() übergeben wird. Der Benutzer verlässt unsere Seite zwangsläufig für den Login-Prozess für einen kurzen Augenblick. Wir möchten ihn auch nicht aus den Augen verlieren und seine SessionID wieder vergessen.

Die Implementierung der fetchToken Methode

Steigen wir direkt ein – viel Neues gibt es hier nicht:

public function fetchToken($sessionID)
{
    $callVerb  = 'FetchToken';
    $xmlBody   =
        '<SessionID>' . $sessionID . '</SessionID>';
    $response  = $this->_apiAdapter->callApi($callVerb, $xmlBody, false, false);

    if($response['Success'] == false) {
        return $response['Response']->ShortMessage;
    } else {
        return array(
            'token' => $response['Response']->eBayAuthToken,
            'expiration' => date('Y-m-d H:i:s', strtotime($response['Response']->HardExpirationTime))
        );
    }
}

Auch die fetchToken() Methode rufen wir direkt aus dem Controller auf. Wir übergeben die SessionID und erhalten im Idealfall ein zweielementiges Array mit Token und Gültigkeitsdauer des Tokens zurück.

Die Rückgabe der eBay trading API

Anhand dieser zwei API-Anfragen möchte ich hier die beiden XML API-Rückgaben vorstellen:

GetSessionID-Anfrage:

RuName =
'ruNameUnsererApplikation'

Der einzige hier zu übergebende Parameter ist der ruName unserer Applikation.

GetSessionID-Antwort:

Timestamp =
'2010-01-26T20:35:46.118Z'
Ack =
'Success'
Version =
637
Build =
'E637_INTL_BUNDLED_10223050_R1'
SessionID =
'b0**...*f74'

Als Antwort erhalten wir die SessionID.

FetchToken-Anfrage:

SessionID =
'b0**...*f74'

Auch hier muss nur ein Paramter – die SessionID – übergeben werden.

FetchToken-Antwort:

Timestamp =
'2010-01-26T20:31:58.283Z'
Ack =
'Success'
Version =
637
Build =
'E637_INTL_BUNDLED_10223050_R1'
eBayAuthToken =
'AuthToken'
HardExpirationTime =
'2011-07-20T20:27:32.000Z'

Die Antwort enthält den AuthToken und seine Gültigkeitsdauer.

Unsere Api_Adapter und User Consent Flow Implementierung ist damit fast fertig. Wie Controller und Views – und damit unser Frontend – implementiert werden, das soll Thema von Teil 4 dieses Guides sein.

Im ersten Teil dieses Guides hatten wir uns einen Überblick über den Consent Flow und eBay Authentifizierung unserer Nutzer geschaffen und so die Voraussetzung zur praktischen Umsetzung mit dem Zend Framework geschaffen.

Was werde ich hier in Teil 2 beschreiben?

Dieser Teil widmet sich dem Aufbau und Implementierung der Ebay_Api_Adapter Klasse, die wir verwenden werden um Anfragen an die eBay trading API zu senden. Wir benötigen Methoden zur Generierung und Auslieferung der Anfragen und eine geeignete Fehlerbehandlung. Exemplarisch und anhand von Code-Beispielen soll das hier in Teil 2 gezeigt werden.

Unsere Webapplikation muss nicht nur Anfragen an die eBay API senden, sondern auch den Überblick über SessionIDs und Tokens seiner Benutzer behalten. Wir sind also gezwungen diese – in unserem Fall in einer Datenbank – zwischen zu speichern:

Das bedeutet sogleich, dass unsere Applikation auch ein User-System haben muss, so dass die zurückgegebenen SessionIDs und Tokens mit den korrekten Benutzern verknüpft werden können. Ich möchte dies hier nicht noch ausführlich herleiten, sondern setze dieses Feature in der Basis-Applikation voraus. Ich nutze dafür Zend_Acl und ein klassisches User-System mit Register-, Login- und Logout Funktionen. Um voraus zu planen und es eventuell später mehren Nutzern gleichzeitig zu ermöglichen mit einem eBay Account zu arbeiten wird es in meiner Users Tabelle eine account_id und eine n:1 Verknüpfung mit der id des eBay Accounts in der Tabelle Accounts geben. Der Controller User und die dazugehörigen Funktionen existieren also schon.

Die benötigten Controller und Klassen

Für unsere eBay Applikation brauchen wir einen neuen Controller (Ebayauth) und eine neue Library (Ebay) in der wir unsere eBay spezifischen Klassen unterbringen. Wir benötigen:

• Einen Controller Ebayauth
• Fünf Actions (index, step1, step2, success und denied) und fünf Views für den Controller Ebayauth: index.phtml, step1.ajax.phtml, step2.ajax.phtml, success.phtml und denied.phtml
• Eine neue Library mit Namespace Ebay_ (nicht vergessen einen Autoloader im bootstrap anzupassen)
• Zwei Ebay_ Klassen: Ebay_Api_Adapter und Ebay_Auth_ConsentFlow
• Eine keys.xml in der Library Ebay

Die Klasse Ebay_Api_Adapter

Die keys.xml erlaubt es uns unsere API-Keys in einer schönen, ausgelagerten XML zu verwalten anstatt sie hardcoded in der Klasse zu lagern. Werfen wir zunächst einen Blick auf den Constructor, die setOptions Methode und die keys.xml:

class Ebay_Api_Adapter
{
    public function __construct($configfile = 'keys.xml')
    {
        $configfile = '../library/Ebay/' . $configfile;
        $configXml = new Zend_Config_Xml($configfile);
        $this->setOptions($configXml->keys->toArray());
        $this->setOptions($configXml->options->toArray());
    }

    // statische Instanz-Rückgabe
    public static function getInstance()
    {
        if (self::$_instance === null) {
            self::$_instance = new self();
        }
        return self::$_instance;
    }

    private function setOptions($options = array())
    {
        if(is_array($options)) {
            foreach($options as $key => $value) {
                $key = '_' . $key;
                $this->$key = $value;
            }
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?><ebay>
<keys>
    <devId>hier-eintragen</devId>
    <appId>hier-eintragen</appId>
    <certId>hier-eintragen</certId>
    <ruName>hier-eintragen</ruName>
</keys>
<options>
    <siteId>77</siteId>
    <warningLevel>High</warningLevel>
    <compatLevel>647</compatLevel>
    <errorLanguage>77</errorLanguage>
    <serverUrl><![CDATA[https://api.sandbox.ebay.com/ws/api.dll]]></serverUrl>
    <signinUrl><![CDATA[https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn]]></signinUrl>
</options></ebay>

Zu den Optionen in der keys.xml möchte ich noch ein paar Worte loswerden:

• siteID 77 entspricht eBay.de und errorLanguage 77 entspricht Deutsch
• warningLevel ist während wir mit der Sandbox arbeiten auf High gesetzt.
• compatLevel 647 ist die aktuelle eBay trading API Version mit der wir arbeiten möchten.
• serverURL ist unser Ansprechpartner für sämtliche API-Requests.
• signinURL verwenden wir für die Weiterleitung des Benutzers zum Consent Flow.

Für den HTTP-Request (POST) an die eBay trading API nutzen wir Zend_Http_Client. Die API möchte von uns eine Reihe HTTP-Header gesetzt sehen, bevor sie antworten wird. Dazu folgende Funktion:

private function setHeaders()
{
    $this->_headers = array (
        // Die eBay trading API Version, die wir unterstützen
        'X-EBAY-API-COMPATIBILITY-LEVEL: ' . $this->_compatLevel,

        // Unsere Keys und Zertifikate
        'X-EBAY-API-DEV-NAME: '    . $this->_devId,
        'X-EBAY-API-APP-NAME: '    . $this->_appId,
        'X-EBAY-API-CERT-NAME: '   . $this->_certId,

        // Der Name jeder eBay API Anfrage muss im Header noch einmal benannt werden
        'X-EBAY-API-CALL-NAME: '   . $this->_callVerb,
        'X-EBAY-API-SITEID: '      . $this->_siteId,

        // Wichtig: Den Content Type der Daten, die wir senden
        'Content-Type: text/xml; charset=utf-8'
    );
    $this->_request = new Zend_Http_Client();
    $this->_request->setUri($this->_serverUrl);
    $this->_request->setHeaders($this->_headers);
}

Sind die Header gesetzt, so können wir mit dem Zend_Http_Client Object ($this->_request) eine Anfrage senden. Der eigentliche Inhalt der Anfrage wird mittels POST mitgesendet. Das eigentliche Herzstück unseres API Adapters ist die Methode callApi, die wie folgt Abläuft:

1. Die Header setzen
   Wir übergeben der callApi Methode die Bezeichnung des Requests als Parameter und rufen damit die setHeaders() Methode auf. Diese baut die Header zusammen und erstellt ein neues Zend_Http_Client Objekt (siehe oben).
2. Den Request Body zusammensetzen
   Abhängig vom Typ der API Anfrage müssen wir den String des Request-Bodys (xml) zusammensetzen. Eine getSessionID verlangt andere (und weniger) Optionen als eine reguläre Anfrage.
3. Den Http_Client mit dem Request Body versehen und absenden
   Den zuvor in der setHeaders() Methode erstellten Http_Client übergeben wir den Request Body und senden den Request mittels POST an den API-Server. Die Rückgabe speichern wir in einer Variable.
4. Die Rückgabe auswerten und Fehler abfangen
   Die Rückgabe (xml) hat je nach API Anfrage eine bestimmte Form, die wir auswerten müssen. Hier muss auch unsere Fehlerbehandlung implementiert werden.

Hier die Implementierung der callApi Methode der Klasse Ebay_Api_Adapter:

public function callApi($verb, $request, $aditionalXml = true, $requestCredentials = true, $serverUrl = null)
{

    if($serverUrl == null) {
        $serverUrl = $this->_serverUrl;
    }

    $this->_callVerb = $verb;

    $this->setHeaders();

    $requestBody =
        '<?xml version="1.0" encoding="utf-8"?>' .
        '<' . $verb . ' xmlns="urn:ebay:apis:eBLBaseComponents">';

    // request Credentials werden nur bei regulären, nicht bei
    // getSessionID oder fetchToken Anfragen benötigt
    if($requestCredentials) {
        $requestBody .=
            '<RequesterCredentials>' .
            '<eBayAuthToken><![CDATA[' . $this->getToken() . ']]></eBayAuthToken>' .
            '</RequesterCredentials>';
    }

    // Auch diese Optionen benötigen wir nur für reguläre Anfragen
    if($aditionalXml) {
        $requestBody .=
            '<ErrorLanguage>' . $this->_errorLanguage . '</ErrorLanguage>' .
            '<WarningLevel>'  . $this->_warningLevel  . '</WarningLevel>';
    }

    $requestBody .=
        $request . '</' . $verb . '>';

    $this->_request->setUri($serverUrl);
    $this->_request->setRawData($requestBody);
    $response = $this->_request->request('POST');

    $this->responseHeader   = $response->getHeaders();
    $this->responseBody     = $response->getBody();

    // die Rückgabe wandeln wir in ein (hoffentlich gültiges)
    // XML Element um
    $xml = @simplexml_load_string($this->responseBody);

    // Existiert in der Rückgabe kein ACK-Feld (zB. weil der ebay
    // Server nicht geantwortet hat) oder ist es nicht 'Success',
    // so ist etwas schief gelaufen
    if(!isset($xml->Ack) || $xml->Ack != 'Success') {
        $errors = 'Keine Antwort von eBay';
        if(isset($xml->Errors))
            $errors = $xml->Errors;
        return array('Success' => false, 'Response' => $errors);
    }

    return array('Success' => true, 'Response' => $xml);
}

Die in Zeile 21 verwendete gettoken() Methode (siehe unten) gibt mir den mit dem User Account verknüpften Token zurück (Siehe Schaubild oben), ist aber optional und setzt ein User-Model voraus. Alternativ oder zu Testzwecken lässt sich der Token auch in der keys.xml hinterlegen und der Funktionsaufruf in Zeile 21 durch ein $this->_token() ersetzen.

public function getToken()
{
    $accountId        = Zend_Auth::getInstance()->getIdentity()->account_id;
    $modelAccount    = new Model_Account();
    return $modelAccount->getEbayToken($accountId);
}

Mit dieser Implementierung können wir nun beliebige eBay trading API Anfragen versenden. Im dritten Teil dieses Guides beschreibe ich die Implementierung der Klasse Ebay_Auth_ConsentFlow.

Erst mit guter Dokumentation macht es Sinn.

Und gut dokumentiert, das ist sowohl das Zend Framework, wie auch die eBay trading API. Sinn macht es also beide zu kombinieren um schnell große eBay-Webapplikationen zu schaffen. Das Zend Framework erlaubt ein rapid PHP development und die eBay trading API ermöglicht es so ziemlich alles, was der Nutzer auf der eBay-Webseite sowieso schon tun kann in die eigenen Webapplikation zu klonen. Natürlich gibt es auch hier best practices – wie ich das ganze angegangen bin, dass möchte ich hier im folgenden beschreiben.

Was werde ich hier in Teil 1 beschreiben?

Webapplikationen, die die eBay trading API verwenden und damit für einen eBay Nutzer in seinem Namen Aktionen auf der eBay-Webseite durchführen, müssen einen Authorisationsprozess durchlaufen. Nutzer der Webapplikation müssen sich als eBay Nutzer identifizieren und die Applikation authorisieren Aktionen in ihrem Namen durchzufüren. Diesen Prozess möchte ich hier exemplarisch in einer Webapplikation mit Hilfe des Zend Framework abbilden und so den ersten Teil einer jeden eBay-Webapplikation beispielhaft beschreiben.

Was benötigen wir um mit der eBay trading API zu arbeiten?

1. Einen eBay Developers Program Account (https://developer.ebay.com)
   Das eBay Developers Program bietet Zugriff auf die eBay APIs und eine umfangreiche Dokumentation und Support. Es existieren Foren, Referenzen und zahlreiche Code-Beispiele. Ein solcher Account ist zwingen notwendig um die eBay trading API überhaupt ansprechen und nutzen zu können.
2. Mindestens einen eBay Sandbox Account (https://sandbox.ebay.com)
   Es ist notwendig seine Applikationen in der eBay Sandbox zu entwickeln. Die Sandbox ist eine der original eBay Umgebung ähnelnde Spielwiese in der man zunächst einmal nichts kaputt machen und nach Lust und Laune seine Programme entwickeln und testen kann. Mindestens einen Account brauchen wir hier um in dessen Namen die trading API nutzen zu können. Empfehlen kann ich auch einen zweiten Account um beispielsweise und zu testzwecken Produkte des ersten Accounts zu ersteigern.
3. Ein Set Sandbox API Keys (werden über den developers Account angelegt)
   Dazu zählen:
   • Die devID – sie identifiziert uns als Entwickler beim Verwenden der eBay trading API
   • Die AppID – sie identifiziert unsere Applikation beim Verwenden der eBay trading API
   • Eine CertID – ein Zertifikat, dass wir beim Ansprechen der eBay trading API benötigen
   • Ein RuName - mit dem wir das eBay Anmeldeformular beim Authorisierungsprozess gestalten können
     Der RuName wird beim Konfigurieren des Consent Flow (der Authorisierungsprozess) im developers Account generiert. Uns wird beispielsweise die Möglichkeit gegeben das Anmeldeformular mit einem Logo unserer Applikation zu versehen.

Was benötigen wir um mit dem Zend Framework zu arbeiten?

1. Eine aktuelle Version des Zend Servers (Community Edition) und das dazugehörige Zend Framework. Ich verwende das Zend Framework in der Version 1.9.5 und den Zend Server mit der PHP Version 5.2.11.
2. Ich empfehle das Entwicklertool Zend Studio und Erfahrung, was das Arbeiten mit PHP, XML, dem Zend Framework und die Konfiguration eines Webservers angeht. Sollte das Zend Framework bis jetzt völlig unbekannt sein, dann möchte ich zunächst auf die zahlreichen Bücher zum Thema und die vielen Tutorials im Internet verweisen. Ich werde hier keine Einführung in das Framework geben.

Was benötigen wir sonst noch für unsere eBay Webapplikation?

1. Einen MySQL Server oder eine andere Datenbank. Ich verwende hier eine MySQL Datenbank in Verbindung mit der Zend_Db_Table Class, die eine abstraktion Layer besitzt und damit auch für andere Datenbanktypen verwendet werden kann.
2. Ein JavaScript Framework für unsere Ajax-Calls. Natürlich ist kein Framework notwendig, aber es macht die Frontendentwicklung und vor allem unsere Ajax Funktionen wunderbar einfach zu implementieren. Ich verwende mootools, kann aber auch jQuery empfehlen. Wichtig bei der Auswahl des Frameworks ist es, dass die Ajax-Requests ein XmlHttpRequest-Header mitsenden.
3. Eine Basis-Applikation mit einem eingerichtetem Layout, die es dem Benutzer erlaubt sich in unserer Applikation einzuloggen.

Der eBay User Consent Flow

Wenn all das geklärt wurde, dann werden wir hier in Teil1 zunächst mit der Theorie beginnen: Wie sieht der User Consent Flow bei eBay aus? Dazu folgende Grafik:

1. Schritt
   Unsere Applikation wird die eBay API nach einer SessionID beten. Dazu schicken wir den ruName unserer Applikation mit, damit eBay das konfigurierte Anmeldeformular (inklusive unseres tollen Applikationslogos und der Redirect-URLs) generieren und mit der SessionID verknüpfen kann. Als Antwort erhalten wir also eine SessionID, die wir dann verwenden um die Parameter der URL des Anmeldeformulars zu generieren und den Benutzer dann im zweiten Schritt …
2. Schritt
   … an diese URL weiterzuleiten. Dort gibt er sein eBay Passwort und Nutzernamen ein und bestätigt, dass er unserer Webapplikation erlaubt in seinem Namen auf eBay Aktionen durchzuführen. Hat er bestätigt, leitet eBay den Benutzer wieder zurück zu unserer Applikation, die daraufhin im dritten Schritt …
3. Schritt
   … eine fetchToken Anfrage an die eBay API senden kann. Mit der fetchToken Anfrage geben wir gleich die zuvor erhaltene SessionID mit. Wurde diese SessionID verwendet und hat sich der Nutzer mit dieser SessionID im Zuge des Schritt 2 auch korrekt angemeldet, so erhalten wir einen ca. 900 Zeichen langes Token zurück gibt. Dieses Token muss unsere Applikation bei jeder API-Anfrage mitsenden und sich so autorisieren.

Wie die Theorie mit dem Zend Framework möglichst schnell und unkompliziert in die Praxis umgesetzt werden kann werde ich im zweiten Teil dieses Guides beschreiben. Ich gehe konkret auf die benötigten Klassen ein und werde zahlreiche Code-Beispiele geben.