documentation/manual/en/module_specs/Zend_Service_Twitter.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.twitter" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Zend_Service_Twitter</title>
   5
   6     <sect2 id="zend.service.twitter.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Twitter</classname> provides a client for the
  11             <ulink url="http://apiwiki.twitter.com/Twitter-API-Documentation">Twitter
  12             <acronym>REST</acronym> <acronym>API</acronym></ulink>.
  13             <classname>Zend_Service_Twitter</classname> allows you to query the public timeline. If
  14             you provide a username and password for Twitter, it will allow you to get and update
  15             your status, reply to friends, direct message friends, mark tweets as favorite, and
  16             much more.
  17         </para>
  18
  19         <para>
  20             <classname>Zend_Service_Twitter</classname> is implementing a <acronym>REST</acronym>
  21             service, and all methods return an instance of
  22             <classname>Zend_Rest_Client_Result</classname>.
  23         </para>
  24
  25         <para>
  26             <classname>Zend_Service_Twitter</classname> is broken up into subsections so you can
  27             easily identify which type of call is being requested.
  28         </para>
  29
  30         <itemizedlist>
  31             <listitem>
  32                 <para>
  33                     <code>account</code> makes sure that your account credentials are valid, checks
  34                     your <acronym>API</acronym> rate limit, and ends the current session for the
  35                     authenticated user.
  36                 </para>
  37             </listitem>
  38
  39             <listitem>
  40                 <para>
  41                     <code>status</code> retrieves the public and user timelines and
  42                     shows, updates, destroys, and retrieves replies for the authenticated user.
  43                 </para>
  44             </listitem>
  45
  46             <listitem>
  47                 <para>
  48                     <code>user</code> retrieves friends and followers for the authenticated user
  49                     and returns extended information about a passed user.
  50                 </para>
  51             </listitem>
  52
  53             <listitem>
  54                 <para>
  55                     <code>directMessage</code> retrieves the authenticated user's received direct
  56                     messages, deletes direct messages, and sends new direct messages.
  57                 </para>
  58             </listitem>
  59
  60             <listitem>
  61                 <para>
  62                     <code>friendship</code> creates and removes friendships for the
  63                     authenticated user.
  64                 </para>
  65             </listitem>
  66
  67             <listitem>
  68                 <para>
  69                     <code>favorite</code> lists, creates, and removes favorite tweets.
  70                 </para>
  71             </listitem>
  72
  73             <listitem>
  74                 <para>
  75                     <code>block</code> blocks and unblocks users from following you.
  76                 </para>
  77             </listitem>
  78         </itemizedlist>
  79     </sect2>
  80
  81     <sect2 id="zend.service.twitter.authentication">
  82         <title>Authentication</title>
  83
  84         <para>
  85             With the exception of fetching the public timeline,
  86             <classname>Zend_Service_Twitter</classname> requires authentication to work.
  87             Twitter currently uses
  88             <ulink url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">HTTP Basic
  89             Authentication</ulink>. You can pass in your username or registered email along with
  90             your password for Twitter to login.
  91         </para>
  92
  93         <example id="zend.service.twitter.authentication.example">
  94             <title>Creating the Twitter Class</title>
  95
  96             <para>
  97                 The following code sample is how you create the Twitter service, pass in your
  98                 username and password, and verify that they are correct.
  99             </para>
 100
 101             <programlisting language="php"><![CDATA[
 102 $twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 103
 104 // verify your credentials with Twitter
 105 $response = $twitter->account->verifyCredentials();
 106 ]]></programlisting>
 107
 108             <para>
 109                 You can also pass in an array that contains the username and password as the
 110                 first argument.
 111             </para>
 112
 113             <programlisting language="php"><![CDATA[
 114 $userInfo   = array('username' => 'foo', 'password' => 'bar');
 115 $twitter    = new Zend_Service_Twitter($userInfo);
 116
 117 // verify your credentials with Twitter
 118 $response = $twitter->account->verifyCredentials();
 119 ]]></programlisting>
 120         </example>
 121     </sect2>
 122
 123     <sect2 id="zend.service.twitter.account">
 124         <title>Account Methods</title>
 125
 126         <itemizedlist>
 127             <listitem>
 128                 <para>
 129                     <methodname>verifyCredentials()</methodname> tests if supplied user
 130                     credentials are valid with minimal overhead.
 131                 </para>
 132
 133                 <example id="zend.service.twitter.account.verifycredentails">
 134                     <title>Verifying credentials</title>
 135
 136                     <programlisting language="php"><![CDATA[
 137 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 138 $response   = $twitter->account->verifyCredentials();
 139 ]]></programlisting>
 140                 </example>
 141             </listitem>
 142
 143             <listitem>
 144                 <para>
 145                     <methodname>endSession()</methodname> signs users out of
 146                     client-facing applications.
 147                 </para>
 148
 149                 <example id="zend.service.twitter.account.endsession">
 150                     <title>Sessions ending</title>
 151
 152                     <programlisting language="php"><![CDATA[
 153 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 154 $response   = $twitter->account->endSession();
 155 ]]></programlisting>
 156                 </example>
 157             </listitem>
 158
 159             <listitem>
 160                 <para>
 161                     <methodname>rateLimitStatus()</methodname> returns the remaining number of
 162                     <acronym>API</acronym> requests available to the authenticating user
 163                     before the <acronym>API</acronym> limit is reached for the current hour.
 164                 </para>
 165
 166                 <example id="zend.service.twitter.account.ratelimitstatus">
 167                     <title>Rating limit status</title>
 168
 169                     <programlisting language="php"><![CDATA[
 170 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 171 $response   = $twitter->account->rateLimitStatus();
 172 ]]></programlisting>
 173                 </example>
 174             </listitem>
 175         </itemizedlist>
 176     </sect2>
 177
 178     <sect2 id="zend.service.twitter.status">
 179         <title>Status Methods</title>
 180
 181         <itemizedlist>
 182             <listitem>
 183                 <para>
 184                     <methodname>publicTimeline()</methodname> returns the 20 most recent statuses
 185                     from non-protected users with a custom user icon. The public timeline is cached
 186                     by Twitter for 60 seconds.
 187                 </para>
 188
 189                 <example id="zend.service.twitter.status.publictimeline">
 190                     <title>Retrieving public timeline</title>
 191
 192                     <programlisting language="php"><![CDATA[
 193 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 194 $response   = $twitter->status->publicTimeline();
 195 ]]></programlisting>
 196                 </example>
 197             </listitem>
 198
 199             <listitem>
 200                 <para>
 201                     <methodname>friendsTimeline()</methodname> returns the 20 most recent statuses
 202                     posted by the authenticating user and that user's friends.
 203                 </para>
 204
 205                 <example id="zend.service.twitter.status.friendstimeline">
 206                     <title>Retrieving friends timeline</title>
 207
 208                     <programlisting language="php"><![CDATA[
 209 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 210 $response   = $twitter->status->friendsTimeline();
 211 ]]></programlisting>
 212                 </example>
 213
 214                 <para>
 215                     The <methodname>friendsTimeline()</methodname> method accepts an array of
 216                     optional parameters to modify the query.
 217                 </para>
 218
 219                 <itemizedlist>
 220                     <listitem>
 221                         <para>
 222                             <code>since</code> narrows the returned results to just those statuses
 223                             created after the specified date/time (up to 24 hours old).
 224                         </para>
 225                     </listitem>
 226
 227                     <listitem>
 228                         <para>
 229                             <code>page</code> specifies which page you want to return.
 230                         </para>
 231                     </listitem>
 232                 </itemizedlist>
 233             </listitem>
 234
 235             <listitem>
 236                 <para>
 237                     <methodname>userTimeline()</methodname> returns the 20 most recent statuses
 238                     posted from the authenticating user.
 239                 </para>
 240
 241                 <example id="zend.service.twitter.status.usertimeline">
 242                     <title>Retrieving user timeline</title>
 243
 244                     <programlisting language="php"><![CDATA[
 245 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 246 $response   = $twitter->status->userTimeline();
 247 ]]></programlisting>
 248                 </example>
 249
 250                 <para>
 251                     The <methodname>userTimeline()</methodname> method accepts an array of optional
 252                     parameters to modify the query.
 253                 </para>
 254
 255                 <itemizedlist>
 256                     <listitem>
 257                         <para>
 258                             <code>id</code> specifies the ID or screen name of the user for whom to
 259                             return the friends_timeline.
 260                         </para>
 261                     </listitem>
 262
 263                     <listitem>
 264                         <para>
 265                             <code>since</code> narrows the returned results to just those statuses
 266                             created after the specified date/time (up to 24 hours old).
 267                         </para>
 268                     </listitem>
 269
 270                     <listitem>
 271                         <para>
 272                             <code>page</code> specifies which page you want to return.
 273                         </para>
 274                     </listitem>
 275
 276                     <listitem>
 277                         <para>
 278                             <code>count</code> specifies the number of statuses to retrieve.
 279                             May not be greater than 200.
 280                         </para>
 281                     </listitem>
 282                 </itemizedlist>
 283             </listitem>
 284
 285             <listitem>
 286                 <para>
 287                     <methodname>show()</methodname> returns a single status, specified by the
 288                     <code>id</code> parameter below. The status' author will be returned inline.
 289                 </para>
 290
 291                 <example id="zend.service.twitter.status.show">
 292                     <title>Showing user status</title>
 293
 294                     <programlisting language="php"><![CDATA[
 295 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 296 $response   = $twitter->status->show(1234);
 297 ]]></programlisting>
 298                 </example>
 299             </listitem>
 300
 301             <listitem>
 302                 <para>
 303                     <methodname>update()</methodname> updates the authenticating user's status.
 304                     This method requires that you pass in the status update that you want to post
 305                     to Twitter.
 306                 </para>
 307
 308                 <example id="zend.service.twitter.status.update">
 309                     <title>Updating user status</title>
 310
 311                     <programlisting language="php"><![CDATA[
 312 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 313 $response   = $twitter->status->update('My Great Tweet');
 314 ]]></programlisting>
 315                 </example>
 316
 317                 <para>
 318                     The <methodname>update()</methodname> method accepts a second additional
 319                     parameter.
 320                 </para>
 321
 322                 <itemizedlist>
 323                     <listitem>
 324                         <para>
 325                             <code>in_reply_to_status_id</code> specifies the ID of an existing
 326                             status that the status to be posted is in reply to.
 327                         </para>
 328                     </listitem>
 329                 </itemizedlist>
 330             </listitem>
 331
 332             <listitem>
 333                 <para>
 334                     <methodname>replies()</methodname> returns the 20 most recent @replies (status
 335                     updates prefixed with @username) for the authenticating user.
 336                 </para>
 337
 338                 <example id="zend.service.twitter.status.replies">
 339                     <title>Showing user replies</title>
 340
 341                     <programlisting language="php"><![CDATA[
 342 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 343 $response   = $twitter->status->replies();
 344 ]]></programlisting>
 345                 </example>
 346
 347                 <para>
 348                     The <methodname>replies()</methodname> method accepts an array of optional
 349                     parameters to modify the query.
 350                 </para>
 351
 352                 <itemizedlist>
 353                     <listitem>
 354                         <para>
 355                             <code>since</code> narrows the returned results to just those statuses
 356                             created after the specified date/time (up to 24 hours old).
 357                         </para>
 358                     </listitem>
 359
 360                     <listitem>
 361                         <para>
 362                             <code>page</code> specifies which page you want to return.
 363                         </para>
 364                     </listitem>
 365                     <listitem>
 366                         <para>
 367                             <code>since_id</code> returns only statuses with an ID greater than
 368                             (that is, more recent than) the specified ID.
 369                         </para>
 370                     </listitem>
 371                 </itemizedlist>
 372             </listitem>
 373
 374             <listitem>
 375                 <para>
 376                     <methodname>destroy()</methodname> destroys the status specified by the
 377                     required <code>id</code> parameter.
 378                 </para>
 379
 380                 <example id="zend.service.twitter.status.destroy">
 381                     <title>Deleting user status</title>
 382
 383                     <programlisting language="php"><![CDATA[
 384 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 385 $response   = $twitter->status->destroy(12345);
 386 ]]></programlisting>
 387                 </example>
 388             </listitem>
 389         </itemizedlist>
 390     </sect2>
 391
 392      <sect2 id="zend.service.twitter.user">
 393         <title>User Methods</title>
 394
 395         <itemizedlist>
 396             <listitem>
 397                 <para>
 398                     <methodname>friends()</methodname>r eturns up to 100 of the authenticating
 399                     user's friends who have most recently updated, each with current status inline.
 400                 </para>
 401
 402                 <example id="zend.service.twitter.user.friends">
 403                     <title>Retrieving user friends</title>
 404
 405                     <programlisting language="php"><![CDATA[
 406 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 407 $response   = $twitter->user->friends();
 408 ]]></programlisting>
 409                 </example>
 410
 411                 <para>
 412                     The <methodname>friends()</methodname> method accepts an array of optional
 413                     parameters to modify the query.
 414                 </para>
 415
 416                 <itemizedlist>
 417                     <listitem>
 418                         <para>
 419                             <code>id</code> specifies the ID or screen name of the user for whom to
 420                             return a list of friends.
 421                         </para>
 422                     </listitem>
 423
 424                     <listitem>
 425                         <para>
 426                             <code>since</code> narrows the returned results to just those statuses
 427                             created after the specified date/time (up to 24 hours old).
 428                         </para>
 429                     </listitem>
 430
 431                     <listitem>
 432                         <para>
 433                             <code>page</code> specifies which page you want to return.
 434                         </para>
 435                     </listitem>
 436                 </itemizedlist>
 437             </listitem>
 438
 439             <listitem>
 440                 <para>
 441                     <methodname>followers()</methodname> returns the authenticating user's
 442                     followers, each with current status inline.
 443                 </para>
 444
 445                 <example id="zend.service.twitter.user.followers">
 446                     <title>Retrieving user followers</title>
 447
 448                     <programlisting language="php"><![CDATA[
 449 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 450 $response   = $twitter->user->followers();
 451 ]]></programlisting>
 452                 </example>
 453
 454                 <para>
 455                     The <methodname>followers()</methodname> method accepts an array of optional
 456                     parameters to modify the query.
 457                 </para>
 458
 459                 <itemizedlist>
 460                     <listitem>
 461                         <para>
 462                             <code>id</code> specifies the ID or screen name of the user for whom to
 463                             return a list of followers.
 464                         </para>
 465                     </listitem>
 466
 467                     <listitem>
 468                         <para>
 469                             <code>page</code> specifies which page you want to return.
 470                         </para>
 471                     </listitem>
 472                 </itemizedlist>
 473             </listitem>
 474
 475             <listitem>
 476                 <para>
 477                     <methodname>show()</methodname> returns extended information of a given user,
 478                     specified by ID or screen name as per the required <code>id</code>
 479                     parameter below.
 480                 </para>
 481
 482                 <example id="zend.service.twitter.user.show">
 483                     <title>Showing user informations</title>
 484
 485                     <programlisting language="php"><![CDATA[
 486 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 487 $response   = $twitter->user->show('myfriend');
 488 ]]></programlisting>
 489                 </example>
 490             </listitem>
 491         </itemizedlist>
 492     </sect2>
 493
 494     <sect2 id="zend.service.twitter.directmessage">
 495         <title>Direct Message Methods</title>
 496
 497         <itemizedlist>
 498             <listitem>
 499                 <para>
 500                     <methodname>messages()</methodname> returns a list of the 20 most recent direct
 501                     messages sent to the authenticating user.
 502                 </para>
 503
 504                 <example id="zend.service.twitter.directmessage.messages">
 505                     <title>Retrieving recent direct messages received</title>
 506
 507                     <programlisting language="php"><![CDATA[
 508 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 509 $response   = $twitter->directMessage->messages();
 510 ]]></programlisting>
 511                 </example>
 512
 513                 <para>
 514                     The <methodname>message()</methodname> method accepts an array of optional
 515                     parameters to modify the query.
 516                 </para>
 517
 518                 <itemizedlist>
 519                     <listitem>
 520                         <para>
 521                             <code>since_id</code> returns only direct messages with an ID greater
 522                             than (that is, more recent than) the specified ID.
 523                         </para>
 524                     </listitem>
 525
 526                     <listitem>
 527                         <para>
 528                             <code>since</code> narrows the returned results to just those statuses
 529                             created after the specified date/time (up to 24 hours old).
 530                         </para>
 531                     </listitem>
 532
 533                     <listitem>
 534                         <para>
 535                             <code>page</code> specifies which page you want to return.
 536                         </para>
 537                     </listitem>
 538                 </itemizedlist>
 539             </listitem>
 540
 541             <listitem>
 542                 <para>
 543                     <methodname>sent()</methodname> returns a list of the 20 most recent direct
 544                     messages sent by the authenticating user.
 545                 </para>
 546
 547                 <example id="zend.service.twitter.directmessage.sent">
 548                     <title>Retrieving recent direct messages sent</title>
 549
 550                     <programlisting language="php"><![CDATA[
 551 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 552 $response   = $twitter->directMessage->sent();
 553 ]]></programlisting>
 554                 </example>
 555
 556                 <para>
 557                     The <methodname>sent()</methodname> method accepts an array of optional
 558                     parameters to modify the query.
 559                 </para>
 560
 561                 <itemizedlist>
 562                     <listitem>
 563                         <para>
 564                             <code>since_id</code> returns only direct messages with an ID greater
 565                             than (that is, more recent than) the specified ID.
 566                         </para>
 567                     </listitem>
 568
 569                     <listitem>
 570                         <para>
 571                             <code>since</code> narrows the returned results to just those statuses
 572                             created after the specified date/time (up to 24 hours old).
 573                         </para>
 574                     </listitem>
 575
 576                     <listitem>
 577                         <para>
 578                             <code>page</code> specifies which page you want to return.
 579                         </para>
 580                     </listitem>
 581                 </itemizedlist>
 582             </listitem>
 583
 584             <listitem>
 585                 <para>
 586                     <methodname>new()</methodname> sends a new direct message to the specified user
 587                     from the authenticating user. Requires both the user and text parameters below.
 588                 </para>
 589
 590                 <example id="zend.service.twitter.directmessage.new">
 591                     <title>Sending direct message</title>
 592
 593                     <programlisting language="php"><![CDATA[
 594 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 595 $response   = $twitter->directMessage->new('myfriend', 'mymessage');
 596 ]]></programlisting>
 597                 </example>
 598             </listitem>
 599
 600             <listitem>
 601                 <para>
 602                     <methodname>destroy()</methodname> destroys the direct message specified in the
 603                     required <code>id</code> parameter. The authenticating user must be the
 604                     recipient of the specified direct message.
 605                 </para>
 606
 607                 <example id="zend.service.twitter.directmessage.destroy">
 608                     <title>Deleting direct message</title>
 609
 610                     <programlisting language="php"><![CDATA[
 611 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 612 $response   = $twitter->directMessage->destroy(123548);
 613 ]]></programlisting>
 614                 </example>
 615             </listitem>
 616         </itemizedlist>
 617     </sect2>
 618
 619     <sect2 id="zend.service.twitter.friendship">
 620         <title>Friendship Methods</title>
 621
 622         <itemizedlist>
 623             <listitem>
 624                 <para>
 625                     <methodname>create()</methodname> befriends the user specified in the
 626                     <code>id</code> parameter with the authenticating user.
 627                 </para>
 628
 629                 <example id="zend.service.twitter.friendship.create">
 630                     <title>Creating friend</title>
 631
 632                     <programlisting language="php"><![CDATA[
 633 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 634 $response   = $twitter->friendship->create('mynewfriend');
 635 ]]></programlisting>
 636                 </example>
 637             </listitem>
 638
 639             <listitem>
 640                 <para>
 641                     <methodname>destroy()</methodname> discontinues friendship with the user
 642                     specified in the <code>id</code> parameter and the authenticating user.
 643                 </para>
 644
 645                 <example id="zend.service.twitter.friendship.destroy">
 646                     <title>Deleting friend</title>
 647
 648                     <programlisting language="php"><![CDATA[
 649 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 650 $response   = $twitter->friendship->destroy('myoldfriend');
 651 ]]></programlisting>
 652                 </example>
 653             </listitem>
 654
 655             <listitem>
 656                 <para>
 657                     <methodname>exists()</methodname> tests if a friendship exists between the
 658                     user specified in the <code>id</code> parameter and the authenticating user.
 659                 </para>
 660
 661                 <example id="zend.service.twitter.friendship.exists">
 662                     <title>Checking friend existence</title>
 663
 664                     <programlisting language="php"><![CDATA[
 665 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 666 $response   = $twitter->friendship->exists('myfriend');
 667 ]]></programlisting>
 668                 </example>
 669             </listitem>
 670         </itemizedlist>
 671     </sect2>
 672
 673     <sect2 id="zend.service.twitter.favorite">
 674         <title>Favorite Methods</title>
 675
 676         <itemizedlist>
 677             <listitem>
 678                 <para>
 679                     <methodname>favorites()</methodname> returns the 20 most recent favorite
 680                     statuses for the authenticating user or user specified by the
 681                     <code>id</code> parameter.
 682                 </para>
 683
 684                 <example id="zend.service.twitter.favorite.favorites">
 685                     <title>Retrieving favorites</title>
 686
 687                     <programlisting language="php"><![CDATA[
 688 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 689 $response   = $twitter->favorite->favorites();
 690 ]]></programlisting>
 691                 </example>
 692
 693                 <para>
 694                     The <methodname>favorites()</methodname> method accepts an array of optional
 695                     parameters to modify the query.
 696                 </para>
 697
 698                 <itemizedlist>
 699                     <listitem>
 700                         <para>
 701                             <code>id</code> specifies the ID or screen name of the user for whom to
 702                             request a list of favorite statuses.
 703                         </para>
 704                     </listitem>
 705
 706                     <listitem>
 707                         <para>
 708                             <code>page</code> specifies which page you want to return.
 709                         </para>
 710                     </listitem>
 711                 </itemizedlist>
 712             </listitem>
 713
 714             <listitem>
 715                 <para>
 716                     <methodname>create()</methodname> favorites the status specified in the
 717                     <code>id</code> parameter as the authenticating user.
 718                 </para>
 719
 720                 <example id="zend.service.twitter.favorite.create">
 721                     <title>Creating favorites</title>
 722
 723                     <programlisting language="php"><![CDATA[
 724 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 725 $response   = $twitter->favorite->create(12351);
 726 ]]></programlisting>
 727                 </example>
 728             </listitem>
 729
 730             <listitem>
 731                 <para>
 732                     <methodname>destroy()</methodname> un-favorites the status specified in the
 733                     <code>id</code> parameter as the authenticating user.
 734                 </para>
 735
 736                 <example id="zend.service.twitter.favorite.destroy">
 737                     <title>Deleting favorites</title>
 738
 739                     <programlisting language="php"><![CDATA[
 740 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 741 $response   = $twitter->favorite->destroy(12351);
 742 ]]></programlisting>
 743                 </example>
 744             </listitem>
 745         </itemizedlist>
 746     </sect2>
 747
 748     <sect2 id="zend.service.twitter.block">
 749         <title>Block Methods</title>
 750
 751         <itemizedlist>
 752             <listitem>
 753                 <para>
 754                     <methodname>exists()</methodname> checks if the authenticating user is blocking
 755                     a target user and can optionally return the blocked user's object if a
 756                     block does exists.
 757                 </para>
 758
 759                 <example id="zend.service.twitter.block.exists">
 760                     <title>Checking if block exists</title>
 761
 762                     <programlisting language="php"><![CDATA[
 763 $twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 764
 765 // returns true or false
 766 $response = $twitter->block->exists('blockeduser');
 767
 768 // returns the blocked user's info if the user is blocked
 769 $response2 = $twitter->block->exists('blockeduser', true);
 770 ]]></programlisting>
 771                 </example>
 772
 773                 <para>
 774                     The <methodname>favorites()</methodname> method accepts a second
 775                     optional parameter.
 776                 </para>
 777
 778                 <itemizedlist>
 779                     <listitem>
 780                         <para>
 781                             <code>returnResult</code> specifies whether or not return the user
 782                             object instead of just <constant>TRUE</constant> or
 783                             <constant>FALSE</constant>.
 784                         </para>
 785                     </listitem>
 786                 </itemizedlist>
 787             </listitem>
 788
 789             <listitem>
 790                 <para>
 791                     <methodname>create()</methodname> blocks the user specified in the
 792                     <code>id</code> parameter as the authenticating user and destroys a friendship
 793                     to the blocked user if one exists. Returns the blocked user in the requested
 794                     format when successful.
 795                 </para>
 796
 797                 <example id="zend.service.twitter.block.create">
 798                     <title>Blocking a user</title>
 799
 800                     <programlisting language="php"><![CDATA[
 801 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 802 $response   = $twitter->block->create('usertoblock);
 803 ]]></programlisting>
 804                 </example>
 805             </listitem>
 806
 807             <listitem>
 808                 <para>
 809                     <methodname>destroy()</methodname> un-blocks the user specified in the
 810                     <code>id</code> parameter for the authenticating user. Returns the un-blocked
 811                     user in the requested format when successful.
 812                 </para>
 813
 814                 <example id="zend.service.twitter.block.destroy">
 815                     <title>Removing a block</title>
 816
 817                     <programlisting language="php"><![CDATA[
 818 $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 819 $response   = $twitter->block->destroy('blockeduser');
 820 ]]></programlisting>
 821                 </example>
 822             </listitem>
 823
 824             <listitem>
 825                 <para>
 826                     <methodname>blocking()</methodname> returns an array of user objects that the
 827                     authenticating user is blocking.
 828                 </para>
 829
 830                 <example id="zend.service.twitter.block.blocking">
 831                     <title>Who are you blocking</title>
 832
 833                     <programlisting language="php"><![CDATA[
 834 $twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
 835
 836 // return the full user list from the first page
 837 $response = $twitter->block->blocking();
 838
 839 // return an array of numeric user IDs from the second page
 840 $response2 = $twitter->block->blocking(2, true);
 841 ]]></programlisting>
 842                 </example>
 843
 844                 <para>
 845                     The <methodname>favorites()</methodname> method accepts two optional parameters.
 846                 </para>
 847
 848                 <itemizedlist>
 849                     <listitem>
 850                         <para>
 851                             <code>page</code> specifies which page ou want to return. A single page
 852                             contains 20 IDs.
 853                         </para>
 854                     </listitem>
 855
 856                     <listitem>
 857                         <para>
 858                             <code>returnUserIds</code> specifies whether to return an array of
 859                             numeric user IDs the authenticating user is blocking instead of an
 860                             array of user objects.
 861                         </para>
 862                     </listitem>
 863                 </itemizedlist>
 864             </listitem>
 865         </itemizedlist>
 866     </sect2>
 867
 868     <xi:include href="Zend_Service_Twitter_Search.xml" />
 869 </sect1>
 870 <!--
 871 vim:se ts=4 sw=4 et:
 872 -->