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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<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 <acronym>API</acronym> pour accéder aux Web
            services <acronym>XML</acronym> et <acronym>JSON</acronym> 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 language="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 : <methodname>getPosts()</methodname>, <methodname>getRecentPosts()</methodname> et
            <methodname>getAllPosts()</methodname>. 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 language="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
            <methodname>getPosts()</methodname>, <methodname>getAllPosts()</methodname>,<methodname>getRecentPosts()</methodname>, et
            <methodname>getUserPosts()</methodname> 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 language="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 <methodname>ArrayAccess::offsetSet()</methodname>
                et <methodname>ArrayAccess::offsetUnset()</methodname> 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 <acronym>URL</acronym>.
        </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 <methodname>withTags()</methodname>. Par confort, <methodname>withTag()</methodname> est aussi
                fourni quand il est nécessaire 'e ne spécifier qu'une seule étiquette
            </para>

            <programlisting language="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 <acronym>URL</acronym> correspondant à une expression
                régulière spécifiée en utilisant la méthode <methodname>withUrl()</methodname> :
            </para>

            <programlisting language="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 language="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 language="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 <acronym>URL</acronym> ou en appelant
            la méthode <methodname>delete()</methodname> 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 language="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
            <methodname>createNewPost()</methodname>, 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
            <methodname>save()</methodname>.
        </para>

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

            <programlisting language="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 language="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 language="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><methodname>getUserFans()</methodname></entry>
                        <entry>Récupère les fans d'un utilisateur</entry>
                        <entry>Array</entry>
                    </row>

                    <row>
                        <entry><methodname>getUserNetwork()</methodname></entry>
                        <entry>Récupère le réseau d'un utilisateur</entry>
                        <entry>Array</entry>
                    </row>

                    <row>
                        <entry><methodname>getUserPosts()</methodname></entry>
                        <entry>Récupère les entrées d'un utilisateur</entry>
                        <entry>Zend_Service_Delicious_PostList</entry>
                    </row>

                    <row>
                        <entry><methodname>getUserTags()</methodname></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 language="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
                <methodname>getUserPosts()</methodname> 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 : <acronym>URL</acronym>, 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><methodname>getNotes()</methodname></entry>
                            <entry>Récupère les notes de l'entrée</entry>
                            <entry>String</entry>
                        </row>

                        <row>
                            <entry><methodname>getTags()</methodname></entry>
                            <entry>Récupère les étiquettes de l'entrée</entry>
                            <entry>Array</entry>
                        </row>

                        <row>
                            <entry><methodname>getTitle()</methodname></entry>
                            <entry>Récupère le titre de l'entrée</entry>
                            <entry>String</entry>
                        </row>

                        <row>
                            <entry><methodname>getUrl()</methodname></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 <acronym>HTTP</acronym> sur le Web
            service de del.icio.us. Pour modifier le client <acronym>HTTP</acronym> utiliser par
            <classname>Zend_Service_Delicious</classname>, vous devez modifier le client <acronym>HTTP</acronym> 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 language="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 <acronym>HTTP</acronym> 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 language="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 <acronym>SSL</acronym> 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>