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

   1 <sect1 id="zend.feed.importing">
   2     <title>Импортирование лент с помощью Zend_Feed</title>
   3     <para>
   4         <code>Zend_Feed</code> позволяет легко получать ленты.
   5         Если вам известен URI ленты, то просто используйте метод
   6         <code>Zend_Feed::import()</code>:
   7     </para>
   8
   9     <programlisting language="php"><![CDATA[
  10 $feed = Zend_Feed::import('http://feeds.example.com/feedName');
  11 ]]>
  12     </programlisting>
  13
  14     <para>
  15         Еще вы можете использовать <code>Zend_Feed</code> для извлечения содержимого
  16         ленты из файла или строки:
  17     </para>
  18
  19     <programlisting language="php"><![CDATA[
  20 // импортирование ленты из текстового файла
  21 $feedFromFile = Zend_Feed::importFile('feed.xml');
  22
  23 // импортирование ленты из строки
  24 $feedFromPHP = Zend_Feed::importString($feedString);
  25 ]]>
  26     </programlisting>
  27
  28     <para>
  29         В примерах выше в случае успеха возвращается
  30         объект одного из классов, расширяющих <code>Zend_Feed_Abstract</code>, в
  31         зависимости от типа ленты. Если посредством одного из вышеприведенных
  32         методов для импортирования была извлечена лента RSS, то будет возвращен объект
  33         <code>Zend_Feed_Rss</code>. Если же импортируется лента Atom, то
  34         будет возвращен объект <code>Zend_Feed_Atom</code>. Эти методы для импортирования
  35         будут бросать исключение <code>Zend_Feed_Exception</code> в случае ошибки,
  36         такой, как недоступная для чтения или плохо сформированная лента.
  37     </para>
  38
  39     <sect2 id="zend.feed.importing.custom">
  40
  41         <title>Создание собственных лент</title>
  42
  43         <para>
  44             <code>Zend_Feed</code> позволяет разработчикам легко создавать
  45             собственные ленты. Вам нужно просто создать массив и импортировать
  46             его в Zend_Feed. Импорт из массива может быть выполнен с помощью
  47             методов <code>Zend_Feed::importArray()</code> или
  48             <code>Zend_Feed::importBuilder()</code>. В последнем методе
  49             массив будет сформирован на лету с помощью специального
  50             источника данных, реализующего интерфейс
  51             <code>Zend_Feed_Builder_Interface</code>.
  52         </para>
  53
  54         <sect3 id="zend.feed.importing.custom.importarray">
  55
  56             <title>Импортирование массива</title>
  57
  58             <programlisting language="php"><![CDATA[
  59 // Импортирование ленты из массива
  60 $atomFeedFromArray = Zend_Feed::importArray($array);
  61
  62 // Следующая строка эквивалентна предыдущей
  63 // По умолчанию возвращается экземпляр Zend_Feed_Atom
  64 $atomFeedFromArray = Zend_Feed::importArray($array, 'atom');
  65
  66 // Импортирование ленты RSS из массива
  67 $rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
  68 ]]>
  69             </programlisting>
  70
  71             <para>
  72                 Формат массива должен соответствовать следующей структуре:
  73             </para>
  74
  75             <programlisting language="php"><![CDATA[
  76 array(
  77       'title'       => 'заголовок ленты', // обязательный
  78       'link'        => 'канонический URL ленты', // обязательный
  79       'lastUpdate'  => 'время обновления', // опциональный
  80       'published'   => 'время публикации', // опциональный
  81       'charset'     => 'кодировка для текстовых данных', // обязательный
  82       'description' => 'краткое описание ленты', // опциональный
  83       'author'      => 'автор/издатель ленты', // опциональный
  84       'email'       => 'e-mail автора', // опциональный
  85       'webmaster'   =>     // опциональный, игнорируется, если используется Atom
  86                        'e-mail лица, отвечающего за технические вопросы'
  87       'copyright'   => 'авторские права', // опциональный
  88       'image'       => 'URL к изображению', // опциональный
  89       'generator'   => 'генератор', // опциональный
  90       'language'    => 'язык, на котором выпускается лента', // опциональный
  91       'ttl'         =>     // опциональный, игнорируется, если используется Atom
  92                        'сколько минут лента может храниться в кэше ' .
  93                        'до обновления',
  94       'rating'      =>     // опциональный, игнорируется, если используется Atom
  95                        'рейтинг PICS',
  96       'cloud'       => array(
  97                              'domain'            => 'домен, пример: rpc.sys.com', // обязательный
  98                              'port'              => 'порт', // опциональный, по умолчанию 80
  99                              'path'              => 'путь, пример: /RPC2', // обязательный
 100                              'registerProcedure' => 'процедура для вызова, пример: myCloud.rssPleaseNotify', // обязательный
 101                              'protocol'          => 'используемый протокол, например, soap или xml-rpc' // обязательный
 102                              ), // веб-сервис, поддерживающий интерфейс
 103                                 // rssCloud, отвечающий за уведомления об изменениях в канале
 104                                 // опциональный, игнорируется, если используется Atom
 105       'textInput'   => array(
 106                              'title'       => 'надпись для кнопки отправки', // обязательный
 107                              'description' => 'пояснение к текстовому полю', // обязательный
 108                              'name'        => 'атрибут name для текстового поля', // обязательный
 109                              'link'        => 'URL скрипта, которому будет отправлены данные' // обязательный
 110                              ), // текстовое поле для ввода, которое может отображаться в ленте
 111                                 // опциональный, игнорируется, если используется Atom
 112       'skipHours'   => array(
 113                              'часы в формате 24'
 114                              // может содержать до 24 элементов, значения которых должны
 115                              // находиться в диапазоне 0..23
 116                              ), // Указывает аггрегатору, в какие часы он может не обновлять канал
 117                                 // опциональный, игнорируется, если используется Atom
 118       'skipDays '   => array(
 119                              'пропускаемые дни недели'
 120                              // может содержать до 7 элементов, значениями которых должны быть
 121                              // Monday, Tuesday, Wednesday, Thursday, Friday, Saturday или Sunday
 122                              ), // Указывает аггрегатору, в какие дни недели он может не обновлять канал
 123                                 // опциональный, игнорируется, если используется Atom
 124       'itunes'      => array(
 125                              'author'       => 'автор', // опциональный, по умолчанию используется элемент из channel
 126                              'owner'        => array(
 127                                                      'name' => 'имя владельца', // опциональный, по умолчанию используется элемент из channel
 128                                                      'email' => 'e-mail владельца' // опциональный, по умолчанию используется элемент из channel
 129                                                      ) // владелец подкаста // опциональный
 130                              'image'        => 'изображение для альбома/подкаста', // опциональный, по умолчанию используется элемент из channel
 131                              'subtitle'     => 'краткое описание', // опциональный, по умолчанию используется элемент из channel
 132                              'summary'      => 'полное описание', // опциональный, по умолчанию используется элемент из channel
 133                              'block'        => 'блокирует показ (yes|no)', // опциональный
 134                              'category'     => array(
 135                                                      array('main' => 'основная категория', // обязательный
 136                                                            'sub'  => 'подкатегория' // опциональный
 137                                                            ),
 138                                                      // до 3-х элементов с парами категория/подкатегория
 139                                                      ) // 'категории для навигации' // обязательный
 140                              'explicit'     => 'индикатор наличия материалов откровенного содержания (yes|no|clean)', // опциональный
 141                              'keywords'     => 'список из ключевых слов, разделенных запятой (до 12 слов)', // опциональный
 142                              'new-feed-url' => 'используется для того, чтобы сообщить iTunes о новом URL ленты' // опциональный
 143                              ) // данные для iTunes // опциональный, игнорируется, если используется Atom
 144       'entries'     => array(
 145                              array(
 146                                    'title'        => 'заголовок сообщения', // обязательный
 147                                    'link'         => 'URL сообщения', // обязательный
 148                                    'description'  => 'краткое описание', // только текст без HTML, обязательный
 149                                    'guid'         => 'идентификатор сообщения, если не передан, то используется URL сообщения', // опциональный
 150                                    'content'      => 'содержание сообщения', // может содержать HTML, опциональный
 151                                    'lastUpdate'   => 'дата публикации', // опциональный
 152                                    'comments'     => 'страница для комментариев к сообщению', // опциональный
 153                                    'commentRss'   => 'URL ленты для комментариев, относящихся к сообщению', // опциональный
 154                                    'source'       => array(
 155                                                            'title' => 'заголовок оригинального источника', // обязательный
 156                                                            'url' => 'URL оригинального источника', // обязательный
 157                                                            ), // оригинальный источник сообщения // опциональный
 158                                    'category'     => array(
 159                                                            array(
 160                                                                  'term' => 'имя категории', // обязательный
 161                                                                  'scheme' => 'URL ресурса с классификацией' // опциональный
 162                                                                  ),
 163                                                            array(
 164                                                                  // данные второй категории и т.д.
 165                                                                  )
 166                                                            ), // список прикрепленных категорий // опциональный
 167                                    'enclosure'    => array(
 168                                                            array(
 169                                                                  'url' => 'URL вложения', // обязательный
 170                                                                  'type' => 'тип MIME вложения', // опциональный
 171                                                                  'length' => 'размер вложения в октетах' // опциональный
 172                                                                  ),
 173                                                            array(
 174                                                                  // данные для второго вложения и т.д.
 175                                                                  )
 176                                                            ) // список вложений для сообщения // опциональный
 177                                    ),
 178                              array(
 179                                    // данные второго сообщения и т.д.
 180                                    )
 181                              )
 182        );
 183 ]]>
 184             </programlisting>
 185
 186             <para>
 187                 Информационные ресурсы:
 188                 <itemizedlist>
 189                     <listitem>
 190                         <para>
 191                             Спецификация RSS 2.0: <ulink url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
 192                         </para>
 193                     </listitem>
 194                     <listitem>
 195                         <para>
 196                             Спецификация Atom: <ulink url="http://tools.ietf.org/html/rfc4287">RFC 4287</ulink>
 197                         </para>
 198                     </listitem>
 199                     <listitem>
 200                         <para>
 201                             Спецификация WFW: <ulink url="http://wellformedweb.org/news/wfw_namespace_elements">Well
 202                             Formed Web</ulink>
 203                         </para>
 204                     </listitem>
 205                     <listitem>
 206                         <para>
 207                             Спецификация iTunes:
 208                             <ulink url="http://www.apple.com/itunes/store/podcaststechspecs.html">Технические спецификации iTunes</ulink>
 209                         </para>
 210                     </listitem>
 211                 </itemizedlist>
 212             </para>
 213
 214         </sect3>
 215
 216         <sect3 id="zend.feed.importing.custom.importbuilder">
 217
 218             <title>Импортирование из специального источника данных</title>
 219
 220             <para>
 221                 Вы можете создать экземпляр Zeed_Feed из любого источника
 222                 данных, реализующего интерфейс
 223                 <code>Zend_Feed_Builder_Interface</code>. Вам нужно только
 224                 реализовать методы <code>getHeader()</code> и
 225                 <code>getEntries()</code> для того, чтобы можно было
 226                 использовать свой объект с
 227                 <code>Zend_Feed::importBuilder()</code>. Простой пример -
 228                 вы можете использовать компоновщик
 229                 <code>Zend_Feed_Builder</code>, который принимает массив в
 230                 своем конструкторе, выполняет
 231                 некоторую проверку и затем может использоваться в методе
 232                 <code>importBuilder()</code>. <code>getEntries()</code>
 233                 должен возвращать массив экземпляров
 234                 <code>Zend_Feed_Builder_Entry</code>.
 235             </para>
 236
 237             <note>
 238                 <para>
 239                     <code>Zend_Feed_Builder</code> служит только в качестве
 240                     конкретной реализации для демонстрации использования.
 241                     Пользователи должны создавать свои классы, реализующие
 242                     интерфейс <code>Zend_Feed_Builder_Interface</code>.
 243                 </para>
 244             </note>
 245
 246             <para>
 247                 Ниже приведен пример использования
 248                 <code>Zend_Feed::importBuilder()</code>:
 249             </para>
 250
 251             <programlisting language="php"><![CDATA[
 252 // Импортирование ленты из специального созданного ресурса-компоновщика
 253 $atomFeedFromArray =
 254     Zend_Feed::importBuilder(new Zend_Feed_Builder($array));
 255
 256 // Следующая строка эквивалентна предыдущей.
 257 // По умолчанию возвращается экземпляр Zend_Feed_Atom
 258 $atomFeedFromArray =
 259     Zend_Feed::importArray(new Zend_Feed_Builder($array), 'atom');
 260
 261 // Импортирование RSS-ленты из специально созданного ресурса-компоновщика
 262 $rssFeedFromArray =
 263     Zend_Feed::importArray(new Zend_Feed_Builder($array), 'rss');
 264 ]]>
 265             </programlisting>
 266
 267         </sect3>
 268
 269         <sect3 id="zend.feed.importing.custom.dump">
 270
 271             <title>Дапм содержимого ленты</title>
 272
 273             <para>
 274                 Для того, чтобы произвести дамп экземпляра
 275                 <code>Zend_Feed_Abstract</code>, вы можете использовать методы
 276                 <code>send()</code> или <code>saveXml()</code>.
 277             </para>
 278
 279             <programlisting language="php">
 280 <![CDATA[
 281 assert($feed instanceof Zend_Feed_Abstract);
 282
 283 // вывод дампа ленты
 284 print $feed->saveXML();
 285
 286 // отправка HTTP-заголовков и вывод дампа ленты
 287 $feed->send();
 288 ]]>
 289             </programlisting>
 290
 291         </sect3>
 292
 293     </sect2>
 294
 295 </sect1>
 296 <!--
 297 vim:se ts=4 sw=4 et:
 298 -->