documentation/manual/en/module_specs/Zend_Service_Delicious.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.delicious">
   4     <title>Zend_Service_Delicious</title>
   5
   6     <sect2 id="zend.service.delicious.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Delicious</classname> is simple <acronym>API</acronym> for using
  11             <ulink url="http://del.icio.us">del.icio.us</ulink> <acronym>XML</acronym> and
  12             <acronym>JSON</acronym> web services. This component gives you read-write access to
  13             posts at del.icio.us if you provide credentials. It also allows read-only access to
  14             public data of all users.
  15         </para>
  16
  17         <example id="zend.service.delicious.introduction.getAllPosts">
  18             <title>Get all posts</title>
  19
  20             <programlisting language="php"><![CDATA[
  21 $delicious = new Zend_Service_Delicious('username', 'password');
  22 $posts = $delicious->getAllPosts();
  23
  24 foreach ($posts as $post) {
  25     echo "--\n";
  26     echo "Title: {$post->getTitle()}\n";
  27     echo "Url: {$post->getUrl()}\n";
  28 }
  29 ]]></programlisting>
  30         </example>
  31     </sect2>
  32
  33     <sect2 id="zend.service.delicious.retrieving_posts">
  34         <title>Retrieving posts</title>
  35
  36         <para>
  37             <classname>Zend_Service_Delicious</classname> provides three methods for retrieving
  38             posts: <methodname>getPosts()</methodname>, <methodname>getRecentPosts()</methodname>
  39             and <methodname>getAllPosts()</methodname>. All of these methods return an instance of
  40             <classname>Zend_Service_Delicious_PostList</classname>, which holds all retrieved posts.
  41         </para>
  42
  43         <programlisting language="php"><![CDATA[
  44 /**
  45  * Get posts matching the arguments. If no date or url is given,
  46  * most recent date will be used.
  47  *
  48  * @param string $tag Optional filtering by tag
  49  * @param Zend_Date $dt Optional filtering by date
  50  * @param string $url Optional filtering by url
  51  * @return Zend_Service_Delicious_PostList
  52  */
  53 public function getPosts($tag = null, $dt = null, $url = null);
  54
  55 /**
  56  * Get recent posts
  57  *
  58  * @param string $tag   Optional filtering by tag
  59  * @param string $count Maximal number of posts to be returned
  60  *                      (default 15)
  61  * @return Zend_Service_Delicious_PostList
  62  */
  63 public function getRecentPosts($tag = null, $count = 15);
  64
  65 /**
  66  * Get all posts
  67  *
  68  * @param string $tag Optional filtering by tag
  69  * @return Zend_Service_Delicious_PostList
  70  */
  71 public function getAllPosts($tag = null);
  72 ]]></programlisting>
  73     </sect2>
  74
  75     <sect2 id="zend.service.delicious.postlist">
  76         <title>Zend_Service_Delicious_PostList</title>
  77
  78         <para>
  79             Instances of this class are returned by the <methodname>getPosts()</methodname>,
  80             <methodname>getAllPosts()</methodname>, <methodname>getRecentPosts()</methodname>, and
  81             <methodname>getUserPosts()</methodname> methods of
  82             <classname>Zend_Service_Delicious</classname>.
  83         </para>
  84
  85         <para>
  86             For easier data access this class implements the <code>Countable</code>,
  87             <code>Iterator</code>, and <code>ArrayAccess</code> interfaces.
  88         </para>
  89
  90         <example id="zend.service.delicious.postlist.accessing_post_lists">
  91             <title>Accessing post lists</title>
  92
  93             <programlisting language="php"><![CDATA[
  94 $delicious = new Zend_Service_Delicious('username', 'password');
  95 $posts = $delicious->getAllPosts();
  96
  97 // count posts
  98 echo count($posts);
  99
 100 // iterate over posts
 101 foreach ($posts as $post) {
 102     echo "--\n";
 103     echo "Title: {$post->getTitle()}\n";
 104     echo "Url: {$post->getUrl()}\n";
 105 }
 106
 107 // get post using array access
 108 echo $posts[0]->getTitle();
 109 ]]></programlisting>
 110         </example>
 111
 112         <note>
 113             <para>
 114                 The <methodname>ArrayAccess::offsetSet()</methodname> and
 115                 <methodname>ArrayAccess::offsetUnset()</methodname> methods throw exceptions in this
 116                 implementation. Thus, code like <code>unset($posts[0]);</code> and
 117                 <code>$posts[0] = 'A';</code> will throw exceptions because these properties are
 118                 read-only.
 119             </para>
 120         </note>
 121
 122         <para>
 123             Post list objects have two built-in filtering capabilities. Post lists may be filtered
 124             by tags and by <acronym>URL</acronym>.
 125         </para>
 126
 127         <example id="zend.service.delicious.postlist.example.withTags">
 128             <title>Filtering a Post List with Specific Tags</title>
 129
 130             <para>
 131                 Posts may be filtered by specific tags using <methodname>withTags()</methodname>. As
 132                 a convenience, <methodname>withTag()</methodname> is also provided for when only a
 133                 single tag needs to be specified.
 134             </para>
 135
 136             <programlisting language="php"><![CDATA[
 137 $delicious = new Zend_Service_Delicious('username', 'password');
 138 $posts = $delicious->getAllPosts();
 139
 140 // Print posts having "php" and "zend" tags
 141 foreach ($posts->withTags(array('php', 'zend')) as $post) {
 142     echo "Title: {$post->getTitle()}\n";
 143     echo "Url: {$post->getUrl()}\n";
 144 }
 145 ]]></programlisting>
 146         </example>
 147
 148         <example id="zend.service.delicious.postlist.example.byUrl">
 149             <title>Filtering a Post List by URL</title>
 150
 151             <para>
 152                 Posts may be filtered by <acronym>URL</acronym> matching a specified regular
 153                 expression using the <methodname>withUrl()</methodname> method:
 154             </para>
 155
 156             <programlisting language="php"><![CDATA[
 157 $delicious = new Zend_Service_Delicious('username', 'password');
 158 $posts = $delicious->getAllPosts();
 159
 160 // Print posts having "help" in the URL
 161 foreach ($posts->withUrl('/help/') as $post) {
 162     echo "Title: {$post->getTitle()}\n";
 163     echo "Url: {$post->getUrl()}\n";
 164 }
 165 ]]></programlisting>
 166         </example>
 167     </sect2>
 168
 169     <sect2 id="zend.service.delicious.editing_posts">
 170         <title>Editing posts</title>
 171
 172         <example id="zend.service.delicious.editing_posts.post_editing">
 173             <title>Post editing</title>
 174
 175             <programlisting language="php"><![CDATA[
 176 $delicious = new Zend_Service_Delicious('username', 'password');
 177 $posts = $delicious->getPosts();
 178
 179 // set title
 180 $posts[0]->setTitle('New title');
 181 // save changes
 182 $posts[0]->save();
 183 ]]></programlisting>
 184         </example>
 185
 186         <example id="zend.service.delicious.editing_posts.method_call_chaining">
 187             <title>Method call chaining</title>
 188
 189             <para>
 190                Every setter method returns the post object so that you can chain method calls using
 191                a fluent interface.
 192             </para>
 193
 194             <programlisting language="php"><![CDATA[
 195 $delicious = new Zend_Service_Delicious('username', 'password');
 196 $posts = $delicious->getPosts();
 197
 198 $posts[0]->setTitle('New title')
 199          ->setNotes('New notes')
 200          ->save();
 201 ]]></programlisting>
 202         </example>
 203     </sect2>
 204
 205     <sect2 id="zend.service.delicious.deleting_posts">
 206         <title>Deleting posts</title>
 207
 208         <para>
 209             There are two ways to delete a post, by specifying the post <acronym>URL</acronym> or by
 210             calling the <methodname>delete()</methodname> method upon a post object.
 211         </para>
 212
 213         <example id="zend.service.delicious.deleting_posts.deleting_posts">
 214             <title>Deleting posts</title>
 215
 216             <programlisting language="php"><![CDATA[
 217 $delicious = new Zend_Service_Delicious('username', 'password');
 218
 219 // by specifying URL
 220 $delicious->deletePost('http://framework.zend.com');
 221
 222 // or by calling the method upon a post object
 223 $posts = $delicious->getPosts();
 224 $posts[0]->delete();
 225
 226 // another way of using deletePost()
 227 $delicious->deletePost($posts[0]->getUrl());
 228 ]]></programlisting>
 229         </example>
 230     </sect2>
 231
 232     <sect2 id="zend.service.delicious.adding_posts">
 233         <title>Adding new posts</title>
 234
 235         <para>
 236             To add a post you first need to call the <methodname>createNewPost()</methodname>
 237             method, which returns a <classname>Zend_Service_Delicious_Post</classname> object. When
 238             you edit the post, you need to save it to the del.icio.us database by calling the
 239             <methodname>save()</methodname> method.
 240         </para>
 241
 242         <example id="zend.service.delicious.adding_posts.adding_a_post">
 243             <title>Adding a post</title>
 244
 245             <programlisting language="php"><![CDATA[
 246 $delicious = new Zend_Service_Delicious('username', 'password');
 247
 248 // create a new post and save it (with method call chaining)
 249 $delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
 250           ->setNotes('Zend Framework Homepage')
 251           ->save();
 252
 253 // create a new post and save it  (without method call chaining)
 254 $newPost = $delicious->createNewPost('Zend Framework',
 255                                      'http://framework.zend.com');
 256 $newPost->setNotes('Zend Framework Homepage');
 257 $newPost->save();
 258 ]]></programlisting>
 259         </example>
 260     </sect2>
 261
 262     <sect2 id="zend.service.delicious.tags">
 263         <title>Tags</title>
 264
 265         <example id="zend.service.delicious.tags.tags">
 266             <title>Tags</title>
 267
 268             <programlisting language="php"><![CDATA[
 269 $delicious = new Zend_Service_Delicious('username', 'password');
 270
 271 // get all tags
 272 print_r($delicious->getTags());
 273
 274 // rename tag ZF to zendFramework
 275 $delicious->renameTag('ZF', 'zendFramework');
 276 ]]></programlisting>
 277         </example>
 278     </sect2>
 279
 280     <sect2 id="zend.service.delicious.bundles">
 281         <title>Bundles</title>
 282
 283         <example id="zend.service.delicious.bundles.example">
 284             <title>Bundles</title>
 285
 286             <programlisting language="php"><![CDATA[
 287 $delicious = new Zend_Service_Delicious('username', 'password');
 288
 289 // get all bundles
 290 print_r($delicious->getBundles());
 291
 292 // delete bundle someBundle
 293 $delicious->deleteBundle('someBundle');
 294
 295 // add bundle
 296 $delicious->addBundle('newBundle', array('tag1', 'tag2'));
 297 ]]></programlisting>
 298         </example>
 299     </sect2>
 300
 301     <sect2 id="zend.service.delicious.public_data">
 302         <title>Public data</title>
 303
 304         <para>
 305             The del.icio.us web <acronym>API</acronym> allows access to the public data of all
 306             users.
 307         </para>
 308
 309         <table id="zend.service.delicious.public_data.functions_for_retrieving_public_data">
 310             <title>Methods for retrieving public data</title>
 311
 312             <tgroup cols="3">
 313                 <thead>
 314                     <row>
 315                         <entry>Name</entry>
 316                         <entry>Description</entry>
 317                         <entry>Return type</entry>
 318                     </row>
 319                 </thead>
 320
 321                 <tbody>
 322                     <row>
 323                         <entry><methodname>getUserFans()</methodname></entry>
 324                         <entry>Retrieves fans of a user</entry>
 325                         <entry>Array</entry>
 326                     </row>
 327
 328                     <row>
 329                         <entry><methodname>getUserNetwork()</methodname></entry>
 330                         <entry>Retrieves network of a user</entry>
 331                         <entry>Array</entry>
 332                     </row>
 333
 334                     <row>
 335                         <entry><methodname>getUserPosts()</methodname></entry>
 336                         <entry>Retrieves posts of a user</entry>
 337                         <entry>Zend_Service_Delicious_PostList</entry>
 338                     </row>
 339
 340                     <row>
 341                         <entry><methodname>getUserTags()</methodname></entry>
 342                         <entry>Retrieves tags of a user</entry>
 343                         <entry>Array</entry>
 344                     </row>
 345                 </tbody>
 346             </tgroup>
 347         </table>
 348
 349         <note>
 350             <para>
 351                 When using only these methods, a username and password combination is not required
 352                 when constructing a new <classname>Zend_Service_Delicious</classname> object.
 353             </para>
 354         </note>
 355
 356         <example id="zend.service.delicious.public_data.retrieving_public_data">
 357             <title>Retrieving public data</title>
 358
 359             <programlisting language="php"><![CDATA[
 360 // username and password are not required
 361 $delicious = new Zend_Service_Delicious();
 362
 363 // get fans of user someUser
 364 print_r($delicious->getUserFans('someUser'));
 365
 366 // get network of user someUser
 367 print_r($delicious->getUserNetwork('someUser'));
 368
 369 // get tags of user someUser
 370 print_r($delicious->getUserTags('someUser'));
 371 ]]></programlisting>
 372         </example>
 373
 374         <sect3 id="zend.service.delicious.public_data.posts">
 375             <title>Public posts</title>
 376
 377             <para>
 378                 When retrieving public posts with the <methodname>getUserPosts()</methodname>
 379                 method, a <classname>Zend_Service_Delicious_PostList</classname> object is returned,
 380                 and it contains <classname>Zend_Service_Delicious_SimplePost</classname> objects,
 381                 which contain basic information about the posts, including <acronym>URL</acronym>,
 382                 title, notes, and tags.
 383             </para>
 384
 385             <table id="zend.service.delicious.public_data.posts.SimplePost_methods">
 386                 <title>Methods of the Zend_Service_Delicious_SimplePost class</title>
 387
 388                 <tgroup cols="3">
 389                     <thead>
 390                         <row>
 391                             <entry>Name</entry>
 392                             <entry>Description</entry>
 393                             <entry>Return type</entry>
 394                         </row>
 395                     </thead>
 396
 397                     <tbody>
 398                         <row>
 399                             <entry><methodname>getNotes()</methodname></entry>
 400                             <entry>Returns notes of a post</entry>
 401                             <entry>String</entry>
 402                         </row>
 403
 404                         <row>
 405                             <entry><methodname>getTags()</methodname></entry>
 406                             <entry>Returns tags of a post</entry>
 407                             <entry>Array</entry>
 408                         </row>
 409
 410                         <row>
 411                             <entry><methodname>getTitle()</methodname></entry>
 412                             <entry>Returns title of a post</entry>
 413                             <entry>String</entry>
 414                         </row>
 415
 416                         <row>
 417                             <entry><methodname>getUrl()</methodname></entry>
 418                             <entry>Returns <acronym>URL</acronym> of a post</entry>
 419                             <entry>String</entry>
 420                         </row>
 421                     </tbody>
 422                 </tgroup>
 423             </table>
 424         </sect3>
 425     </sect2>
 426
 427     <sect2 id="zend.service.delicious.httpclient">
 428         <title>HTTP client</title>
 429
 430         <para>
 431             <classname>Zend_Service_Delicious</classname> uses
 432             <classname>Zend_Rest_Client</classname> for making <acronym>HTTP</acronym> requests to
 433             the del.icio.us web service. To change which <acronym>HTTP</acronym> client
 434             <classname>Zend_Service_Delicious</classname> uses, you need to change the
 435             <acronym>HTTP</acronym> client of <classname>Zend_Rest_Client</classname>.
 436         </para>
 437
 438         <example id="zend.service.delicious.httpclient.changing">
 439             <title>Changing the HTTP client of Zend_Rest_Client</title>
 440
 441             <programlisting language="php"><![CDATA[
 442 $myHttpClient = new My_Http_Client();
 443 Zend_Rest_Client::setHttpClient($myHttpClient);
 444 ]]></programlisting>
 445         </example>
 446
 447         <para>
 448             When you are making more than one request with
 449             <classname>Zend_Service_Delicious</classname> to speed your requests, it's better to
 450             configure your <acronym>HTTP</acronym> client to keep connections alive.
 451         </para>
 452
 453         <example id="zend.service.delicious.httpclient.keepalive">
 454             <title>Configuring your HTTP client to keep connections alive</title>
 455
 456             <programlisting language="php"><![CDATA[
 457 Zend_Rest_Client::getHttpClient()->setConfig(array(
 458         'keepalive' => true
 459 ));
 460 ]]></programlisting>
 461         </example>
 462
 463         <note>
 464             <para>
 465                 When a <classname>Zend_Service_Delicious</classname> object is constructed, the
 466                 <acronym>SSL</acronym> transport of <classname>Zend_Rest_Client</classname> is set
 467                 to <code>'ssl'</code> rather than the default of <code>'ssl2'</code>. This is
 468                 because del.icio.us has some problems with <code>'ssl2'</code>, such as requests
 469                 taking a long time to complete (around 2 seconds).
 470             </para>
 471         </note>
 472     </sect2>
 473 </sect1>
 474 <!--
 475 vim:se ts=4 sw=4 et:
 476 -->