File indexing completed on 2024-12-22 05:37:06

 <?php
 /**
  * Zend Framework
  *
  * LICENSE
  *
  * This source file is subject to the new BSD license that is bundled
  * with this package in the file LICENSE.txt.
  * It is also available through the world-wide-web at this URL:
  * http://framework.zend.com/license/new-bsd
  * If you did not receive a copy of the license and are unable to
  * obtain it through the world-wide-web, please send an email
  * to license@zend.com so we can send you a copy immediately.
  *
  * @category   Zend
  * @package    Zend_Service
  * @subpackage Twitter
  * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  * @version    $Id$
  */
 
 /**
  * @see Zend_Http_Client
  */
 // require_once 'Zend/Http/Client.php';
 
 /**
  * @see Zend_Http_CookieJar
  */
 // require_once 'Zend/Http/CookieJar.php';
 
 /**
  * @see Zend_Oauth_Consumer
  */
 // require_once 'Zend/Oauth/Consumer.php';
 
 /**
  * @see Zend_Oauth_Token_Access
  */
 // require_once 'Zend/Oauth/Token/Access.php';
 
 /**
  * @see Zend_Service_Twitter_Response
  */
 // require_once 'Zend/Service/Twitter/Response.php';
 
 /**
  * @category   Zend
  * @package    Zend_Service
  * @subpackage Twitter
  * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
 class Zend_Service_Twitter
 {
     /**
      * Base URI for all API calls
      */
     const API_BASE_URI = 'https://api.twitter.com/1.1/';
 
     /**
      * OAuth Endpoint
      */
     const OAUTH_BASE_URI = 'https://api.twitter.com/oauth';
 
     /**
      * 246 is the current limit for a status message, 140 characters are displayed
      * initially, with the remainder linked from the web UI or client. The limit is
      * applied to a html encoded UTF-8 string (i.e. entities are counted in the limit
      * which may appear unusual but is a security measure).
      *
      * This should be reviewed in the future...
      */
     const STATUS_MAX_CHARACTERS = 246;
 
     /**
      * @var array
      */
     protected $cookieJar;
 
     /**
      * Date format for 'since' strings
      *
      * @var string
      */
     protected $dateFormat = 'D, d M Y H:i:s T';
 
     /**
      * @var Zend_Http_Client
      */
     protected $httpClient = null;
 
     /**
      * Current method type (for method proxying)
      *
      * @var string
      */
     protected $methodType;
 
     /**
      * Oauth Consumer
      *
      * @var Zend_Oauth_Consumer
      */
     protected $oauthConsumer = null;
 
     /**
      * Types of API methods
      *
      * @var array
      */
     protected $methodTypes = array(
         'account',
         'application',
         'blocks',
         'directmessages',
         'favorites',
         'friendships',
         'search',
         'statuses',
         'users',
     );
 
     /**
      * Options passed to constructor
      *
      * @var array
      */
     protected $options = array();
 
     /**
      * Username
      *
      * @var string
      */
     protected $username;
 
     /**
      * Constructor
      *
      * @param  null|array|Zend_Config $options
      * @param  null|Zend_Oauth_Consumer $consumer
      * @param  null|Zend_Http_Client $httpClient
      */
     public function __construct($options = null, Zend_Oauth_Consumer $consumer = null, Zend_Http_Client $httpClient = null)
     {
         if ($options instanceof Zend_Config) {
             $options = $options->toArray();
         }
         if (!is_array($options)) {
             $options = array();
         }
 
         $this->options = $options;
 
         if (isset($options['username'])) {
             $this->setUsername($options['username']);
         }
 
         $accessToken = false;
         if (isset($options['accessToken'])) {
             $accessToken = $options['accessToken'];
         } elseif (isset($options['access_token'])) {
             $accessToken = $options['access_token'];
         }
 
         $oauthOptions = array();
         if (isset($options['oauthOptions'])) {
             $oauthOptions = $options['oauthOptions'];
         } elseif (isset($options['oauth_options'])) {
             $oauthOptions = $options['oauth_options'];
         }
         $oauthOptions['siteUrl'] = self::OAUTH_BASE_URI;
 
         $httpClientOptions = array();
         if (isset($options['httpClientOptions'])) {
             $httpClientOptions = $options['httpClientOptions'];
         } elseif (isset($options['http_client_options'])) {
             $httpClientOptions = $options['http_client_options'];
         }
 
         // If we have an OAuth access token, use the HTTP client it provides
         if ($accessToken && is_array($accessToken)
             && (isset($accessToken['token']) && isset($accessToken['secret']))
         ) {
             $token = new Zend_Oauth_Token_Access();
             $token->setToken($accessToken['token']);
             $token->setTokenSecret($accessToken['secret']);
             $accessToken = $token;
         }
         if ($accessToken && $accessToken instanceof Zend_Oauth_Token_Access) {
             $oauthOptions['token'] = $accessToken;
             $this->setHttpClient($accessToken->getHttpClient($oauthOptions, self::OAUTH_BASE_URI, $httpClientOptions));
             return;
         }
 
         // See if we were passed an http client
         if (isset($options['httpClient']) && null === $httpClient) {
             $httpClient = $options['httpClient'];
         } elseif (isset($options['http_client']) && null === $httpClient) {
             $httpClient = $options['http_client'];
         }
         if ($httpClient instanceof Zend_Http_Client) {
             $this->httpClient = $httpClient;
         } else {
             $this->setHttpClient(new Zend_Http_Client(null, $httpClientOptions));
         }
 
         // Set the OAuth consumer
         if ($consumer === null) {
             $consumer = new Zend_Oauth_Consumer($oauthOptions);
         }
         $this->oauthConsumer = $consumer;
     }
 
     /**
      * Proxy service methods
      *
      * @param  string $type
      * @return Twitter
      * @throws Exception\DomainException If method not in method types list
      */
     public function __get($type)
     {
         $type = strtolower($type);
         $type = str_replace('_', '', $type);
         if (!in_array($type, $this->methodTypes)) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Invalid method type "' . $type . '"'
             );
         }
         $this->methodType = $type;
         return $this;
     }
 
     /**
      * Method overloading
      *
      * @param  string $method
      * @param  array $params
      * @return mixed
      * @throws Exception\BadMethodCallException if unable to find method
      */
     public function __call($method, $params)
     {
         if (method_exists($this->oauthConsumer, $method)) {
             $return = call_user_func_array(array($this->oauthConsumer, $method), $params);
             if ($return instanceof Zend_Oauth_Token_Access) {
                 $this->setHttpClient($return->getHttpClient($this->options));
             }
             return $return;
         }
         if (empty($this->methodType)) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Invalid method "' . $method . '"'
             );
         }
 
         $test = str_replace('_', '', strtolower($method));
         $test = $this->methodType . $test;
         if (!method_exists($this, $test)) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Invalid method "' . $test . '"'
             );
         }
 
         return call_user_func_array(array($this, $test), $params);
     }
 
     /**
      * Set HTTP client
      *
      * @param Zend_Http_Client $client
      * @return self
      */
     public function setHttpClient(Zend_Http_Client $client)
     {
         $this->httpClient = $client;
         $this->httpClient->setHeaders(array('Accept-Charset' => 'ISO-8859-1,utf-8'));
         return $this;
     }
 
     /**
      * Get the HTTP client
      *
      * Lazy loads one if none present
      *
      * @return Zend_Http_Client
      */
     public function getHttpClient()
     {
         if (null === $this->httpClient) {
             $this->setHttpClient(new Zend_Http_Client());
         }
         return $this->httpClient;
     }
 
     /**
      * Retrieve username
      *
      * @return string
      */
     public function getUsername()
     {
         return $this->username;
     }
 
     /**
      * Set username
      *
      * @param  string $value
      * @return self
      */
     public function setUsername($value)
     {
         $this->username = $value;
         return $this;
     }
 
     /**
      * Checks for an authorised state
      *
      * @return bool
      */
     public function isAuthorised()
     {
         if ($this->getHttpClient() instanceof Zend_Oauth_Client) {
             return true;
         }
         return false;
     }
 
     /**
      * Verify Account Credentials
      *
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function accountVerifyCredentials()
     {
         $this->init();
         $response = $this->get('account/verify_credentials');
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Returns the number of api requests you have left per hour.
      *
      * @todo   Have a separate payload object to represent rate limits
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function applicationRateLimitStatus()
     {
         $this->init();
         $response = $this->get('application/rate_limit_status');
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Blocks the user specified in the ID parameter as the authenticating user.
      * Destroys a friendship to the blocked user if it exists.
      *
      * @param  integer|string $id       The ID or screen name of a user to block.
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function blocksCreate($id)
     {
         $this->init();
         $path     = 'blocks/create';
         $params   = $this->createUserParameter($id, array());
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Un-blocks the user specified in the ID parameter for the authenticating user
      *
      * @param  integer|string $id       The ID or screen_name of the user to un-block.
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function blocksDestroy($id)
     {
         $this->init();
         $path   = 'blocks/destroy';
         $params = $this->createUserParameter($id, array());
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Returns an array of user ids that the authenticating user is blocking
      *
      * @param  integer $cursor  Optional. Specifies the cursor position at which to begin listing ids; defaults to first "page" of results.
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function blocksIds($cursor = -1)
     {
         $this->init();
         $path = 'blocks/ids';
         $response = $this->get($path, array('cursor' => $cursor));
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Returns an array of user objects that the authenticating user is blocking
      *
      * @param  integer $cursor  Optional. Specifies the cursor position at which to begin listing ids; defaults to first "page" of results.
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function blocksList($cursor = -1)
     {
         $this->init();
         $path = 'blocks/list';
         $response = $this->get($path, array('cursor' => $cursor));
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Destroy a direct message
      *
      * @param  int $id ID of message to destroy
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function directMessagesDestroy($id)
     {
         $this->init();
         $path     = 'direct_messages/destroy';
         $params   = array('id' => $this->validInteger($id));
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Retrieve direct messages for the current user
      *
      * $options may include one or more of the following keys
      * - count: return page X of results
      * - since_id: return statuses only greater than the one specified
      * - max_id: return statuses with an ID less than (older than) or equal to that specified
      * - include_entities: setting to false will disable embedded entities
      * - skip_status:setting to true, "t", or 1 will omit the status in returned users
      *
      * @param  array $options
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function directMessagesMessages(array $options = array())
     {
         $this->init();
         $path   = 'direct_messages';
         $params = array();
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'count':
                     $params['count'] = (int) $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 case 'skip_status':
                     $params['skip_status'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Send a direct message to a user
      *
      * @param  int|string $user User to whom to send message
      * @param  string $text Message to send to user
      * @throws Exception\InvalidArgumentException if message is empty
      * @throws Exception\OutOfRangeException if message is too long
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function directMessagesNew($user, $text)
     {
         $this->init();
         $path = 'direct_messages/new';
 
         $len = iconv_strlen($text, 'UTF-8');
         if (0 == $len) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Direct message must contain at least one character'
             );
         } elseif (140 < $len) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Direct message must contain no more than 140 characters'
             );
         }
 
         $params         = $this->createUserParameter($user, array());
         $params['text'] = $text;
         $response       = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Retrieve list of direct messages sent by current user
      *
      * $options may include one or more of the following keys
      * - count: return page X of results
      * - page: return starting at page
      * - since_id: return statuses only greater than the one specified
      * - max_id: return statuses with an ID less than (older than) or equal to that specified
      * - include_entities: setting to false will disable embedded entities
      *
      * @param  array $options
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function directMessagesSent(array $options = array())
     {
         $this->init();
         $path   = 'direct_messages/sent';
         $params = array();
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'count':
                     $params['count'] = (int) $value;
                     break;
                 case 'page':
                     $params['page'] = (int) $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Mark a status as a favorite
      *
      * @param  int $id Status ID you want to mark as a favorite
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function favoritesCreate($id)
     {
         $this->init();
         $path     = 'favorites/create';
         $params   = array('id' => $this->validInteger($id));
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Remove a favorite
      *
      * @param  int $id Status ID you want to de-list as a favorite
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function favoritesDestroy($id)
     {
         $this->init();
         $path     = 'favorites/destroy';
         $params   = array('id' => $this->validInteger($id));
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Fetch favorites
      *
      * $options may contain one or more of the following:
      * - user_id: Id of a user for whom to fetch favorites
      * - screen_name: Screen name of a user for whom to fetch favorites
      * - count: number of tweets to attempt to retrieve, up to 200
      * - since_id: return results only after the specified tweet id
      * - max_id: return results with an ID less than (older than) or equal to the specified ID
      * - include_entities: when set to false, entities member will be omitted
      *
      * @param  array $params
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function favoritesList(array $options = array())
     {
         $this->init();
         $path = 'favorites/list';
         $params = array();
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'user_id':
                     $params['user_id'] = $this->validInteger($value);
                     break;
                 case 'screen_name':
                     $params['screen_name'] = $value;
                     break;
                 case 'count':
                     $params['count'] = (int) $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Create friendship
      *
      * @param  int|string $id User ID or name of new friend
      * @param  array $params Additional parameters to pass
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function friendshipsCreate($id, array $params = array())
     {
         $this->init();
         $path    = 'friendships/create';
         $params  = $this->createUserParameter($id, $params);
         $allowed = array(
             'user_id'     => null,
             'screen_name' => null,
             'follow'      => null,
         );
         $params = array_intersect_key($params, $allowed);
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Destroy friendship
      *
      * @param  int|string $id User ID or name of friend to remove
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function friendshipsDestroy($id)
     {
         $this->init();
         $path     = 'friendships/destroy';
         $params   = $this->createUserParameter($id, array());
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Search tweets
      *
      * $options may include any of the following:
      * - geocode: a string of the form "latitude, longitude, radius"
      * - lang: restrict tweets to the two-letter language code
      * - locale: query is in the given two-letter language code
      * - result_type: what type of results to receive: mixed, recent, or popular
      * - count: number of tweets to return per page; up to 100
      * - until: return tweets generated before the given date
      * - since_id: return resutls with an ID greater than (more recent than) the given ID
      * - max_id: return results with an ID less than (older than) the given ID
      * - include_entities: whether or not to include embedded entities
      *
      * @param  string $query
      * @param  array $options
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function searchTweets($query, array $options = array())
     {
         $this->init();
         $path = 'search/tweets';
 
         $len = iconv_strlen($query, 'UTF-8');
         if (0 == $len) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Query must contain at least one character'
             );
         }
 
         $params = array('q' => $query);
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'geocode':
                     if (!substr_count($value, ',') !== 2) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             '"geocode" must be of the format "latitude,longitude,radius"'
                         );
                     }
                     list($latitude, $longitude, $radius) = explode(',', $value);
                     $radius = trim($radius);
                     if (!preg_match('/^\d+(mi|km)$/', $radius)) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             'Radius segment of "geocode" must be of the format "[unit](mi|km)"'
                         );
                     }
                     $latitude  = (float) $latitude;
                     $longitude = (float) $longitude;
                     $params['geocode'] = $latitude . ',' . $longitude . ',' . $radius;
                     break;
                 case 'lang':
                     if (strlen($value) > 2) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             'Query language must be a 2 character string'
                         );
                     }
                     $params['lang'] = strtolower($value);
                     break;
                 case 'locale':
                     if (strlen($value) > 2) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             'Query locale must be a 2 character string'
                         );
                     }
                     $params['locale'] = strtolower($value);
                     break;
                 case 'result_type':
                     $value = strtolower($value);
                     if (!in_array($value, array('mixed', 'recent', 'popular'))) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             'result_type must be one of "mixed", "recent", or "popular"'
                         );
                     }
                     $params['result_type'] = $value;
                     break;
                 case 'count':
                     $value = (int) $value;
                     if (1 > $value || 100 < $value) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             'count must be between 1 and 100'
                         );
                     }
                     $params['count'] = $value;
                     break;
                 case 'until':
                     if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $value)) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             '"until" must be a date in the format YYYY-MM-DD'
                         );
                     }
                     $params['until'] = $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Destroy a status message
      *
      * @param  int $id ID of status to destroy
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesDestroy($id)
     {
         $this->init();
         $path = 'statuses/destroy/' . $this->validInteger($id);
         $response = $this->post($path);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Friend Timeline Status
      *
      * $options may include one or more of the following keys
      * - count: number of tweets to attempt to retrieve, up to 200
      * - since_id: return results only after the specified tweet id
      * - max_id: return results with an ID less than (older than) or equal to the specified ID
      * - trim_user: when set to true, "t", or 1, user object in tweets will include only author's ID.
      * - contributor_details: when set to true, includes screen_name of each contributor
      * - include_entities: when set to false, entities member will be omitted
      * - exclude_replies: when set to true, will strip replies appearing in the timeline
      *
      * @param  array $params
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesHomeTimeline(array $options = array())
     {
         $this->init();
         $path = 'statuses/home_timeline';
         $params = array();
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'count':
                     $params['count'] = (int) $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'trim_user':
                     if (in_array($value, array(true, 'true', 't', 1, '1'))) {
                         $value = true;
                     } else {
                         $value = false;
                     }
                     $params['trim_user'] = $value;
                     break;
                 case 'contributor_details:':
                     $params['contributor_details:'] = (bool) $value;
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 case 'exclude_replies':
                     $params['exclude_replies'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Get status replies
      *
      * $options may include one or more of the following keys
      * - count: number of tweets to attempt to retrieve, up to 200
      * - since_id: return results only after the specified tweet id
      * - max_id: return results with an ID less than (older than) or equal to the specified ID
      * - trim_user: when set to true, "t", or 1, user object in tweets will include only author's ID.
      * - contributor_details: when set to true, includes screen_name of each contributor
      * - include_entities: when set to false, entities member will be omitted
      *
      * @param  array $options
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesMentionsTimeline(array $options = array())
     {
         $this->init();
         $path   = 'statuses/mentions_timeline';
         $params = array();
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'count':
                     $params['count'] = (int) $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'trim_user':
                     if (in_array($value, array(true, 'true', 't', 1, '1'))) {
                         $value = true;
                     } else {
                         $value = false;
                     }
                     $params['trim_user'] = $value;
                     break;
                 case 'contributor_details:':
                     $params['contributor_details:'] = (bool) $value;
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Public Timeline status
      *
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesSample()
     {
         $this->init();
         $path = 'statuses/sample';
         $response = $this->get($path);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Show a single status
      *
      * @param  int $id Id of status to show
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesShow($id)
     {
         $this->init();
         $path = 'statuses/show/' . $this->validInteger($id);
         $response = $this->get($path);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Update user's current status
      *
      * @todo   Support additional parameters supported by statuses/update endpoint
      * @param  string $status
      * @param  null|int $inReplyToStatusId
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\OutOfRangeException if message is too long
      * @throws Exception\InvalidArgumentException if message is empty
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesUpdate($status, $inReplyToStatusId = null)
     {
         $this->init();
         $path = 'statuses/update';
         $len = iconv_strlen(htmlspecialchars($status, ENT_QUOTES, 'UTF-8'), 'UTF-8');
         if ($len > self::STATUS_MAX_CHARACTERS) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Status must be no more than '
                 . self::STATUS_MAX_CHARACTERS
                 . ' characters in length'
             );
         } elseif (0 == $len) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Status must contain at least one character'
             );
         }
 
         $params = array('status' => $status);
         $inReplyToStatusId = $this->validInteger($inReplyToStatusId);
         if ($inReplyToStatusId) {
             $params['in_reply_to_status_id'] = $inReplyToStatusId;
         }
         $response = $this->post($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * User Timeline status
      *
      * $options may include one or more of the following keys
      * - user_id: Id of a user for whom to fetch favorites
      * - screen_name: Screen name of a user for whom to fetch favorites
      * - count: number of tweets to attempt to retrieve, up to 200
      * - since_id: return results only after the specified tweet id
      * - max_id: return results with an ID less than (older than) or equal to the specified ID
      * - trim_user: when set to true, "t", or 1, user object in tweets will include only author's ID.
      * - exclude_replies: when set to true, will strip replies appearing in the timeline
      * - contributor_details: when set to true, includes screen_name of each contributor
      * - include_rts: when set to false, will strip native retweets
      *
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function statusesUserTimeline(array $options = array())
     {
         $this->init();
         $path = 'statuses/user_timeline';
         $params = array();
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'user_id':
                     $params['user_id'] = $this->validInteger($value);
                     break;
                 case 'screen_name':
                     $params['screen_name'] = $this->validateScreenName($value);
                     break;
                 case 'count':
                     $params['count'] = (int) $value;
                     break;
                 case 'since_id':
                     $params['since_id'] = $this->validInteger($value);
                     break;
                 case 'max_id':
                     $params['max_id'] = $this->validInteger($value);
                     break;
                 case 'trim_user':
                     if (in_array($value, array(true, 'true', 't', 1, '1'))) {
                         $value = true;
                     } else {
                         $value = false;
                     }
                     $params['trim_user'] = $value;
                     break;
                 case 'contributor_details:':
                     $params['contributor_details:'] = (bool) $value;
                     break;
                 case 'exclude_replies':
                     $params['exclude_replies'] = (bool) $value;
                     break;
                 case 'include_rts':
                     $params['include_rts'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Search users
      *
      * $options may include any of the following:
      * - page: the page of results to retrieve
      * - count: the number of users to retrieve per page; max is 20
      * - include_entities: if set to boolean true, include embedded entities
      *
      * @param  string $query
      * @param  array $options
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function usersSearch($query, array $options = array())
     {
         $this->init();
         $path = 'users/search';
 
         $len = iconv_strlen($query, 'UTF-8');
         if (0 == $len) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Query must contain at least one character'
             );
         }
 
         $params = array('q' => $query);
         foreach ($options as $key => $value) {
             switch (strtolower($key)) {
                 case 'count':
                     $value = (int) $value;
                     if (1 > $value || 20 < $value) {
                         // require_once 'Zend/Service/Twitter/Exception.php';
                         throw new Zend_Service_Twitter_Exception(
                             'count must be between 1 and 20'
                         );
                     }
                     $params['count'] = $value;
                     break;
                 case 'page':
                     $params['page'] = (int) $value;
                     break;
                 case 'include_entities':
                     $params['include_entities'] = (bool) $value;
                     break;
                 default:
                     break;
             }
         }
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
 
     /**
      * Show extended information on a user
      *
      * @param  int|string $id User ID or name
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      * @return Zend_Service_Twitter_Response
      */
     public function usersShow($id)
     {
         $this->init();
         $path     = 'users/show';
         $params   = $this->createUserParameter($id, array());
         $response = $this->get($path, $params);
         return new Zend_Service_Twitter_Response($response);
     }
 
     /**
      * Initialize HTTP authentication
      *
      * @return void
      * @throws Exception\DomainException if unauthorised
      */
     protected function init()
     {
         if (!$this->isAuthorised() && $this->getUsername() !== null) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Twitter session is unauthorised. You need to initialize '
                 . __CLASS__ . ' with an OAuth Access Token or use '
                 . 'its OAuth functionality to obtain an Access Token before '
                 . 'attempting any API actions that require authorisation'
             );
         }
         $client = $this->getHttpClient();
         $client->resetParameters();
         if (null === $this->cookieJar) {
             $cookieJar = $client->getCookieJar();
             if (null === $cookieJar) {
                 $cookieJar = new Zend_Http_CookieJar();
             }
             $this->cookieJar = $cookieJar;
             $this->cookieJar->reset();
         } else {
             $client->setCookieJar($this->cookieJar);
         }
     }
 
     /**
      * Protected function to validate that the integer is valid or return a 0
      *
      * @param  $int
      * @throws Zend_Http_Client_Exception if HTTP request fails or times out
      * @return integer
      */
     protected function validInteger($int)
     {
         if (preg_match("/(\d+)/", $int)) {
             return $int;
         }
         return 0;
     }
 
     /**
      * Validate a screen name using Twitter rules
      *
      * @param string $name
      * @return string
      * @throws Exception\InvalidArgumentException
      */
     protected function validateScreenName($name)
     {
         if (!preg_match('/^[a-zA-Z0-9_]{0,20}$/', $name)) {
             // require_once 'Zend/Service/Twitter/Exception.php';
             throw new Zend_Service_Twitter_Exception(
                 'Screen name, "' . $name
                 . '" should only contain alphanumeric characters and'
                 . ' underscores, and not exceed 15 characters.');
         }
         return $name;
     }
 
     /**
      * Call a remote REST web service URI
      *
      * @param  string $path The path to append to the URI
      * @param  Zend_Http_Client $client
      * @throws Zend_Http_Client_Exception
      * @return void
      */
     protected function prepare($path, Zend_Http_Client $client)
     {
         $client->setUri(self::API_BASE_URI . $path . '.json');
 
         /**
          * Do this each time to ensure oauth calls do not inject new params
          */
         $client->resetParameters();
     }
 
     /**
      * Performs an HTTP GET request to the $path.
      *
      * @param string $path
      * @param array  $query Array of GET parameters
      * @throws Zend_Http_Client_Exception
      * @return Zend_Http_Response
      */
     protected function get($path, array $query = array())
     {
         $client = $this->getHttpClient();
         $this->prepare($path, $client);
         $client->setParameterGet($query);
         $response = $client->request(Zend_Http_Client::GET);
         return $response;
     }
 
     /**
      * Performs an HTTP POST request to $path.
      *
      * @param string $path
      * @param mixed $data Raw data to send
      * @throws Zend_Http_Client_Exception
      * @return Zend_Http_Response
      */
     protected function post($path, $data = null)
     {
         $client = $this->getHttpClient();
         $this->prepare($path, $client);
         $response = $this->performPost(Zend_Http_Client::POST, $data, $client);
         return $response;
     }
 
     /**
      * Perform a POST or PUT
      *
      * Performs a POST or PUT request. Any data provided is set in the HTTP
      * client. String data is pushed in as raw POST data; array or object data
      * is pushed in as POST parameters.
      *
      * @param mixed $method
      * @param mixed $data
      * @return Zend_Http_Response
      */
     protected function performPost($method, $data, Zend_Http_Client $client)
     {
         if (is_string($data)) {
             $client->setRawData($data);
         } elseif (is_array($data) || is_object($data)) {
             $client->setParameterPost((array) $data);
         }
         return $client->request($method);
     }
 
     /**
      * Create a parameter representing the user
      *
      * Determines if $id is an integer, and, if so, sets the "user_id" parameter.
      * If not, assumes the $id is the "screen_name".
      *
      * @param  int|string $id
      * @param  array $params
      * @return array
      */
     protected function createUserParameter($id, array $params)
     {
         if ($this->validInteger($id)) {
             $params['user_id'] = $id;
             return $params;
         }
 
         $params['screen_name'] = $this->validateScreenName($id);
         return $params;
     }
 }