repo_zf1/documentation/manual/fr/module_specs/Zend_Feed-Importing.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.feed.importing">
    <title>Importer des flux</title>

    <para>
        <classname>Zend_Feed</classname> permet aux développeurs d'obtenir très facilement
        des flux. Si vous connaissez l'URI d'un flux, utilisez simplement la méthode
        <methodname>Zend_Feed::import()</methodname>&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$flux = Zend_Feed::import('http://flux.example.com/nomDuFlux');
]]></programlisting>

    <para>
        Vous pouvez aussi utiliser <classname>Zend_Feed</classname> pour aller chercher le
        contenu d'un flux à partir d'un fichier ou d'une chaîne <acronym>PHP</acronym>&#160;:
    </para>

    <programlisting language="php"><![CDATA[
// on importe un flux à partir d'un fichier texte
$fluxAPartirDeFichierTexte = Zend_Feed::importFile('flux.xml');

// on importe un flux à partir d'une variable PHP de type chaîne
$fluxAPartirDePHP = Zend_Feed::importString($chaineFlux);
]]></programlisting>

    <para>
        Dans chacun des exemples ci-dessus, une instance d'une classe étendant
        <classname>Zend_Feed_Abstract</classname> est renvoyée en cas de succès, selon le type du
        flux. Si un flux <acronym>RSS</acronym> a été obtenu au moyen de l'une des méthodes d'importation décrites
        ci-dessus, alors un objet <classname>Zend_Feed_Rss</classname> sera renvoyé. Par contre, si
        un flux Atom a été importé, alors un objet <classname>Zend_Feed_Atom</classname> est
        renvoyé. Les méthodes d'importation déclencheront aussi une exception
        <classname>Zend_Feed_Exception</classname> en cas d'échec, par exemple si le flux est
        illisible ou malformé.
    </para>

    <sect2 id="zend.feed.importing.custom">
        <title>Flux personnalisés</title>

        <para>
            <classname>Zend_Feed</classname> permet aux développeurs de créer du flux
            personnalisé très facilement. Vous devez juste créer un tableau et l'importer avec
            Zend_Feed. Ce tableau peut être importé avec
            <methodname>Zend_Feed::importArray()</methodname> ou avec
            <methodname>Zend_Feed::importBuilder()</methodname>. Dans ce dernier cas, le tableau sera
            calculé instantanément par une source de données personnalisée implémentant
            <classname>Zend_Feed_Builder_Interface</classname>.
        </para>

        <sect3 id="zend.feed.importing.custom.importarray">
            <title>Importer un tableau personnalisé</title>

            <programlisting language="php"><![CDATA[
// on importe un flux atom à partir d'un tableau
$atomFeedFromArray = Zend_Feed::importArray($array);

// la ligne suivante est équivalente à celle ci-dessus ;
// par défaut l'instance Zend_Feed_Atom est retournée
$atomFeedFromArray = Zend_Feed::importArray($array, 'atom');

// on importe un flux rss à partir d'un tableau
$rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
]]></programlisting>

            <para>Le format du tableau doit être conforme à cette structure&#160;:</para>

            <programlisting language="php"><![CDATA[
array(
    // obligatoire
    'title'       => 'titre du flux',
    'link'        => 'url canonique du flux',

    // optionel
    'lastUpdate'  => 'date de la mise à jour au format timestamp',
    'published'   => 'date de la publication au format timestamp',

    // obligatoire
    'charset'     => 'charset des données textuelles',

    // optionel
    'description' => 'description courte du flux',
    'author'      => 'auteur du flux',
    'email'       => 'email de l'auteur du flux',

     // optionel, ignoré si le flux est de type atom
    'webmaster'   => 'email de la personne responsable'
                   . 'en cas de problème technique'

    // optionel
    'copyright'   => 'informations de copyright',
    'image'       => 'url de l'image',
    'generator'   => 'générateur du flux',
    'language'    => 'langue dans la quelle le flux est écrit',

    // optionel, ignoré si le flux est de type atom
    'ttl'         => 'combien de temps en minutes un flux peut être'
                   . 'mis en cache avant rafraichissement',
    'rating'      => 'l'évaluation PICS du canal',

    // optionel, ignoré si le flux est de type atom
    // un nuage pour être averti des mises à jour
    'cloud'       => array(
        // obligatoire
        'domain'            => 'domaine du nuage, ex. rpc.sys.com',

        // optionel, par défault port 80
        'port'              => 'port de connexion',

        // obligatoire
        'path'              => 'chemin du nuage, ex. /RPC2',
        'registerProcedure' => 'procédure à appeler, '
                             . 'ex. myCloud.rssPleaseNotify',
        'protocol'          => 'protocole à utiliser , ex. soap ou xml-rpc',
    ),

    // optionel, ignoré si le flux est de type atom
    // une boîte de saisie qui peut être montrée avec le flux
    'textInput'   => array(
        // obligatoire
        'title'       => 'l'intitulé du bouton de validation '
                       . 'de la boîte de saisie',
        'description' => 'explication de la boîte de saisie',
        'name'        => 'le nom de l'objet texte',
        'link'        => 'l'URL du CGI qui va analyser la requête',
    )

    // optionel, ignoré si le flux est de type atom
    // Information disant aux aggrégateurs quelles heures ils peuvent ignorer
    'skipHours'   => array(
        // jusqu'à 24 lignes dont les valeurs
        // sont des nombres commpris entre 0 et 23
        // ex. 13 (1pm)
        'heures dans le format 24H',
    )

    // optionel, ignoré si le flux est de type atom
    // Information disant aux aggrégateurs quels jours ils peuvent ignorer
    'skipDays '   => array(
        // jusqu'à 7 lignes dont les valeurs peuvent être
        // Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday
        // ex. Monday
        'jour'
    )

    // optionel, ignoré si le flux est de type atom
    // Données d'extension iTunes
    'itunes'      => array(
        // optionel, par défaut l'auteur principal
        'author'       => 'nom de l'artiste',

        // optionel, default l'auteur principal
        'owner'        => array(
            'name'  => 'nom du propriétaire' ,
            'email' => 'email du propriétaire',
        )

        // optionel, default to the main image value
        'image'        => 'image de l'album/podcast',

        // optionel, default to the main description value
        'subtitle'     => 'description courte',

        // optionel, default to the main description value
        'summary'      => 'description longue',

        // optionel
        'block'        => 'empêcher l'apparition d'un épisode (yes|no)',

        // obligatoire, catégorie et information de recherche
        // dans iTunes Music Store
        'category'     => array(
            // jusqu'à 3 lignes
            array(
                // obligatoire
                'main' => 'catégorie principale',
                // optionel
                'sub'  => 'sous-catégorie'
            ),
        )

        // optionel
        'explicit'     => 'graphique d'avertissement parental (yes|no|clean)',
        'keywords'     => 'une liste d'au maximum 12 mot clés'
                        . 'séparés par des virgules',
        'new-feed-url' => 'utiliser pour informer iTunes'
                        . 'd'un nouvel URL de flux',
    )

    'entries'     => array(
        array(
            // obligatoire
            'title'        => 'titre de l'item',
            'link'         => 'url de cet item',

            // obligatoire, seulement du text, pas d'html
            'description'  => 'version raccourci du texte',

            // optionel
            'guid'         => 'id de l'article, si aucun alors'
                            . 'la valeur link est utilisée',

             // optionel, peut contenir html
            'content'      => 'version complète de l'information',

            // optionel
            'lastUpdate'   => 'date de publication au format timestamp',
            'comments'     => 'page de commentaires de l'item',
            'commentRss'   => 'l'url du flux des commentaires associés',

            // optionel, source originale de l'item
            'source'       => array(
                // obligatoire
                'title' => 'titre de la source originale',
                'url' => 'url de la source originale'
            )

            // optionel, liste des catégories attachées
            'category'     => array(
                array(
                    // obligatoire
                    'term' => 'intitulé de la première catégorie',

                    // optionel
                    'scheme' => 'url qui décrit l'organisation de la catégorie'
                ),
                array(
                    //données de la seconde catégorie et ainsi de suite
                )
            ),

            // optionel, liste des pièces jointes à l'item
            'enclosure'    => array(
                array(
                    // obligatoire
                    'url' => 'url de la pièce jointe',

                    // optionel
                    'type' => 'type mime de la pièce jointe',
                    'length' => 'length de la pièce jointe en octets'
                ),
                array(
                    //données de la seconde pièce jointe et ainsi de suite
                )
            )
        ),

        array(
            //données du second item et ainsi de suite
        )
    )
);
]]></programlisting>

            <para>
                Références :
                <itemizedlist>
                    <listitem>
                        <para>Spécification <acronym>RSS</acronym> 2.0&#160;:
                        <ulink url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
                    </para>

                </listitem>

                <listitem>
                    <para>
                        Spécification Atom&#160;:
                        <ulink url="http://tools.ietf.org/html/rfc4287">RFC 4287</ulink>
                    </para>

                </listitem>

                <listitem>
                    <para>
                        Spécification WFW&#160;:
                        <ulink url="http://wellformedweb.org/news/wfw_namespace_elements">Well
                        Formed Web</ulink>
                    </para>

                </listitem>

                <listitem>
                    <para>
                        Spécification iTunes&#160;:
                        <ulink url="http://www.apple.com/itunes/store/podcaststechspecs.html">
                        iTunes Technical Specifications</ulink>
                    </para>

                </listitem>

            </itemizedlist></para>

        </sect3>

        <sect3 id="zend.feed.importing.custom.importbuilder">
            <title>Importer une source de données personnalisée</title>

            <para>
                Vous pouvez créer une instance Zeed_Feed à partir de n'importe quelle source
                de données implémentant <classname>Zend_Feed_Builder_Interface</classname>. Vous
                devez juste implémenter les méthodes <methodname>getHeader()</methodname> et
                <methodname>getEntries()</methodname> pour pouvoir utiliser votre objet avec
                <methodname>Zend_Feed::importBuilder()</methodname>. Par une simple référence
                d'implémentation vous pouvez utiliser <classname>Zend_Feed_Builder</classname>, qui
                prend un tableau dans son constructeur, réalise quelques validations mineures, et
                peut être utilisé dans la méthode <methodname>importBuilder()</methodname>. La méthode
                <methodname>getHeader()</methodname> doit retourner une instance de
                <classname>Zend_Feed_Builder_Header</classname>, et <methodname>getEntries()</methodname> doit
                retourner un tableau d'instances
                <classname>Zend_Feed_Builder_Entry</classname>
            </para>

            <note>
                <para>
                    <classname>Zend_Feed_Builder</classname> fournit une mise en oeuvre
                    concrète afin de montrer l'utilisation. Les utilisateurs sont encouragés à
                    faire leurs classes propres mettre en oeuvre
                    <classname>Zend_Feed_Builder_Interface</classname>.
                </para>
            </note>

            <para>
                Voici un exemple d'utilisation de
                <methodname>Zend_Feed::importBuilder()</methodname>&#160;:
            </para>

            <programlisting language="php"><![CDATA[
// importe un flux atom à partir d'un constructeur personnalisé
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array));

// la ligne suivante est équivalente à celle ci-dessus ;
// par défaut l'instance Zend_Feed_Atom est retournée
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'atom');

// importe un flux rss à partir d'un constructeur personnalisé
$rssFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'rss');
]]></programlisting>

        </sect3>

        <sect3 id="zend.feed.importing.custom.dump">
            <title>Décharger le contenu d'un flux</title>

            <para>
                Pour décharger le contenu d'une instance
                <classname>Zend_Feed_Abstract</classname>, vous pouvez utiliser les méthodes
                <methodname>send()</methodname> ou <code>saveXml().</code>
            </para>

            <programlisting language="php"><![CDATA[
assert($feed instanceof Zend_Feed_Abstract);

// décharge le flux dans l'affichage standard
print $feed->saveXML();

// envoie les en-têtes et décharge le flux
$feed->send();
]]></programlisting>
        </sect3>
    </sect2>
</sect1>