Source for file object.php

Documentation is available at object.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  Twitter
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die();
  11.  
  12. /**
  13.  * Twitter API object class for the Joomla Platform.
  14.  *
  15.  * @package     Joomla.Platform
  16.  * @subpackage  Twitter
  17.  * @since       12.3
  18.  */
  19. abstract class JTwitterObject
  20. {
  21.     /**
  22.      * @var    JRegistry  Options for the Twitter object.
  23.      * @since  12.3
  24.      */
  25.     protected $options;
  26.  
  27.     /**
  28.      * @var    JHttp  The HTTP client object to use in sending HTTP requests.
  29.      * @since  12.3
  30.      */
  31.     protected $client;
  32.  
  33.     /**
  34.      * @var    JTwitterOAuth The OAuth client.
  35.      * @since  12.3
  36.      */
  37.     protected $oauth;
  38.  
  39.     /**
  40.      * Constructor.
  41.      *
  42.      * @param   JRegistry      &$options  Twitter options object.
  43.      * @param   JHttp          $client    The HTTP client object.
  44.      * @param   JTwitterOAuth  $oauth     The OAuth client.
  45.      *
  46.      * @since   12.3
  47.      */
  48.     public function __construct(JRegistry &$options = null, JHttp $client = null, JTwitterOAuth $oauth = null)
  49.     {
  50.         $this->options = isset($options) ? $options : new JRegistry;
  51.         $this->client = isset($client) ? $client : new JHttp($this->options);
  52.         $this->oauth = $oauth;
  53.     }
  54.  
  55.     /**
  56.      * Method to check the rate limit for the requesting IP address
  57.      *
  58.      * @param   string  $resource  A resource or a comma-separated list of resource families you want to know the current rate limit disposition for.
  59.      * @param   string  $action    An action for the specified resource, if only one resource is specified.
  60.      *
  61.      * @return  void 
  62.      *
  63.      * @since   12.3
  64.      * @throws  RuntimeException
  65.      */
  66.     public function checkRateLimit($resource = null, $action = null)
  67.     {
  68.         // Check the rate limit for remaining hits
  69.         $rate_limit = $this->getRateLimit($resource);
  70.  
  71.         $property = '/' . $resource;
  72.  
  73.         if (!is_null($action))
  74.         {
  75.             $property .= '/' . $action;
  76.         }
  77.  
  78.         if ($rate_limit->resources->$resource->$property->remaining == 0)
  79.         {
  80.             // The IP has exceeded the Twitter API rate limit
  81.             throw new RuntimeException('This server has exceed the Twitter API rate limit for the given period.  The limit will reset at '
  82.                 . $rate_limit->resources->$resource->$property->reset
  83.             );
  84.         }
  85.     }
  86.  
  87.     /**
  88.      * Method to build and return a full request URL for the request.  This method will
  89.      * add appropriate pagination details if necessary and also prepend the API url
  90.      * to have a complete URL for the request.
  91.      *
  92.      * @param   string  $path        URL to inflect
  93.      * @param   array   $parameters  The parameters passed in the URL.
  94.      *
  95.      * @return  string  The request URL.
  96.      *
  97.      * @since   12.3
  98.      */
  99.     public function fetchUrl($path, $parameters = null)
  100.     {
  101.         if ($parameters)
  102.         {
  103.             foreach ($parameters as $key => $value)
  104.             {
  105.                 if (strpos($path, '?') === false)
  106.                 {
  107.                     $path .= '?' . $key . '=' . $value;
  108.                 }
  109.                 else
  110.                 {
  111.                     $path .= '&' . $key . '=' . $value;
  112.                 }
  113.             }
  114.         }
  115.  
  116.         // Get a new JUri object fousing the api url and given path.
  117.         if (strpos($path, 'http://search.twitter.com/search.json') === false)
  118.         {
  119.             $uri = new JUri($this->options->get('api.url') . $path);
  120.         }
  121.         else
  122.         {
  123.             $uri = new JUri($path);
  124.         }
  125.  
  126.         return (string) $uri;
  127.     }
  128.  
  129.     /**
  130.      * Method to retrieve the rate limit for the requesting IP address
  131.      *
  132.      * @param   string  $resource  A resource or a comma-separated list of resource families you want to know the current rate limit disposition for.
  133.      *
  134.      * @return  array  The JSON response decoded
  135.      *
  136.      * @since   12.3
  137.      */
  138.     public function getRateLimit($resource)
  139.     {
  140.         // Build the request path.
  141.         $path = '/application/rate_limit_status.json';
  142.  
  143.         if (!is_null($resource))
  144.         {
  145.             return $this->sendRequest($path, 'GET',  array('resources' => $resource));
  146.         }
  147.  
  148.         return $this->sendRequest($path);
  149.     }
  150.  
  151.     /**
  152.      * Method to send the request.
  153.      *
  154.      * @param   string  $path     The path of the request to make
  155.      * @param   string  $method   The request method.
  156.      * @param   mixed   $data     Either an associative array or a string to be sent with the post request.
  157.      * @param   array   $headers  An array of name-value pairs to include in the header of the request
  158.      *
  159.      * @return  array  The decoded JSON response
  160.      *
  161.      * @since   12.3
  162.      * @throws  RuntimeException
  163.      */
  164.     public function sendRequest($path, $method = 'GET', $data = array(), $headers = array())
  165.     {
  166.         // Get the access token.
  167.         $token = $this->oauth->getToken();
  168.  
  169.         // Set parameters.
  170.         $parameters['oauth_token'] = $token['key'];
  171.  
  172.         // Send the request.
  173.         $response = $this->oauth->oauthRequest($this->fetchUrl($path), $method, $parameters, $data, $headers);
  174.  
  175.         if (strpos($path, 'update_with_media') !== false)
  176.         {
  177.             // Check Media Rate Limit.
  178.             $response_headers = $response->headers;
  179.  
  180.             if ($response_headers['x-mediaratelimit-remaining'] == 0)
  181.             {
  182.                 // The IP has exceeded the Twitter API media rate limit
  183.                 throw new RuntimeException('This server has exceed the Twitter API media rate limit for the given period.  The limit will reset in '
  184.                     . $response_headers['x-mediaratelimit-reset'] . 'seconds.'
  185.                 );
  186.             }
  187.         }
  188.  
  189.         if (strpos($response->body, 'redirected') !== false)
  190.         {
  191.             return $response->headers['Location'];
  192.         }
  193.  
  194.         return json_decode($response->body);
  195.     }
  196.  
  197.     /**
  198.      * Get an option from the JTwitterObject instance.
  199.      *
  200.      * @param   string  $key  The name of the option to get.
  201.      *
  202.      * @return  mixed  The option value.
  203.      *
  204.      * @since   12.3
  205.      */
  206.     public function getOption($key)
  207.     {
  208.         return $this->options->get($key);
  209.     }
  210.  
  211.     /**
  212.      * Set an option for the JTwitterObject instance.
  213.      *
  214.      * @param   string  $key    The name of the option to set.
  215.      * @param   mixed   $value  The option value to set.
  216.      *
  217.      * @return  JTwitterObject  This object for method chaining.
  218.      *
  219.      * @since   12.3
  220.      */
  221.     public function setOption($key, $value)
  222.     {
  223.         $this->options->set($key, $value);
  224.  
  225.         return $this;
  226.     }
  227. }

Documentation generated on Tue, 19 Nov 2013 15:09:42 +0100 by phpDocumentor 1.4.3