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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.feed.importing">
    <title>Feeds importieren</title>

    <para>
        <classname>Zend_Feed</classname> ermöglicht es Entwicklern, Feeds sehr einfach abzurufen.
        Wenn Du die <acronym>URI</acronym> eines Feeds kennst, verwende einfach die
        <methodname>Zend_Feed::import()</methodname> Methode:
    </para>

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

    <para>
        Du kannst <classname>Zend_Feed</classname> außerdem verwenden, um Inhalte eines Feeds aus
        einer Datei oder die Inhalte aus einem <acronym>PHP</acronym> String Variable zu abzurufen.
    </para>

    <programlisting language="php"><![CDATA[
// Feeds von einer Textdatei importieren
$feedFromFile = Zend_Feed::importFile('feed.xml');

// Feeds von einer PHP String Variable importieren
$feedFromPHP = Zend_Feed::importString($feedString);
]]></programlisting>

    <para>
        In jedem der obigen Beispiele wird bei Erfolg abhängig vom Typ des Feeds ein Objekt einer
        Klasse zurück gegeben, welche <classname>Zend_Feed_Abstract</classname> erweitert. Wird ein
        <acronym>RSS</acronym> Feed durch eine der obigen Importiermethoden abgerufen, wird eine
        <classname>Zend_Feed_Rss</classname> Objekt zurückgegeben. Auf der anderen Seite wird beim
        Importieren eines Atom Feeds ein <classname>Zend_Feed_Atom</classname> Objekt zurückgegeben.
        Bei Fehlern, wie z.B. ein unlesbarer oder nicht wohlgeformter Feed, werfen die
        Importiermethoden auch ein <classname>Zend_Feed_Exception</classname> Objekt.
    </para>

    <sect2 id="zend.feed.importing.custom">
        <title>Eigene Feeds</title>

        <para>
            <classname>Zend_Feed</classname> ermöglicht es Entwicklern Ihre eigenen Feeds sehr
            einfach zu erstellen. Man muß nur ein Array erstellen und es in
            <classname>Zend_Feed</classname> importieren, Dieses Array kann mit
            <methodname>Zend_Feed::importArray()</methodname> oder mit
            <methodname>Zend_Feed::importBuilder()</methodname> importiert werden. Im letzteren Fall
            wird das Array on the Fly durch eine eigene Datenquelle berechnet die
            <classname>Zend_Feed_Builder_Interface</classname> implementiert.
        </para>

        <sect3 id="zend.feed.importing.custom.importarray">
            <title>Importieren eines eigenen Arrays</title>

            <programlisting language="php"><![CDATA[
// Importieren eines Feeds von einem Array
$atomFeedFromArray = Zend_Feed::importArray($array);

// Die folgende Zeile ist identisch mit der obigen; standardmäßig
// wird eine Zend_Feed_Atom Instanz zurückgegeben
$atomFeedFromArray = Zend_Feed::importArray($array, 'atom');

// Importieren eines RSS Feeds von einem Array
$rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
]]></programlisting>

            <para>
                Das Format des Arrays muß dieser Struktur entsprechen:
            </para>

            <programlisting language="php"><![CDATA[
array(
    // benötigt
    'title' => 'Titel des Feeds',
    'link'  => 'Kanonische URL zu dem Feed',

    // optional
    'lastUpdate' => 'Zeitstempel des Update Datums',
    'published'  => 'Zeitstempel des Veröffentlichungs Datums',

    // benötigt
    'charset' => 'Zeichensatz der textuellen Daten',

    //optional
    'description' => 'Kurzbeschreibung des Feeds',
    'author'      => 'Author, Veröffentlicher des Feeds',
    'email'       => 'Email des Authors',

    // optional, ignoriert wenn Atom verwendet wird
    'webmaster' => 'Email Adresse der Person die für technische '
                .  'Belange verantwortlich ist',

    //optional
    'copyright' => 'Copyright Notiz',
    'image'     => 'URL zu Bildern',
    'generator' => 'Ersteller',
    'language'  => 'Sprache in welcher der Feed geschrieben ist',

    // optional, ignoriert wenn Atom verwendet wird
    'ttl'    => 'Wie lange ein Feed gecached werden kann '
             .  'bevor er erneut werden muß',
    'rating' => 'Die PICS Rate dieses Kanals',

    // optional, ignoriert wenn Atom verwendet wird
    // eine Wolke die über Updates benachrichtigt wird
    'cloud' => array(
        // benötigt
        'domain' => 'Domain der Wolke, e.g. rpc.sys.com',

        // optional, Standard ist 80
        'port' => 'Port zu dem verbunden wird',

        // benötigt
        'path'              => 'Pfad der Wolke, e.g. /RPC2',
        'registerProcedure' => 'Prozedur die aufgerufen wird, '
                            .  'z.B. myCloud.rssPleaseNotify'
        'protocol'          => 'Protokoll das verwendet wird, z.B. '
                            .  'soap oder xml-rpc'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Eine Texteingabebox die im Feed angezeigt werden kann
    'textInput' => array(
        // benötigt
        'title'       => 'Die Überschrift des Senden Buttons im '
                      .  'Texteingabefeld',
        'description' => 'Beschreibt das Texteingabefeld',
        'name'        => 'Der Name des Text Objekts im '
                      .  'Texteingabefeld',
        'link'        => 'Die URL des CGI Skripts das Texteingabe '
                      .  'Anfragen bearbeitet'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Hinweise geben welche Stunden übersprungen werden können
    'skipHours'   => array(
        // bis zu 24 Zeilen dessen Werte eine Nummer zwischen 0 und 23 ist
        // z.B. 13 (1pm)
        'hour in 24 format'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Hinweise geben welche Tage übersprungen werden können
    'skipDays '   => array(
        // bis zu 7 Zeilen dessen Werte Montag, Dienstag, Mittwoch,
        // Donnerstag, Freitag, Samstag oder Sonntag sind
        // z.B. Montag
        'a day to skip'
    ),

    // optional, ignoriert wenn Atom verwendet wird
    // Itunes Erweiterungsdaten
    'itunes' => array(
        // optional, Standard ist der Wert der author Spalte
        'author' => 'Musiker Spalte',

        // optional, Standard ist der Wert der author Spalte
        // Eigentümer des Podcasts
        'owner' => array(
            'name'  => 'Name des Eigentümers',
            'email' => 'Email des Eigentümers'
        ),

        // optional, Standard ist der image Wert
        'image' => 'Album/Podcast Bild',

        // optional, Standard ist der description Wert
        'subtitle' => 'Kurzbeschreibung',
        'summary'  => 'Langbeschreibung',

        // optional
        'block' => 'Verhindern das eine Episode erscheint (ja|nein)',

        // benötigt
        // 'Kategoriespalte und iTunes Music Store Browse'
        'category' => array(
            // bis zu 3 Zeilen
            array(
                // benötigt
                'main' => 'Hauptkategorie',

                // optional
                'sub'  => 'Unterkategorie'
            ),
        ),

        // optional
        'explicit'     => 'Elterliche Anweisungsspalte (ja|nein|löschen)',
        'keywords'     => 'Eine kommagetrennte Liste von maximal '
                       .  '12 Schlüsselwörtern',
        'new-feed-url' => 'Verwendet um iTunes über eine neue URL '
                       .  'Lokation zu informieren'
    ),

    'entries' => array(
        array(
            // benötigt
            'title' => 'Titel des Feedeintrags',
            'link'  => 'URL zum Feedeintrag',

            // benötigt, nur Text, kein HTML
            'description'  => 'Kurzversion des Feedeintrags',

            //optional
            'guid' => 'Id des Artikels, wenn nicht angegeben '
                   .  'wird der link Wert verwendet',

            // optional, kann HTML enthalten
            'content' => 'Langversion',

            // optional
            'lastUpdate' => 'Zeitstempel des Veröffnetlichungsdatums',
            'comments'   => 'Kommentarseite des Feedeintrags',
            'commentRss' => 'Die FeedURL der zugehörenden Kommentare',

            // optional, Originale Quelle des Feedeintrags
            'source' => array(
                // benötigt
                'title' => 'Titel der Originalen Quelle',
                'url'   => 'URL der originalen Quelle'
            ),

            // optional, Liste der zugeordneten Kategorien
            'category' => array(
                array(
                    // benötigt
                    'term' => 'Überschrift der ersten Kategorie',

                    // optional
                    'scheme' => 'URL die das Kategorisierungsschema '
                             .  'identifiziert'
                ),

                array(
                    //Daten der zweiten Kategorie und so weiter
                )
            ),

            // optional, Liste der Anhänge des Feedeintrags
            'enclosure' => array(
                array(
                    // benötigt
                    'url' => 'URL des verlinkten Anhangs',

                    // optional
                    'type'   => 'Mime Typ des Anhangs',
                    'length' => 'Länge des verlinkten Inhalts oktal'
                ),

                array(
                    // Daten für den zweiten Anhang und so weiter
                )
            )
        ),

        array(
            // Daten für den zweiten Eintrag und so weiter
        )
    )
);
]]></programlisting>

            <para>
                Referenzen:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <acronym>RSS</acronym> 2.0 Spezifikation: <ulink
                            url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Atom Spezifikation: <ulink url="http://tools.ietf.org/html/rfc4287">RFC
                            4287</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <acronym>WFW</acronym> Spezifikation: <ulink
                            url="http://wellformedweb.org/news/wfw_namespace_elements">Gut
                            geformtes Web</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        iTunes Spezifikation:
                        <ulink
                            url="http://www.apple.com/itunes/store/podcaststechspecs.html">iTunes
                            Technische Spezifikation</ulink>
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.feed.importing.custom.importbuilder">
            <title>Importieren einer eigenen Daten Quelle</title>

            <para>
                Eine <classname>Zend_Feed</classname> Instanz kann von jeder Datenquelle erstellt
                werden die <classname>Zend_Feed_Builder_Interface</classname> implementiert. Die
                <methodname>getHeader()</methodname> und <methodname>getEntries()</methodname>
                Methoden müssen implementiert werden damit das Objekt mit
                <methodname>Zend_Feed::importBuilder()</methodname> verwendet werden kann. Als
                einfache Referenz Implementation kann <classname>Zend_Feed_Builder</classname>
                verwendet werden, welches ein Array im Contructor entgegen nimmt, einige einfache
                Prüfungen durchführt, und anschließend in der
                <methodname>importBuilder()</methodname> Methode verwendet werden kann. Die
                <methodname>getHeader()</methodname> Methode muß eine Instanz von
                <classname>Zend_Feed_Builder_Header</classname> zurückgeben, und
                <methodname>getEntries()</methodname> muß ein Array von
                <classname>Zend_Feed_Builder_Entry</classname> Instanzen zurückgeben.
            </para>

            <note>
                <para>
                    <classname>Zend_Feed_Builder</classname> arbeitet als konkrete Implementation um
                    die Verwendung zu demonstrieren. Benutzer sind angehlaten Ihre eigenen Klassen
                    zu Erstellen um <classname>Zend_Feed_Builder_Interface</classname> zu
                    implementieren.
                </para>
            </note>

            <para>
                Hier ist ein Beispiel der Verwendung von
                <methodname>Zend_Feed::importBuilder()</methodname>:
            </para>

            <programlisting language="php"><![CDATA[
// Einen Feed von einer eigenen Erstellungsquelle importieren
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array));

// Die folgende Zeile ist mit der obigen äquivalent; standardmäßig
// wird eine Zend_Feed_Atom Instanz zurückgegeben
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'atom');

// Einen RSS Feeed von einem Array von eigenen Erstellungsquellen importieren
$rssFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'rss');
]]></programlisting>
        </sect3>

        <sect3 id="zend.feed.importing.custom.dump">
            <title>Ausgeben des Inhalts eines Feeds</title>

            <para>
                Um den Inhalt einer <classname>Zend_Feed_Abstract</classname> Instanz auszugeben
                können die <methodname>send()</methodname> oder <methodname>saveXml()</methodname>
                Methoden verwendet werden.
            </para>

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

// Den Feed an der Standardausgabe ausgeben
print $feed->saveXML();

// HTTP Header und den Feed ausgeben
$feed->send();
]]></programlisting>
        </sect3>
    </sect2>
</sect1>