repo_zf1/documentation/manual/fr/module_specs/Zend_Service_Delicious.xml

<!-- EN-Revision: 11146 -->
<sect1 id="zend.service.delicious">
    <title>Zend_Service_Delicious</title>

    <sect2 id="zend.service.delicious.introduction">
        <title>Introduction</title>

        <para><classname>Zend_Service_Delicious</classname> est une API pour accéder aux Web services XML et JSON de <ulink
        url="http://del.icio.us">del.icio.us</ulink>. Ce composant vous donne, si vous avez les droits, un accès en
        lecture-écriture à vos entrées sur del.icio.us. Il permet également un accès en lecture seule aux données de
        tous les utilisateurs.</para>

        <example id="zend.service.delicious.introduction.getAllPosts">
            <title>Récupérer toutes vos entrées</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('identifiant', 'mot_de_passe');
$posts = $delicious->getAllPosts();

foreach ($posts as $post) {
    echo "--\n";
    echo "Titre: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.retrieving_posts">
        <title>Récupérer vos entrées</title>

        <para><classname>Zend_Service_Delicious</classname> fournis trois méthodes pour récupérer vos entrées :
        <code>getPosts()</code>, <code>getRecentPosts()</code> et <code>getAllPosts()</code>. Elles retournent toutes
        une instance de la classe <classname>Zend_Service_Delicious_PostList</classname>, qui contient toutes les entrées
        récupérées.</para>

        <programlisting role="php"><![CDATA[
/**
 * Récupère les entrées correspondants aux arguments. Si la date ou
 * l'url n'est pas précisée, la date la plus récente
 * sera prise en compte.
 *
 * @param string $tag Optionnel pour filtrer par tag
 * @param Zend_Date $dt Optionnel pour filtrer par date
 * @param string $url Optionnel pour filtrer par url
 * @return Zend_Service_Delicious_PostList
 */
public function getPosts($tag = null, $dt = null, $url = null);

/**
 * Récupère les dernières entrées
 *
 * @param string $tag Optionnel pour filtrer par tag
 * @param string $count Nombre maximum d'entrées à récupérer
 *                     (15 par défaut)
 * @return Zend_Service_Delicious_PostList
 */
public function getRecentPosts($tag = null, $count = 15);

/**
 * Récupère toutes les entrées
 *
 * @param string $tag Optionnel pour filtrer par tag
 * @return Zend_Service_Delicious_PostList
 */
public function getAllPosts($tag = null);
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.delicious.postlist">
        <title>Zend_Service_Delicious_PostList</title>

        <para>Des instances de cette classe sont retournées par les méthodes <code>getPosts()</code>,
        <code>getAllPosts()</code>,<code>getRecentPosts()</code>, et <code>getUserPosts()</code> de
        <classname>Zend_Service_Delicious</classname>.</para>

        <para>Pour faciliter l'accès au données cette classe implémente les interfaces <code>Countable</code>,
        <code>Iterator</code>, et<code>ArrayAccess</code>.</para>

        <example id="zend.service.delicious.postlist.accessing_post_lists">
            <title>Accéder à la liste des entrées</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');
$posts = $delicious->getAllPosts();

// Affiche le nombre d'entrées
echo count($posts);

// Itération sur les entrées
foreach ($posts as $post) {
    echo "--\n";
    echo "Titre: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}

// Affiche une entrée en utilisant un tableau
echo $posts[0]->getTitle();
]]></programlisting>
        </example>

        <note>
            <para>Dans cette implémentation les méthodes <code>ArrayAccess::offsetSet()</code> et
            <code>ArrayAccess::offsetUnset()</code> lèvent des exceptions. Ainsi, du code tel que
            <code>unset($posts[0]);</code> ou <code>$posts[0] = 'A';</code> lèvera une exception car ces propriétés sont
            en lecture seule.</para>
        </note>

        <para>Les objets d'entrées ont deux capacités de filtrage incorporées. Les entrées peuvent être filtrées par
        étiquette et URL.</para>

        <example id="zend.service.delicious.postlist.example.withTags">
            <title>Filtrage d'une entrée par une étiquette spécifique</title>

            <para>Les entrées peuvent être filtrées par une (des) étiquette(s) spécifique(s) en utilisant
            <code>withTags()</code>. Par confort, <code>withTag()</code> est aussi fourni quand il est nécessaire 'e ne
            spécifier qu'une seule étiquette</para>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');
$posts = $delicious->getAllPosts();

// Affiche les entrées ayant les étiquettes "php" et "zend"
foreach ($posts->withTags(array('php', 'zend')) as $post) {
    echo "Title: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}
]]></programlisting>
        </example>

        <example id="zend.service.delicious.postlist.example.byUrl">
            <title>Filtrage d'une entrée par URL</title>

            <para>Les entrées peuvent être filtrées par URL correspondant à une expression régulière spécifiée en
            utilisant la méthode <code>withUrl()</code> :</para>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');
$posts = $delicious->getAllPosts();

// Affiche les entrées ayant "help" dans l'URL
foreach ($posts->withUrl('/help/') as $post) {
    echo "Title: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.editing_posts">
        <title>Édition des entrées</title>

        <example id="zend.service.delicious.editing_posts.post_editing">
            <title>Édition d'une entrée</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');
$posts = $delicious->getPosts();

// change le titre
$posts[0]->setTitle('Nouveau Titre');
// sauvegarde le changement
$posts[0]->save();
]]></programlisting>
        </example>

        <example id="zend.service.delicious.editing_posts.method_call_chaining">
            <title>Enchaînement des appels de méthode</title>

            <para>Toutes les méthodes "setter" renvoient l'objet <classname>Zend_Service_Delicious_PostList</classname> vous
            pouvez donc chaîner les appels aux méthodes en utilisant une interface fluide.</para>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');
$posts = $delicious->getPosts();

$posts[0]->setTitle('Nouveau Titre')
         ->setNotes('Nouvelle note')
         ->save();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.deleting_posts">
        <title>Supprimer des entrées</title>

        <para>Il y a deux moyens de supprimer une entrée, en spécifiant son URL ou en appelant la méthode
        <code>delete()</code> sur un objet Zend_Service_Delicious_PostList.</para>

        <example id="zend.service.delicious.deleting_posts.deleting_posts">
            <title>Suppression d'une entrée</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');

// en spécifiant l' URL
$delicious->deletePost('http://framework.zend.com');

// en appelant la méthode de l'objet Zend_Service_Delicious_PostList
$posts = $delicious->getPosts();
$posts[0]->delete();

// une autre façon d'utiliser deletePost()
$delicious->deletePost($posts[0]->getUrl());
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.adding_posts">
        <title>Ajout d'entrées</title>

        <para>Pour ajouter une entrée vous devez appeler la méthode <code>createNewPost()</code>, qui renvoie un objet
        <classname>Zend_Service_Delicious_Post</classname>. Quand vous éditez l'entrée, vous devez la sauvegarder dans la base de
        donnée de del.icio.us en appelant la méthode <code>save()</code>.</para>

        <example id="zend.service.delicious.adding_posts.adding_a_post">
            <title>Ajouter une entrée</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');

// créé et sauvegarde une nouvelle entrée (en chainant les méthodes)
$delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
          ->setNotes('Page d\'accueil de Zend Framework')
          ->save();

// créé et sauvegarde une nouvelle entrée (sans enchaîner les méthodes)
$newPost = $delicious->createNewPost('Zend Framework',
                                     'http://framework.zend.com');
$newPost->setNotes('Page d\'accueil de Zend Framework');
$newPost->save();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.tags">
        <title>Les étiquettes ("tags")</title>

        <example id="zend.service.delicious.tags.tags">
            <title>Récupérer les étiquettes</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');

// récupère tous les étiquettes
print_r($delicious->getTags());

// renomme l'étiquette "ZF" en "zendFramework"
$delicious->renameTag('ZF', 'zendFramework');
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.bundles">
        <title>Les groupes d'étiquettes</title>

        <example id="zend.service.delicious.bundles.example">
            <title>Gestion des groupes d'étiquette</title>

            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('nom_d_utilisateur',
                                        'mot_de_passe');

// récupère tous les groupes
print_r($delicious->getBundles());

// efface le groupe someBundle
$delicious->deleteBundle('someBundle');

// ajoute un groupe
$delicious->addBundle('newBundle', array('tag1', 'tag2'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.public_data">
        <title>Données publiques</title>

        <para>L'API Web del.icio.us autorise l'accès aux données publiques de tous les utilisateurs.</para>

        <table id="zend.service.delicious.public_data.functions_for_retrieving_public_data">
            <title>Méthodes pour récupérer les données publiques</title>

            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Nom</entry>

                        <entry>Description</entry>

                        <entry>Type de retour</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><code>getUserFans()</code></entry>

                        <entry>Récupère les fans d'un utilisateur</entry>

                        <entry>Array</entry>
                    </row>

                    <row>
                        <entry><code>getUserNetwork()</code></entry>

                        <entry>Récupère le réseau d'un utilisateur</entry>

                        <entry>Array</entry>
                    </row>

                    <row>
                        <entry><code>getUserPosts()</code></entry>

                        <entry>Récupère les entrées d'un utilisateur</entry>

                        <entry>Zend_Service_Delicious_PostList</entry>
                    </row>

                    <row>
                        <entry><code>getUserTags()</code></entry>

                        <entry>Récupère les étiquettes d'un utilisateur</entry>

                        <entry>Array</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para>Si vous utilisez uniquement ces méthodes, le nom d'utilisateur et le mot de passe ne sont pas
            obligatoires pour créer un nouvel objet <classname>Zend_Service_Delicious</classname>.</para>
        </note>

        <example id="zend.service.delicious.public_data.retrieving_public_data">
            <title>Récupérer les données publiques</title>

            <programlisting role="php"><![CDATA[
// nom d'utilisateur et mot de passe optionnels
$delicious = new Zend_Service_Delicious();

// récupère les fans de l'utilisateur someUser
print_r($delicious->getUserFans('someUser'));

// récupère le réseau de l'utilisateur someUser
print_r($delicious->getUserNetwork('someUser'));

// récupère les Tags de l'utilisateur someUser
print_r($delicious->getUserTags('someUser'));
]]></programlisting>
        </example>

        <sect3 id="zend.service.delicious.public_data.posts">
            <title>Entrées publiques</title>

            <para>Quand vous récupérez des entrées publiques, la méthode <code>getUserPosts()</code> retourne un objet
            <classname>Zend_Service_Delicious_PostList</classname> qui contient des objets
            <classname>Zend_Service_Delicious_SimplePost</classname>. Ces derniers contiennent des informations basiques sur
            l'entrée : URL, title, notes, and tags.</para>

            <table id="zend.service.delicious.public_data.posts.SimplePost_methods">
                <title>Méthodes de la classe <classname>Zend_Service_Delicious_SimplePost</classname></title>

                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Nom</entry>

                            <entry>Description</entry>

                            <entry>Type de retour</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><code>getNotes()</code></entry>

                            <entry>Récupère les notes de l'entrée</entry>

                            <entry>String</entry>
                        </row>

                        <row>
                            <entry><code>getTags()</code></entry>

                            <entry>Récupère les étiquettes de l'entrée</entry>

                            <entry>Array</entry>
                        </row>

                        <row>
                            <entry><code>getTitle()</code></entry>

                            <entry>Récupère le titre de l'entrée</entry>

                            <entry>String</entry>
                        </row>

                        <row>
                            <entry><code>getUrl()</code></entry>

                            <entry>Récupère l'URL de l'entrée</entry>

                            <entry>String</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>

    <sect2 id="zend.service.delicious.httpclient">
        <title>Client HTTP</title>

        <para><classname>Zend_Service_Delicious</classname> utilise <classname>Zend_Rest_Client</classname> pour effectuer les requêtes HTTP
        sur le Web service de del.icio.us. Pour modifier le client HTTP utiliser par
        <classname>Zend_Service_Delicious</classname>, vous devez modifier le client HTTP de <classname>Zend_Rest_Client</classname>.</para>

        <example id="zend.service.delicious.httpclient.changing">
            <title>Modifier le client HTTP de <classname>Zend_Rest_Client</classname></title>

            <programlisting role="php"><![CDATA[
$myHttpClient = new My_Http_Client();
Zend_Rest_Client::setHttpClient($myHttpClient);
]]></programlisting>
        </example>

        <para>Quand vous effectuez plus d'une requête avec <classname>Zend_Service_Delicious</classname> vous pouvez accélérez vos
        requêtes en configurant votre client HTTP pour qu'il ne ferme pas les connexions.</para>

        <example id="zend.service.delicious.httpclient.keepalive">
            <title>Configurer votre client HTTP pour qu'il ne ferme pas les connexions</title>

            <programlisting role="php"><![CDATA[
Zend_Rest_Client::getHttpClient()->setConfig(array(
        'keepalive' => true
));
]]></programlisting>
        </example>

        <note>
            <para>En raison de quelques problèmes de del.icio.us avec <code>'ssl2'</code> (environs 2 secondes pour une
            requête), quand un objet <classname>Zend_Service_Delicious</classname> est construit, le transport SSL de
            <classname>Zend_Rest_Client</classname> est configuré sur <code>'ssl'</code> au lieu de la valeur par défaut
            <code>'ssl2'</code>.</para>
        </note>
    </sect2>
</sect1>