Dieser Beitrag beschreibt kurz wie man mit Zend_Validate prüfen kann, ob eine URL / URI syntaktisch korrekt und die verlinkte Ressource erreichbar ist.

Aufbau einer URL prüfen

Ein eigenständiger Validator ist im Zend Framework nicht vorhanden welcher den Aufbau einer URL / URI prüft. Jedoch bietet Zend_URI mit der Methode check() hier eine entsprechende Funktionalität an. Auf diese greifen wir in einem selbst geschriebenen Validator zurück:

class Validator_Uri extends Zend_Validate_Abstract {
	const INVALID_URI = 'invalidUri';
	protected $_messageTemplates = array (self::INVALID_URI => "'%value%' is not a valid URI" );

	public function isValid($value) {
		$this->_setValue ($value);

		if (! Zend_Uri::check ($value)) {
			$this->_error ( self::INVALID_URI );
			return false;
		}

		return true;
	}
}

Erreichbarkeit einer URL prüfen

Es ist nicht nur wichtig, dass die Ressourcenangabe in Ihrem Aufbau korrekt ist, sondern auch, dass sich dahinter ein erreichbares Objekt (Webseite, Bild, PDF etc.) befindet.
Mit Hilfe der PHP-Funktion get_headers prüfen wir den Antwort-Header auf Erfolg (200 OK). Mit Hilfe des @ unterdrücken wir eine Fehler-Ausgabe von PHP, wenn der String an get_headers keine URL sein sollte:

class Validator_Uri_Reachable extends Zend_Validate_Abstract {
	const URI_REACHABLE = 'uriReachable';
	protected $_messageTemplates = array (self::URI_REACHABLE => "'%value%' not reachable" );

	public function isValid($value) {
		$this->_setValue ( $value );

		$headers = @get_headers ( $value );
		if (! preg_match ( '/200 OK/', $headers [0] )) {
			$this->_error ();
			return false;
		}

		return true;
	}
}

Entsprechend kann dann in einem Zend-Formular z.B. eine Homepageadresse geprüft werden:

$hpUrl = new Zend_Form_Element_Text ( 'hpUrl' );
$hpUrl->setLabel ( 'Homepage:' )
			  ->setDescription ( 'Ihre Homepage- oder Blog-Adresse' );
			  ->setAttrib ( 'value', 'http://' )
			  ->addValidator ( new Validator_Uri() )
			  ->addValidator ( new Validator_Uri_Reachable() )

Weitere Links:

• Zend Framework Dokumentation – Schreiben von Prüfern
• PHP – Funktion getheaders
• Wikipedia – Aufbau einer URL
• ROAE Blog – Tools für Regex / Reguläre Ausdrücke

Ein kurzer Beitrag welcher beschreibt, wie man unter Windows das Passwort des Benutzers root zurücksetzen, bzw. neu setzen kann, wenn man es vergessen hat.

Um das vergessene Passwort des root Benutzers bei MySQL neu zu setzen sind 3 Schritte notwendig:

• MySQL-Daemon beenden
• Init-Datei mit neuem Passwort anlegen
• MySQL-Daemon mit Init-Datei starten – Passwort wird auf “Init-Passwort” gesetzt

Die notwendigen Schritte werden gefolgt beschrieben bei Verwendung von Windows 7.

Den MySQL-Daemon beenden

Ein laufender MySQL-Daemon muss zuerst beendet werden, damit wir das Passwort ändern können. Hier werden zwei Varianten beschrieben, wobei Variante 1 klar zu empfehlen ist.

Variante 1: MySQL-Daemon über die Computerverwaltung beenden

Rufen Sie die Computerverwaltung über die folgende Schritte auf.

In der Computerverwaltung wählen Sie links im Baum den Bereich Dienste (1), rechts MySQL (2) und beenden den Dienst zuletzt über das Stop-Icon (3).

Variante 2: MySQL-Daemon über den Task-Manager beenden/ killen

(Diesen Schritt brauchen Sie nur durchführen, wenn Sie über die Computerverwaltung MySQL nicht beenden konnten).

Starten Sie den Task-Manger durch einen Rechtsklick auf die Taskleiste und einen Klick auf Task-Manager starten. Klicken Sie im Task-Manager auf den Button Prozesse aller Benutzer anzeigen, um auch die Systemprozesse und somit MySQL gelistet zu bekommen.

Auch Systemprozesse anzeigen

Klicken Sie auf Abbildname (1) um alle Prozesse alphabetisch zu sortieren. Selektieren Sie nun in der Liste den Eintrag mysqld.exe (2). Diesen Prozess können Sie nun durch Prozess beenden (3) beenden. Bestätigen Sie die Aktion in dem Sie bei der Sicherheitsabfrage erneut auf Prozess beenden (4) klicken.

Killen von MySQL über den Task-Manager

Init-Datei anlegen

Die Init-Datei enthält Anweisungen, welche beim Starten von MySQL direkt ausgeführt werden. Wir hinterlegen in ein solchen Datei nun eine Direktive, um das Passwort des Users root zu ändern.

Legen Sie auf dem Desktop eine Datei mit dem Namen mysql-init.txt an. Öffen Sie Datei und kopieren Sie folgende SQL-Anweisung hinein

SET PASSWORD FOR 'root'@'localhost' = PASSWORD('geheim');

Natürlich können Sie statt geheim jedes erdenkliche Passwort verwenden.

MySQL-Daemon mit init-Datei starten

Nun starten wir den MySQL-Daemon mit der init-Datei, welcher wir zuvor erstellt haben.

Öffnen Sie eine Eingabeaufforderung (Startmenü -> CMD -> ENTER). Geben Sie nun folgende Anweisung ein:

<Pfad mysqld.exe> --init-file=C:\Users\<Ihr Windowsbenutzer>\Desktop\my-init.txt --console

So sieht der Aufruf z.B. aus wenn MySQL in einem Unterordner namens Zend installiert ist:

mysqld mit --init-file aufgerufen

Das Passwort wurde nun auf Ihren Wert, welchen Sie im Schritt Init-Datei anlegen festgelegt haben, gesetzt. Beenden Sie nun die Eingabeaufforderung durch STRG + C. Starten Sie nun anschließend wieder mysql über die Diensteverwaltung (siehe oben), in dem Sie das Start-Icon benutzen.

Anschließend können Sie wie gewohnt MySQL nutzen – jetzt aber mit Ihrem neuen Passwort.

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.

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!

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.