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

<sect1 id="zend.feed.importing">
    <title>Импортирование лент с помощью Zend_Feed</title>
    <para>
        <code>Zend_Feed</code> позволяет легко получать ленты.
        Если вам известен URI ленты, то просто используйте метод
        <code>Zend_Feed::import()</code>:
    </para>

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

    <para>
        Еще вы можете использовать <code>Zend_Feed</code> для извлечения содержимого
        ленты из файла или строки:
    </para>

    <programlisting language="php"><![CDATA[
// импортирование ленты из текстового файла
$feedFromFile = Zend_Feed::importFile('feed.xml');

// импортирование ленты из строки
$feedFromPHP = Zend_Feed::importString($feedString);
]]>
    </programlisting>

    <para>
        В примерах выше в случае успеха возвращается
        объект одного из классов, расширяющих <code>Zend_Feed_Abstract</code>, в
        зависимости от типа ленты. Если посредством одного из вышеприведенных
        методов для импортирования была извлечена лента RSS, то будет возвращен объект
        <code>Zend_Feed_Rss</code>. Если же импортируется лента Atom, то
        будет возвращен объект <code>Zend_Feed_Atom</code>. Эти методы для импортирования
        будут бросать исключение <code>Zend_Feed_Exception</code> в случае ошибки,
        такой, как недоступная для чтения или плохо сформированная лента.
    </para>

    <sect2 id="zend.feed.importing.custom">

        <title>Создание собственных лент</title>

        <para>
            <code>Zend_Feed</code> позволяет разработчикам легко создавать
            собственные ленты. Вам нужно просто создать массив и импортировать
            его в Zend_Feed. Импорт из массива может быть выполнен с помощью
            методов <code>Zend_Feed::importArray()</code> или
            <code>Zend_Feed::importBuilder()</code>. В последнем методе
            массив будет сформирован на лету с помощью специального
            источника данных, реализующего интерфейс
            <code>Zend_Feed_Builder_Interface</code>.
        </para>

        <sect3 id="zend.feed.importing.custom.importarray">

            <title>Импортирование массива</title>

            <programlisting language="php"><![CDATA[
// Импортирование ленты из массива
$atomFeedFromArray = Zend_Feed::importArray($array);

// Следующая строка эквивалентна предыдущей
// По умолчанию возвращается экземпляр Zend_Feed_Atom
$atomFeedFromArray = Zend_Feed::importArray($array, 'atom');

// Импортирование ленты RSS из массива
$rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
]]>
            </programlisting>

            <para>
                Формат массива должен соответствовать следующей структуре:
            </para>

            <programlisting language="php"><![CDATA[
array(
      'title'       => 'заголовок ленты', // обязательный
      'link'        => 'канонический URL ленты', // обязательный
      'lastUpdate'  => 'время обновления', // опциональный
      'published'   => 'время публикации', // опциональный
      'charset'     => 'кодировка для текстовых данных', // обязательный
      'description' => 'краткое описание ленты', // опциональный
      'author'      => 'автор/издатель ленты', // опциональный
      'email'       => 'e-mail автора', // опциональный
      'webmaster'   =>     // опциональный, игнорируется, если используется Atom
                       'e-mail лица, отвечающего за технические вопросы'
      'copyright'   => 'авторские права', // опциональный
      'image'       => 'URL к изображению', // опциональный
      'generator'   => 'генератор', // опциональный
      'language'    => 'язык, на котором выпускается лента', // опциональный
      'ttl'         =>     // опциональный, игнорируется, если используется Atom
                       'сколько минут лента может храниться в кэше ' .
                       'до обновления',
      'rating'      =>     // опциональный, игнорируется, если используется Atom
                       'рейтинг PICS',
      'cloud'       => array(
                             'domain'            => 'домен, пример: rpc.sys.com', // обязательный
                             'port'              => 'порт', // опциональный, по умолчанию 80
                             'path'              => 'путь, пример: /RPC2', // обязательный
                             'registerProcedure' => 'процедура для вызова, пример: myCloud.rssPleaseNotify', // обязательный
                             'protocol'          => 'используемый протокол, например, soap или xml-rpc' // обязательный
                             ), // веб-сервис, поддерживающий интерфейс
                                // rssCloud, отвечающий за уведомления об изменениях в канале
                                // опциональный, игнорируется, если используется Atom
      'textInput'   => array(
                             'title'       => 'надпись для кнопки отправки', // обязательный
                             'description' => 'пояснение к текстовому полю', // обязательный
                             'name'        => 'атрибут name для текстового поля', // обязательный
                             'link'        => 'URL скрипта, которому будет отправлены данные' // обязательный
                             ), // текстовое поле для ввода, которое может отображаться в ленте
                                // опциональный, игнорируется, если используется Atom
      'skipHours'   => array(
                             'часы в формате 24'
                             // может содержать до 24 элементов, значения которых должны
                             // находиться в диапазоне 0..23
                             ), // Указывает аггрегатору, в какие часы он может не обновлять канал
                                // опциональный, игнорируется, если используется Atom
      'skipDays '   => array(
                             'пропускаемые дни недели'
                             // может содержать до 7 элементов, значениями которых должны быть
                             // Monday, Tuesday, Wednesday, Thursday, Friday, Saturday или Sunday
                             ), // Указывает аггрегатору, в какие дни недели он может не обновлять канал
                                // опциональный, игнорируется, если используется Atom
      'itunes'      => array(
                             'author'       => 'автор', // опциональный, по умолчанию используется элемент из channel
                             'owner'        => array(
                                                     'name' => 'имя владельца', // опциональный, по умолчанию используется элемент из channel
                                                     'email' => 'e-mail владельца' // опциональный, по умолчанию используется элемент из channel
                                                     ) // владелец подкаста // опциональный
                             'image'        => 'изображение для альбома/подкаста', // опциональный, по умолчанию используется элемент из channel
                             'subtitle'     => 'краткое описание', // опциональный, по умолчанию используется элемент из channel
                             'summary'      => 'полное описание', // опциональный, по умолчанию используется элемент из channel
                             'block'        => 'блокирует показ (yes|no)', // опциональный
                             'category'     => array(
                                                     array('main' => 'основная категория', // обязательный
                                                           'sub'  => 'подкатегория' // опциональный
                                                           ),
                                                     // до 3-х элементов с парами категория/подкатегория
                                                     ) // 'категории для навигации' // обязательный
                             'explicit'     => 'индикатор наличия материалов откровенного содержания (yes|no|clean)', // опциональный
                             'keywords'     => 'список из ключевых слов, разделенных запятой (до 12 слов)', // опциональный
                             'new-feed-url' => 'используется для того, чтобы сообщить iTunes о новом URL ленты' // опциональный
                             ) // данные для iTunes // опциональный, игнорируется, если используется Atom
      'entries'     => array(
                             array(
                                   'title'        => 'заголовок сообщения', // обязательный
                                   'link'         => 'URL сообщения', // обязательный
                                   'description'  => 'краткое описание', // только текст без HTML, обязательный
                                   'guid'         => 'идентификатор сообщения, если не передан, то используется URL сообщения', // опциональный
                                   'content'      => 'содержание сообщения', // может содержать HTML, опциональный
                                   'lastUpdate'   => 'дата публикации', // опциональный
                                   'comments'     => 'страница для комментариев к сообщению', // опциональный
                                   'commentRss'   => 'URL ленты для комментариев, относящихся к сообщению', // опциональный
                                   'source'       => array(
                                                           'title' => 'заголовок оригинального источника', // обязательный
                                                           'url' => 'URL оригинального источника', // обязательный
                                                           ), // оригинальный источник сообщения // опциональный
                                   'category'     => array(
                                                           array(
                                                                 'term' => 'имя категории', // обязательный
                                                                 'scheme' => 'URL ресурса с классификацией' // опциональный
                                                                 ),
                                                           array(
                                                                 // данные второй категории и т.д.
                                                                 )
                                                           ), // список прикрепленных категорий // опциональный
                                   'enclosure'    => array(
                                                           array(
                                                                 'url' => 'URL вложения', // обязательный
                                                                 'type' => 'тип MIME вложения', // опциональный
                                                                 'length' => 'размер вложения в октетах' // опциональный
                                                                 ),
                                                           array(
                                                                 // данные для второго вложения и т.д.
                                                                 )
                                                           ) // список вложений для сообщения // опциональный
                                   ),
                             array(
                                   // данные второго сообщения и т.д.
                                   )
                             )
       );
]]>
            </programlisting>

            <para>
                Информационные ресурсы:
                <itemizedlist>
                    <listitem>
                        <para>
                            Спецификация RSS 2.0: <ulink url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Спецификация Atom: <ulink url="http://tools.ietf.org/html/rfc4287">RFC 4287</ulink>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Спецификация WFW: <ulink url="http://wellformedweb.org/news/wfw_namespace_elements">Well
                            Formed Web</ulink>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Спецификация iTunes:
                            <ulink url="http://www.apple.com/itunes/store/podcaststechspecs.html">Технические спецификации iTunes</ulink>
                        </para>
                    </listitem>
                </itemizedlist>
            </para>

        </sect3>

        <sect3 id="zend.feed.importing.custom.importbuilder">

            <title>Импортирование из специального источника данных</title>

            <para>
                Вы можете создать экземпляр Zeed_Feed из любого источника
                данных, реализующего интерфейс
                <code>Zend_Feed_Builder_Interface</code>. Вам нужно только
                реализовать методы <code>getHeader()</code> и
                <code>getEntries()</code> для того, чтобы можно было
                использовать свой объект с
                <code>Zend_Feed::importBuilder()</code>. Простой пример -
                вы можете использовать компоновщик
                <code>Zend_Feed_Builder</code>, который принимает массив в
                своем конструкторе, выполняет
                некоторую проверку и затем может использоваться в методе
                <code>importBuilder()</code>. <code>getEntries()</code>
                должен возвращать массив экземпляров
                <code>Zend_Feed_Builder_Entry</code>.
            </para>

            <note>
                <para>
                    <code>Zend_Feed_Builder</code> служит только в качестве
                    конкретной реализации для демонстрации использования.
                    Пользователи должны создавать свои классы, реализующие
                    интерфейс <code>Zend_Feed_Builder_Interface</code>.
                </para>
            </note>

            <para>
                Ниже приведен пример использования
                <code>Zend_Feed::importBuilder()</code>:
            </para>

            <programlisting language="php"><![CDATA[
// Импортирование ленты из специального созданного ресурса-компоновщика
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array));

// Следующая строка эквивалентна предыдущей.
// По умолчанию возвращается экземпляр Zend_Feed_Atom
$atomFeedFromArray =
    Zend_Feed::importArray(new Zend_Feed_Builder($array), 'atom');

// Импортирование RSS-ленты из специально созданного ресурса-компоновщика
$rssFeedFromArray =
    Zend_Feed::importArray(new Zend_Feed_Builder($array), 'rss');
]]>
            </programlisting>

        </sect3>

        <sect3 id="zend.feed.importing.custom.dump">

            <title>Дапм содержимого ленты</title>

            <para>
                Для того, чтобы произвести дамп экземпляра
                <code>Zend_Feed_Abstract</code>, вы можете использовать методы
                <code>send()</code> или <code>saveXml()</code>.
            </para>

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

// вывод дампа ленты
print $feed->saveXML();

// отправка HTTP-заголовков и вывод дампа ленты
$feed->send();
]]>
            </programlisting>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->