library/Zend/Service/Twitter.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   7  * This source file is subject to the new BSD license that is bundled
   8  * with this package in the file LICENSE.txt.
   9  * It is also available through the world-wide-web at this URL:
  10  * http://framework.zend.com/license/new-bsd
  11  * If you did not receive a copy of the license and are unable to
  12  * obtain it through the world-wide-web, please send an email
  13  * to license@zend.com so we can send you a copy immediately.
  14  *
  15  * @category   Zend
  16  * @package    Zend_Service
  17  * @subpackage Twitter
  18  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  19  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20  * @version    $Id$
  21  */
  22
  23 /**
  24  * @see Zend_Rest_Client
  25  */
  26 require_once 'Zend/Rest/Client.php';
  27
  28 /**
  29  * @see Zend_Rest_Client_Result
  30  */
  31 require_once 'Zend/Rest/Client/Result.php';
  32
  33 /**
  34  * @see Zend_Oauth_Consumer
  35  */
  36 require_once 'Zend/Oauth/Consumer.php';
  37
  38 /**
  39  * @category   Zend
  40  * @package    Zend_Service
  41  * @subpackage Twitter
  42  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  43  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  44  */
  45 class Zend_Service_Twitter extends Zend_Rest_Client
  46 {
  47
  48     /**
  49      * 246 is the current limit for a status message, 140 characters are displayed
  50      * initially, with the remainder linked from the web UI or client. The limit is
  51      * applied to a html encoded UTF-8 string (i.e. entities are counted in the limit
  52      * which may appear unusual but is a security measure).
  53      *
  54      * This should be reviewed in the future...
  55      */
  56     const STATUS_MAX_CHARACTERS = 246;
  57
  58     /**
  59      * OAuth Endpoint
  60      */
  61     const OAUTH_BASE_URI = 'http://twitter.com/oauth';
  62
  63     /**
  64      * @var Zend_Http_CookieJar
  65      */
  66     protected $_cookieJar;
  67
  68     /**
  69      * Date format for 'since' strings
  70      *
  71      * @var string
  72      */
  73     protected $_dateFormat = 'D, d M Y H:i:s T';
  74
  75     /**
  76      * Username
  77      *
  78      * @var string
  79      */
  80     protected $_username;
  81
  82     /**
  83      * Current method type (for method proxying)
  84      *
  85      * @var string
  86      */
  87     protected $_methodType;
  88
  89     /**
  90      * Zend_Oauth Consumer
  91      *
  92      * @var Zend_Oauth_Consumer
  93      */
  94     protected $_oauthConsumer = null;
  95
  96     /**
  97      * Types of API methods
  98      *
  99      * @var array
 100      */
 101     protected $_methodTypes = array(
 102         'status',
 103         'user',
 104         'directMessage',
 105         'friendship',
 106         'account',
 107         'favorite',
 108         'block'
 109     );
 110
 111     /**
 112      * Options passed to constructor
 113      *
 114      * @var array
 115      */
 116     protected $_options = array();
 117
 118     /**
 119      * Local HTTP Client cloned from statically set client
 120      *
 121      * @var Zend_Http_Client
 122      */
 123     protected $_localHttpClient = null;
 124
 125     /**
 126      * Constructor
 127      *
 128      * @param  array $options Optional options array
 129      * @return void
 130      */
 131     public function __construct(array $options = null, Zend_Oauth_Consumer $consumer = null)
 132     {
 133         $this->setUri('http://api.twitter.com');
 134         if (!is_array($options)) $options = array();
 135         $options['siteUrl'] = self::OAUTH_BASE_URI;
 136         if ($options instanceof Zend_Config) {
 137             $options = $options->toArray();
 138         }
 139         $this->_options = $options;
 140         if (isset($options['username'])) {
 141             $this->setUsername($options['username']);
 142         }
 143         if (isset($options['accessToken'])
 144         && $options['accessToken'] instanceof Zend_Oauth_Token_Access) {
 145             $this->setLocalHttpClient($options['accessToken']->getHttpClient($options));
 146         } else {
 147             $this->setLocalHttpClient(clone self::getHttpClient());
 148             if (is_null($consumer)) {
 149                 $this->_oauthConsumer = new Zend_Oauth_Consumer($options);
 150             } else {
 151                 $this->_oauthConsumer = $consumer;
 152             }
 153         }
 154     }
 155
 156     /**
 157      * Set local HTTP client as distinct from the static HTTP client
 158      * as inherited from Zend_Rest_Client.
 159      *
 160      * @param Zend_Http_Client $client
 161      * @return self
 162      */
 163     public function setLocalHttpClient(Zend_Http_Client $client)
 164     {
 165         $this->_localHttpClient = $client;
 166         $this->_localHttpClient->setHeaders('Accept-Charset', 'ISO-8859-1,utf-8');
 167         return $this;
 168     }
 169
 170     /**
 171      * Get the local HTTP client as distinct from the static HTTP client
 172      * inherited from Zend_Rest_Client
 173      *
 174      * @return Zend_Http_Client
 175      */
 176     public function getLocalHttpClient()
 177     {
 178         return $this->_localHttpClient;
 179     }
 180
 181     /**
 182      * Checks for an authorised state
 183      *
 184      * @return bool
 185      */
 186     public function isAuthorised()
 187     {
 188         if ($this->getLocalHttpClient() instanceof Zend_Oauth_Client) {
 189             return true;
 190         }
 191         return false;
 192     }
 193
 194     /**
 195      * Retrieve username
 196      *
 197      * @return string
 198      */
 199     public function getUsername()
 200     {
 201         return $this->_username;
 202     }
 203
 204     /**
 205      * Set username
 206      *
 207      * @param  string $value
 208      * @return Zend_Service_Twitter
 209      */
 210     public function setUsername($value)
 211     {
 212         $this->_username = $value;
 213         return $this;
 214     }
 215
 216     /**
 217      * Proxy service methods
 218      *
 219      * @param  string $type
 220      * @return Zend_Service_Twitter
 221      * @throws Zend_Service_Twitter_Exception If method not in method types list
 222      */
 223     public function __get($type)
 224     {
 225         if (!in_array($type, $this->_methodTypes)) {
 226             include_once 'Zend/Service/Twitter/Exception.php';
 227             throw new Zend_Service_Twitter_Exception(
 228                 'Invalid method type "' . $type . '"'
 229             );
 230         }
 231         $this->_methodType = $type;
 232         return $this;
 233     }
 234
 235     /**
 236      * Method overloading
 237      *
 238      * @param  string $method
 239      * @param  array $params
 240      * @return mixed
 241      * @throws Zend_Service_Twitter_Exception if unable to find method
 242      */
 243     public function __call($method, $params)
 244     {
 245         if (method_exists($this->_oauthConsumer, $method)) {
 246             $return = call_user_func_array(array($this->_oauthConsumer, $method), $params);
 247             if ($return instanceof Zend_Oauth_Token_Access) {
 248                 $this->setLocalHttpClient($return->getHttpClient($this->_options));
 249             }
 250             return $return;
 251         }
 252         if (empty($this->_methodType)) {
 253             include_once 'Zend/Service/Twitter/Exception.php';
 254             throw new Zend_Service_Twitter_Exception(
 255                 'Invalid method "' . $method . '"'
 256             );
 257         }
 258         $test = $this->_methodType . ucfirst($method);
 259         if (!method_exists($this, $test)) {
 260             include_once 'Zend/Service/Twitter/Exception.php';
 261             throw new Zend_Service_Twitter_Exception(
 262                 'Invalid method "' . $test . '"'
 263             );
 264         }
 265
 266         return call_user_func_array(array($this, $test), $params);
 267     }
 268
 269     /**
 270      * Initialize HTTP authentication
 271      *
 272      * @return void
 273      */
 274     protected function _init()
 275     {
 276         if (!$this->isAuthorised() && $this->getUsername() !== null) {
 277             require_once 'Zend/Service/Twitter/Exception.php';
 278             throw new Zend_Service_Twitter_Exception(
 279                 'Twitter session is unauthorised. You need to initialize '
 280                 . 'Zend_Service_Twitter with an OAuth Access Token or use '
 281                 . 'its OAuth functionality to obtain an Access Token before '
 282                 . 'attempting any API actions that require authorisation'
 283             );
 284         }
 285         $client = $this->_localHttpClient;
 286         $client->resetParameters();
 287         if (null == $this->_cookieJar) {
 288             $client->setCookieJar();
 289             $this->_cookieJar = $client->getCookieJar();
 290         } else {
 291             $client->setCookieJar($this->_cookieJar);
 292         }
 293     }
 294
 295     /**
 296      * Set date header
 297      *
 298      * @param  int|string $value
 299      * @deprecated Not supported by Twitter since April 08, 2009
 300      * @return void
 301      */
 302     protected function _setDate($value)
 303     {
 304         if (is_int($value)) {
 305             $date = date($this->_dateFormat, $value);
 306         } else {
 307             $date = date($this->_dateFormat, strtotime($value));
 308         }
 309         $this->_localHttpClient->setHeaders('If-Modified-Since', $date);
 310     }
 311
 312     /**
 313      * Public Timeline status
 314      *
 315      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 316      * @return Zend_Rest_Client_Result
 317      */
 318     public function statusPublicTimeline()
 319     {
 320         $this->_init();
 321         $path = '/1/statuses/public_timeline.xml';
 322         $response = $this->_get($path);
 323         return new Zend_Rest_Client_Result($response->getBody());
 324     }
 325
 326     /**
 327      * Friend Timeline Status
 328      *
 329      * $params may include one or more of the following keys
 330      * - id: ID of a friend whose timeline you wish to receive
 331      * - count: how many statuses to return
 332      * - since_id: return results only after the specific tweet
 333      * - page: return page X of results
 334      *
 335      * @param  array $params
 336      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 337      * @return void
 338      */
 339     public function statusFriendsTimeline(array $params = array())
 340     {
 341         $this->_init();
 342         $path = '/1/statuses/friends_timeline';
 343         $_params = array();
 344         foreach ($params as $key => $value) {
 345             switch (strtolower($key)) {
 346                 case 'count':
 347                     $count = (int) $value;
 348                     if (0 >= $count) {
 349                         $count = 1;
 350                     } elseif (200 < $count) {
 351                         $count = 200;
 352                     }
 353                     $_params['count'] = (int) $count;
 354                     break;
 355                 case 'since_id':
 356                     $_params['since_id'] = $this->_validInteger($value);
 357                     break;
 358                 case 'page':
 359                     $_params['page'] = (int) $value;
 360                     break;
 361                 default:
 362                     break;
 363             }
 364         }
 365         $path .= '.xml';
 366         $response = $this->_get($path, $_params);
 367         return new Zend_Rest_Client_Result($response->getBody());
 368     }
 369
 370     /**
 371      * User Timeline status
 372      *
 373      * $params may include one or more of the following keys
 374      * - id: ID of a friend whose timeline you wish to receive
 375      * - since_id: return results only after the tweet id specified
 376      * - page: return page X of results
 377      * - count: how many statuses to return
 378      * - max_id: returns only statuses with an ID less than or equal to the specified ID
 379      * - user_id: specfies the ID of the user for whom to return the user_timeline
 380      * - screen_name: specfies the screen name of the user for whom to return the user_timeline
 381      *
 382      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 383      * @return Zend_Rest_Client_Result
 384      */
 385     public function statusUserTimeline(array $params = array())
 386     {
 387         $this->_init();
 388         $path = '/1/statuses/user_timeline';
 389         $_params = array();
 390         foreach ($params as $key => $value) {
 391             switch (strtolower($key)) {
 392                 case 'id':
 393                     $path .= '/' . $value;
 394                     break;
 395                 case 'page':
 396                     $_params['page'] = (int) $value;
 397                     break;
 398                 case 'count':
 399                     $count = (int) $value;
 400                     if (0 >= $count) {
 401                         $count = 1;
 402                     } elseif (200 < $count) {
 403                         $count = 200;
 404                     }
 405                     $_params['count'] = $count;
 406                     break;
 407                 case 'user_id':
 408                     $_params['user_id'] = $this->_validInteger($value);
 409                     break;
 410                 case 'screen_name':
 411                     $_params['screen_name'] = $this->_validateScreenName($value);
 412                     break;
 413                 case 'since_id':
 414                     $_params['since_id'] = $this->_validInteger($value);
 415                     break;
 416                 case 'max_id':
 417                     $_params['max_id'] = $this->_validInteger($value);
 418                     break;
 419                 default:
 420                     break;
 421             }
 422         }
 423         $path .= '.xml';
 424         $response = $this->_get($path, $_params);
 425         return new Zend_Rest_Client_Result($response->getBody());
 426     }
 427
 428     /**
 429      * Show a single status
 430      *
 431      * @param  int $id Id of status to show
 432      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 433      * @return Zend_Rest_Client_Result
 434      */
 435     public function statusShow($id)
 436     {
 437         $this->_init();
 438         $path = '/1/statuses/show/' . $this->_validInteger($id) . '.xml';
 439         $response = $this->_get($path);
 440         return new Zend_Rest_Client_Result($response->getBody());
 441     }
 442
 443     /**
 444      * Update user's current status
 445      *
 446      * @param  string $status
 447      * @param  int $in_reply_to_status_id
 448      * @return Zend_Rest_Client_Result
 449      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 450      * @throws Zend_Service_Twitter_Exception if message is too short or too long
 451      */
 452     public function statusUpdate($status, $inReplyToStatusId = null)
 453     {
 454         $this->_init();
 455         $path = '/1/statuses/update.xml';
 456         $len = iconv_strlen(htmlspecialchars($status, ENT_QUOTES, 'UTF-8'), 'UTF-8');
 457         if ($len > self::STATUS_MAX_CHARACTERS) {
 458             include_once 'Zend/Service/Twitter/Exception.php';
 459             throw new Zend_Service_Twitter_Exception(
 460                 'Status must be no more than '
 461                 . self::STATUS_MAX_CHARACTERS
 462                 . ' characters in length'
 463             );
 464         } elseif (0 == $len) {
 465             include_once 'Zend/Service/Twitter/Exception.php';
 466             throw new Zend_Service_Twitter_Exception(
 467                 'Status must contain at least one character'
 468             );
 469         }
 470         $data = array('status' => $status);
 471         if (is_numeric($inReplyToStatusId) && !empty($inReplyToStatusId)) {
 472             $data['in_reply_to_status_id'] = $inReplyToStatusId;
 473         }
 474         $response = $this->_post($path, $data);
 475         return new Zend_Rest_Client_Result($response->getBody());
 476     }
 477
 478     /**
 479      * Get status replies
 480      *
 481      * $params may include one or more of the following keys
 482      * - since_id: return results only after the specified tweet id
 483      * - page: return page X of results
 484      *
 485      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 486      * @return Zend_Rest_Client_Result
 487      */
 488     public function statusReplies(array $params = array())
 489     {
 490         $this->_init();
 491         $path = '/1/statuses/mentions.xml';
 492         $_params = array();
 493         foreach ($params as $key => $value) {
 494             switch (strtolower($key)) {
 495                 case 'since_id':
 496                     $_params['since_id'] = $this->_validInteger($value);
 497                     break;
 498                 case 'page':
 499                     $_params['page'] = (int) $value;
 500                     break;
 501                 default:
 502                     break;
 503             }
 504         }
 505         $response = $this->_get($path, $_params);
 506         return new Zend_Rest_Client_Result($response->getBody());
 507     }
 508
 509     /**
 510      * Destroy a status message
 511      *
 512      * @param  int $id ID of status to destroy
 513      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 514      * @return Zend_Rest_Client_Result
 515      */
 516     public function statusDestroy($id)
 517     {
 518         $this->_init();
 519         $path = '/1/statuses/destroy/' . $this->_validInteger($id) . '.xml';
 520         $response = $this->_post($path);
 521         return new Zend_Rest_Client_Result($response->getBody());
 522     }
 523
 524     /**
 525      * User friends
 526      *
 527      * @param  int|string $id Id or username of user for whom to fetch friends
 528      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 529      * @return Zend_Rest_Client_Result
 530      */
 531     public function userFriends(array $params = array())
 532     {
 533         $this->_init();
 534         $path = '/1/statuses/friends';
 535         $_params = array();
 536
 537         foreach ($params as $key => $value) {
 538             switch (strtolower($key)) {
 539                 case 'id':
 540                     $path .= '/' . $value;
 541                     break;
 542                 case 'page':
 543                     $_params['page'] = (int) $value;
 544                     break;
 545                 default:
 546                     break;
 547             }
 548         }
 549         $path .= '.xml';
 550
 551         $response = $this->_get($path, $_params);
 552         return new Zend_Rest_Client_Result($response->getBody());
 553     }
 554
 555     /**
 556      * User Followers
 557      *
 558      * @param  bool $lite If true, prevents inline inclusion of current status for followers; defaults to false
 559      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 560      * @return Zend_Rest_Client_Result
 561      */
 562     public function userFollowers($lite = false)
 563     {
 564         $this->_init();
 565         $path = '/1/statuses/followers.xml';
 566         if ($lite) {
 567             $this->lite = 'true';
 568         }
 569         $response = $this->_get($path);
 570         return new Zend_Rest_Client_Result($response->getBody());
 571     }
 572
 573     /**
 574      * Show extended information on a user
 575      *
 576      * @param  int|string $id User ID or name
 577      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 578      * @return Zend_Rest_Client_Result
 579      */
 580     public function userShow($id)
 581     {
 582         $this->_init();
 583         $path = '/1/users/show.xml';
 584         $response = $this->_get($path, array('id'=>$id));
 585         return new Zend_Rest_Client_Result($response->getBody());
 586     }
 587
 588     /**
 589      * Retrieve direct messages for the current user
 590      *
 591      * $params may include one or more of the following keys
 592      * - since_id: return statuses only greater than the one specified
 593      * - page: return page X of results
 594      *
 595      * @param  array $params
 596      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 597      * @return Zend_Rest_Client_Result
 598      */
 599     public function directMessageMessages(array $params = array())
 600     {
 601         $this->_init();
 602         $path = '/1/direct_messages.xml';
 603         $_params = array();
 604         foreach ($params as $key => $value) {
 605             switch (strtolower($key)) {
 606                 case 'since_id':
 607                     $_params['since_id'] = $this->_validInteger($value);
 608                     break;
 609                 case 'page':
 610                     $_params['page'] = (int) $value;
 611                     break;
 612                 default:
 613                     break;
 614             }
 615         }
 616         $response = $this->_get($path, $_params);
 617         return new Zend_Rest_Client_Result($response->getBody());
 618     }
 619
 620     /**
 621      * Retrieve list of direct messages sent by current user
 622      *
 623      * $params may include one or more of the following keys
 624      * - since_id: return statuses only greater than the one specified
 625      * - page: return page X of results
 626      *
 627      * @param  array $params
 628      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 629      * @return Zend_Rest_Client_Result
 630      */
 631     public function directMessageSent(array $params = array())
 632     {
 633         $this->_init();
 634         $path = '/1/direct_messages/sent.xml';
 635         $_params = array();
 636         foreach ($params as $key => $value) {
 637             switch (strtolower($key)) {
 638                 case 'since_id':
 639                     $_params['since_id'] = $this->_validInteger($value);
 640                     break;
 641                 case 'page':
 642                     $_params['page'] = (int) $value;
 643                     break;
 644                 default:
 645                     break;
 646             }
 647         }
 648         $response = $this->_get($path, $_params);
 649         return new Zend_Rest_Client_Result($response->getBody());
 650     }
 651
 652     /**
 653      * Send a direct message to a user
 654      *
 655      * @param  int|string $user User to whom to send message
 656      * @param  string $text Message to send to user
 657      * @return Zend_Rest_Client_Result
 658      * @throws Zend_Service_Twitter_Exception if message is too short or too long
 659      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 660      */
 661     public function directMessageNew($user, $text)
 662     {
 663         $this->_init();
 664         $path = '/1/direct_messages/new.xml';
 665         $len = iconv_strlen($text, 'UTF-8');
 666         if (0 == $len) {
 667             throw new Zend_Service_Twitter_Exception(
 668                 'Direct message must contain at least one character'
 669             );
 670         } elseif (140 < $len) {
 671             throw new Zend_Service_Twitter_Exception(
 672                 'Direct message must contain no more than 140 characters'
 673             );
 674         }
 675         $data = array('user' => $user, 'text' => $text);
 676         $response = $this->_post($path, $data);
 677         return new Zend_Rest_Client_Result($response->getBody());
 678     }
 679
 680     /**
 681      * Destroy a direct message
 682      *
 683      * @param  int $id ID of message to destroy
 684      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 685      * @return Zend_Rest_Client_Result
 686      */
 687     public function directMessageDestroy($id)
 688     {
 689         $this->_init();
 690         $path = '/1/direct_messages/destroy/' . $this->_validInteger($id) . '.xml';
 691         $response = $this->_post($path);
 692         return new Zend_Rest_Client_Result($response->getBody());
 693     }
 694
 695     /**
 696      * Create friendship
 697      *
 698      * @param  int|string $id User ID or name of new friend
 699      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 700      * @return Zend_Rest_Client_Result
 701      */
 702     public function friendshipCreate($id)
 703     {
 704         $this->_init();
 705         $path = '/1/friendships/create/' . $id . '.xml';
 706         $response = $this->_post($path);
 707         return new Zend_Rest_Client_Result($response->getBody());
 708     }
 709
 710     /**
 711      * Destroy friendship
 712      *
 713      * @param  int|string $id User ID or name of friend to remove
 714      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 715      * @return Zend_Rest_Client_Result
 716      */
 717     public function friendshipDestroy($id)
 718     {
 719         $this->_init();
 720         $path = '/1/friendships/destroy/' . $id . '.xml';
 721         $response = $this->_post($path);
 722         return new Zend_Rest_Client_Result($response->getBody());
 723     }
 724
 725     /**
 726      * Friendship exists
 727      *
 728      * @param int|string $id User ID or name of friend to see if they are your friend
 729      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 730      * @return Zend_Rest_Client_result
 731      */
 732     public function friendshipExists($id)
 733     {
 734         $this->_init();
 735         $path = '/1/friendships/exists.xml';
 736         $data = array('user_a' => $this->getUsername(), 'user_b' => $id);
 737         $response = $this->_get($path, $data);
 738         return new Zend_Rest_Client_Result($response->getBody());
 739     }
 740
 741     /**
 742      * Verify Account Credentials
 743      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 744      *
 745      * @return Zend_Rest_Client_Result
 746      */
 747     public function accountVerifyCredentials()
 748     {
 749         $this->_init();
 750         $response = $this->_get('/1/account/verify_credentials.xml');
 751         return new Zend_Rest_Client_Result($response->getBody());
 752     }
 753
 754     /**
 755      * End current session
 756      *
 757      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 758      * @return true
 759      */
 760     public function accountEndSession()
 761     {
 762         $this->_init();
 763         $this->_get('/1/account/end_session');
 764         return true;
 765     }
 766
 767     /**
 768      * Returns the number of api requests you have left per hour.
 769      *
 770      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 771      * @return Zend_Rest_Client_Result
 772      */
 773     public function accountRateLimitStatus()
 774     {
 775         $this->_init();
 776         $response = $this->_get('/1/account/rate_limit_status.xml');
 777         return new Zend_Rest_Client_Result($response->getBody());
 778     }
 779
 780     /**
 781      * Fetch favorites
 782      *
 783      * $params may contain one or more of the following:
 784      * - 'id': Id of a user for whom to fetch favorites
 785      * - 'page': Retrieve a different page of resuls
 786      *
 787      * @param  array $params
 788      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 789      * @return Zend_Rest_Client_Result
 790      */
 791     public function favoriteFavorites(array $params = array())
 792     {
 793         $this->_init();
 794         $path = '/1/favorites';
 795         $_params = array();
 796         foreach ($params as $key => $value) {
 797             switch (strtolower($key)) {
 798                 case 'id':
 799                     $path .= '/' . $this->_validInteger($value);
 800                     break;
 801                 case 'page':
 802                     $_params['page'] = (int) $value;
 803                     break;
 804                 default:
 805                     break;
 806             }
 807         }
 808         $path .= '.xml';
 809         $response = $this->_get($path, $_params);
 810         return new Zend_Rest_Client_Result($response->getBody());
 811     }
 812
 813     /**
 814      * Mark a status as a favorite
 815      *
 816      * @param  int $id Status ID you want to mark as a favorite
 817      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 818      * @return Zend_Rest_Client_Result
 819      */
 820     public function favoriteCreate($id)
 821     {
 822         $this->_init();
 823         $path = '/1/favorites/create/' . $this->_validInteger($id) . '.xml';
 824         $response = $this->_post($path);
 825         return new Zend_Rest_Client_Result($response->getBody());
 826     }
 827
 828     /**
 829      * Remove a favorite
 830      *
 831      * @param  int $id Status ID you want to de-list as a favorite
 832      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 833      * @return Zend_Rest_Client_Result
 834      */
 835     public function favoriteDestroy($id)
 836     {
 837         $this->_init();
 838         $path = '/1/favorites/destroy/' . $this->_validInteger($id) . '.xml';
 839         $response = $this->_post($path);
 840         return new Zend_Rest_Client_Result($response->getBody());
 841     }
 842
 843     /**
 844      * Blocks the user specified in the ID parameter as the authenticating user.
 845      * Destroys a friendship to the blocked user if it exists.
 846      *
 847      * @param integer|string $id       The ID or screen name of a user to block.
 848      * @return Zend_Rest_Client_Result
 849      */
 850     public function blockCreate($id)
 851     {
 852         $this->_init();
 853         $path = '/1/blocks/create/' . $id . '.xml';
 854         $response = $this->_post($path);
 855         return new Zend_Rest_Client_Result($response->getBody());
 856     }
 857
 858     /**
 859      * Un-blocks the user specified in the ID parameter for the authenticating user
 860      *
 861      * @param integer|string $id       The ID or screen_name of the user to un-block.
 862      * @return Zend_Rest_Client_Result
 863      */
 864     public function blockDestroy($id)
 865     {
 866         $this->_init();
 867         $path = '/1/blocks/destroy/' . $id . '.xml';
 868         $response = $this->_post($path);
 869         return new Zend_Rest_Client_Result($response->getBody());
 870     }
 871
 872     /**
 873      * Returns if the authenticating user is blocking a target user.
 874      *
 875      * @param string|integer $id    The ID or screen_name of the potentially blocked user.
 876      * @param boolean $returnResult Instead of returning a boolean return the rest response from twitter
 877      * @return Boolean|Zend_Rest_Client_Result
 878      */
 879     public function blockExists($id, $returnResult = false)
 880     {
 881         $this->_init();
 882         $path = '/1/blocks/exists/' . $id . '.xml';
 883         $response = $this->_get($path);
 884
 885         $cr = new Zend_Rest_Client_Result($response->getBody());
 886
 887         if ($returnResult === true)
 888             return $cr;
 889
 890         if (!empty($cr->request)) {
 891             return false;
 892         }
 893
 894         return true;
 895     }
 896
 897     /**
 898      * Returns an array of user objects that the authenticating user is blocking
 899      *
 900      * @param integer $page         Optional. Specifies the page number of the results beginning at 1. A single page contains 20 ids.
 901      * @param boolean $returnUserIds  Optional. Returns only the userid's instead of the whole user object
 902      * @return Zend_Rest_Client_Result
 903      */
 904     public function blockBlocking($page = 1, $returnUserIds = false)
 905     {
 906         $this->_init();
 907         $path = '/1/blocks/blocking';
 908         if ($returnUserIds === true) {
 909             $path .= '/ids';
 910         }
 911         $path .= '.xml';
 912         $response = $this->_get($path, array('page' => $page));
 913         return new Zend_Rest_Client_Result($response->getBody());
 914     }
 915
 916     /**
 917      * Protected function to validate that the integer is valid or return a 0
 918      * @param $int
 919      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
 920      * @return integer
 921      */
 922     protected function _validInteger($int)
 923     {
 924         if (preg_match("/(\d+)/", $int)) {
 925             return $int;
 926         }
 927         return 0;
 928     }
 929
 930     /**
 931      * Validate a screen name using Twitter rules
 932      *
 933      * @param string $name
 934      * @throws Zend_Service_Twitter_Exception
 935      * @return string
 936      */
 937     protected function _validateScreenName($name)
 938     {
 939         if (!preg_match('/^[a-zA-Z0-9_]{0,20}$/', $name)) {
 940             require_once 'Zend/Service/Twitter/Exception.php';
 941             throw new Zend_Service_Twitter_Exception(
 942                 'Screen name, "' . $name
 943                 . '" should only contain alphanumeric characters and'
 944                 . ' underscores, and not exceed 15 characters.');
 945         }
 946         return $name;
 947     }
 948
 949     /**
 950      * Call a remote REST web service URI and return the Zend_Http_Response object
 951      *
 952      * @param  string $path            The path to append to the URI
 953      * @throws Zend_Rest_Client_Exception
 954      * @return void
 955      */
 956     protected function _prepare($path)
 957     {
 958         // Get the URI object and configure it
 959         if (!$this->_uri instanceof Zend_Uri_Http) {
 960             require_once 'Zend/Rest/Client/Exception.php';
 961             throw new Zend_Rest_Client_Exception(
 962                 'URI object must be set before performing call'
 963             );
 964         }
 965
 966         $uri = $this->_uri->getUri();
 967
 968         if ($path[0] != '/' && $uri[strlen($uri) - 1] != '/') {
 969             $path = '/' . $path;
 970         }
 971
 972         $this->_uri->setPath($path);
 973
 974         /**
 975          * Get the HTTP client and configure it for the endpoint URI.
 976          * Do this each time because the Zend_Http_Client instance is shared
 977          * among all Zend_Service_Abstract subclasses.
 978          */
 979         $this->_localHttpClient->resetParameters()->setUri((string) $this->_uri);
 980     }
 981
 982     /**
 983      * Performs an HTTP GET request to the $path.
 984      *
 985      * @param string $path
 986      * @param array  $query Array of GET parameters
 987      * @throws Zend_Http_Client_Exception
 988      * @return Zend_Http_Response
 989      */
 990     protected function _get($path, array $query = null)
 991     {
 992         $this->_prepare($path);
 993         $this->_localHttpClient->setParameterGet($query);
 994         return $this->_localHttpClient->request(Zend_Http_Client::GET);
 995     }
 996
 997     /**
 998      * Performs an HTTP POST request to $path.
 999      *
1000      * @param string $path
1001      * @param mixed $data Raw data to send
1002      * @throws Zend_Http_Client_Exception
1003      * @return Zend_Http_Response
1004      */
1005     protected function _post($path, $data = null)
1006     {
1007         $this->_prepare($path);
1008         return $this->_performPost(Zend_Http_Client::POST, $data);
1009     }
1010
1011     /**
1012      * Perform a POST or PUT
1013      *
1014      * Performs a POST or PUT request. Any data provided is set in the HTTP
1015      * client. String data is pushed in as raw POST data; array or object data
1016      * is pushed in as POST parameters.
1017      *
1018      * @param mixed $method
1019      * @param mixed $data
1020      * @return Zend_Http_Response
1021      */
1022     protected function _performPost($method, $data = null)
1023     {
1024         $client = $this->_localHttpClient;
1025         if (is_string($data)) {
1026             $client->setRawData($data);
1027         } elseif (is_array($data) || is_object($data)) {
1028             $client->setParameterPost((array) $data);
1029         }
1030         return $client->request($method);
1031     }
1032
1033 }