# Zend_Service_Delicious

## Einführung

Zend_Service_Delicious ist eine simple API, um die XML- und JSON-Webservices von del.icio.us nutzen zu können. Diese Komponente bietet Lese- und Schreibzugriff auf Beiträge bei del.icio.us, sofern man die nötigen Zugrffisrechte vorweist.

Alle Beiträge abrufen

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getAllPosts();

    foreach ($posts as $post) {
        echo "--\n";
        echo "Title: {$post->getTitle()}\n";
        echo "Url: {$post->getUrl()}\n";
    }

## Beiträge abrufen

Zend_Service_Delicious bietet drei Möglichkeiten, um Beiträge von del.icio.us abzurufen: getPosts(), getRecentPosts() und getAllPosts(). Jede dieser Methoden liefert eine Instanz der Klasse Zend_Service_Delicious_PostList, welche die abgerufenen Beiträge beinhaltet.

    /**
     * Beiträge werden je nach Parametern geladen. Ist kein Datum oder
     * kein URL gegeben, so wird standardmäßig das aktuelleste Datum
     * verwendet.
     *
     * @param string $tag Optionaler Filter nach einem bestimmten tag
     * @param Zend_Date $dt Optionaler Filter nach Datum
     * @param string $url Optionaler Filter nach URL
     * @return Zend_Service_Delicious_PostList
     */
    public function getPosts($tag = null, $dt = null, $url = null);

    /**
     * Die letzten x Beiträge abrufen.
     *
     * @param string $tag   Optionaler Filter nach einem bestimmten tag
     * @param string $count Maximale Anzahl der Beiträge, die
     *                      zurückgeliefert werden (standardmäßig 15)
     * @return Zend_Service_Delicious_PostList
     */
    public function getRecentPosts($tag = null, $count = 15);

    /**
     * Alle Beiträge abrufen
     *
     * @param string $tag Optionaler Filter nach einem bestimmten tag
     * @return Zend_Service_Delicious_PostList
     */
    public function getAllPosts($tag = null);

## Zend_Service_Delicious_PostList

Instanzen dieser Klasse werden von den Methoden getPosts(), getAllPosts(), getRecentPosts() und getUserPosts() der Klasse Zend_Service_Delicious zurückgegeben.

Für den leichteren Zugriff implementiert diese Klasse die Interfaces `Countable`, `Iterator` and`ArrayAccess`.

Zugriff auf Beitragslisten

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getAllPosts();

    // Beiträge zählen
    echo count($posts);

    // Iteration über die Beitragsliste
    foreach ($posts as $post) {
        echo "--\n";
        echo "Title: {$post->getTitle()}\n";
        echo "Url: {$post->getUrl()}\n";
    }

    // speziellen Beitrag über Arrayzugriff erhalten
    echo $posts[0]->getTitle();

Die Methoden ArrayAccess::offsetSet() und ArrayAccess::offsetUnset() werfen in dieser Implementierung Ausnahmen (Exceptions). Dadurch werfen Codes, wie z.B. `unset($posts[0]);` oder `$posts[0] = 'A';` Exceptions, da nur Leserechte für die Eigenschaften bestehen.

Beitragslisten-Objekte haben zwei integrierte Filter-Möglichkenten. Die Listen können nach Tags und nach URLs gefiltert werden.

Eine Beitragsliste nach gewissen tags filtern

Beiträge mit speziellen tags können durch die Methode withTags() aus der Liste herausgefiltert werden. Der Einfachheit halber, kann die Methode withTag() verwendet werden, wenn nur nach einem einzigen tag gefiltert werden soll.

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getAllPosts();

    // Alle Beiträge ausgeben, denen die tags "php" und "zend" zugeordnet sind
    foreach ($posts->withTags(array('php', 'zend')) as $post) {
        echo "Title: {$post->getTitle()}\n";
        echo "Url: {$post->getUrl()}\n";
    }

Eine Beitragsliste nach URLs filtern

Beiträge können mit Hilfe der Methode withUrl() nach einer speziellen URL gefiltert werden indem ein passender regulärer Ausdruck spezifiziert wird.

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getAllPosts();

    // Beiträge ausgeben, deren URL "/help/" enthält
    foreach ($posts->withUrl('/help/') as $post) {
        echo "Title: {$post->getTitle()}\n";
        echo "Url: {$post->getUrl()}\n";
    }

## Das Bearbeiten von Beiträgen

Beiträge bearbeiten

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getPosts();

    // Titel setzen
    $posts[0]->setTitle('New title');
    // Änderungen speichern
    $posts[0]->save();

Verkettung von Methodenaufrufen

Jede set-Methode gibt das Beitragsobjekt zurück, so dass man die Methodenaufrufe verketten kann.

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getPosts();

    $posts[0]->setTitle('New title')
             ->setNotes('New notes')
             ->save();

## Das Löschen von Beiträgen

Es existieren zwei Wege, um einen Beitrag zu löschen. Zum Einen explizit über den Beitrags-URL oder zum Anderen durch den Aufruf der Methode delete() mit dem Objekt, welches den zu löschenden Beitrag repräsentiert.

Beiträge löschen

    $delicious = new Zend_Service_Delicious('username', 'password');

    // Explizites Löschen eines Beitrags über einen URL
    $delicious->deletePost('http://framework.zend.com');

    // Löschen eines Beitrags über den Aufruf der delete()-Methode
    $posts = $delicious->getPosts();
    $posts[0]->delete();

    // eine alternative Anwendung von deletePost()
    $delicious->deletePost($posts[0]->getUrl());

## Das Hinzufügen von neuen Beiträgen

Um einen Beitrag hinzuzufügen, muss zu Beginn die Methode createNewPost() aufgerufen werden, welche eine Instanz der Klasse Zend_Service_Delicious_Post zurückgibt. Danach kann mit Hilfe des erhaltenen Objekts der Beitrag verändert werden. Nach der Änderung muss die save()-Methode aufgerufen werden, damit die Änderungen in die del.icio.us-Datenbank übernommen werden.

Einen Beitrag hinzufügen

    $delicious = new Zend_Service_Delicious('username', 'password');

    // Neuen Beitrag erstellen, ändern und abspeichern
    // (Verkettung der Methodenaufrufe)
    $delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
              ->setNotes('Zend Framework Homepage')
              ->save();

    // Neuen Beitrag erstellen, ändern und abspeichern (ohne Verkettung)
    $newPost = $delicious->createNewPost('Zend Framework',
                                         'http://framework.zend.com');
    $newPost->setNotes('Zend Framework Homepage');
    $newPost->save();

## Tags

Tags

    $delicious = new Zend_Service_Delicious('username', 'password');

    // Abrufen aller tags
    print_r($delicious->getTags());

    // Umbenennen des tags "ZF" zu "Zend Framework"
    $delicious->renameTag('ZF', 'zendFramework');

## Bundles

Bundles

    $delicious = new Zend_Service_Delicious('username', 'password');

    // get all bundles
    print_r($delicious->getBundles());

    // delete bundle someBundle
    $delicious->deleteBundle('someBundle');

    // add bundle
    $delicious->addBundle('newBundle', array('tag1', 'tag2'));

## Öffentliche Daten

Die del.icio.us webservice API ermöglicht den Zugriff auf die öffentlichen Daten aller Nutzer.

Methoden, um öffentliche Daten abzurufen

Name | Beschreibung | Rückgabewert
--- | --- | ---
getUserFans() | Liefert die Fans eines Nutzers | Array
getUserNetwork() | Liefert das Netzwerk eines Nutzers | Array
getUserPosts() | Liefert alle Beiträge eines Nutzers | Zend_Service_Delicious_PostList
getUserTags() | Liefert alle tags, die der Nutzer vergeben hat | Array

Sollten nur diese Methoden verwendet werden, ist dem Konstruktor der Klasse Zend_Service_Delicious bei der Instanzierung kein Nutzername in Kombination mit dem entsprechenden Passwort zu übergeben.

öffentliche Daten auslesen

    // Nutzername und Passwort werden nicht benötigt
    $delicious = new Zend_Service_Delicious();

    // Laden der Fans eines Nutzers
    print_r($delicious->getUserFans('someUser'));

    // Laden des Netzwerks eines Nutzers
    print_r($delicious->getUserNetwork('someUser'));

    // Laden der vergebenen tags eines Nutzers
    print_r($delicious->getUserTags('someUser'));

### Öffentliche Beiträge

Wenn öffentliche Beiträge über die Methode getUserPosts() bezogen werden wird ein Zend_Service_Delicious_PostList Objekt zurückgegeben, welches die einzelnen Beiträge in einer Liste von Zend_Service_Delicious_SimplePost-Objekten speichert. Diese Objekte enthalten Basisinformationen über den Beitrag, wie z.B. den URL, den Titel, die Notizen und Tags.

Methoden der Klasse Zend_Service_Delicious_SimplePost

Name | Beschreibung | Rückgabewert
--- | --- | ---
getNotes() | Liefert die Beschreibung zu einem Beitrag | String
getTags() | Liefert die tags zu einem Beitrag | Array
getTitle() | Liefert den Titel eines Beitrags | String
getUrl() | Liefert den URL eines Beitrags | String

## HTTP client

Zend_Service_Delicious verwendet die Klasse Zend_Rest_Client, um HTTP-Request an den del.icio.us Webservice zu schicken. Um einzustellen, welchen HTTP Client Zend_Service_Delicious verwenden soll, muss der HTTP Client der Klasse Zend_Rest_Client geändert werden.

Veränderung des HTTP clients der Klasse Zend_Rest_Client

    $myHttpClient = new My_Http_Client();
    Zend_Rest_Client::setHttpClient($myHttpClient);

Sollte man mehr als einen Request mit Zend_Service_Delicious senden, ist es sinnvoll den HTTP Client so zu konfigurieren, dass die Verbindungen offen gehalten werden, um die Geschwindigkeit der Requests zu erhöhen.

Konifguration des HTTP clients, so dass Verbindungen geöffnet bleiben

    Zend_Rest_Client::getHttpClient()->setConfig(array(
            'keepalive' => true
    ));

Bei der Instanzierung eines Zend_Service_Delicious Objekts wird der SSL Transport der Klasse Zend_Rest_Client auf `'ssl'` anstatt auf `'ssl2'` gesetzt, da del.icio.us einige Probleme mit `'ssl2'` hat. So kann es vorkommen, dass die Vervollständigung eines Request sehr lange (um die zwei Sekunden) dauert.