Services_Scribd
[ class tree: Services_Scribd ] [ index: Services_Scribd ] [ all elements ]

Source for file Common.php

Documentation is available at Common.php

  1. <?php
  2. /**
  3.  * Common logic for all of Scribd's API endpoints.
  4.  *
  5.  * PHP version 5.2.0+
  6.  *
  7.  * LICENSE: This source file is subject to the New BSD license that is
  8.  * available through the world-wide-web at the following URI:
  9.  * http://www.opensource.org/licenses/bsd-license.php. If you did not receive
  10.  * a copy of the New BSD License and are unable to obtain it through the web,
  11.  * please send a note to license@php.net so we can mail you a copy immediately.
  12.  *
  13.  * @category  Services
  14.  * @package   Services_Scribd
  15.  * @author    Rich Schumacher <rich.schu@gmail.com>
  16.  * @copyright 2009 Rich Schumacher <rich.schu@gmail.com>
  17.  * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
  18.  * @version   Release: 0.2.0
  19.  * @link      http://pear.php.net/package/Services_Scribd
  20.  */
  21.  
  22. require_once 'Services/Scribd.php';
  23. require_once 'HTTP/Request2.php';
  24.  
  25. /**
  26.  * This class contains common logic needed for all the API endpoints.  Handles
  27.  * tasks such as sending requests, signing the requests, etc.
  28.  *
  29.  * @category  Services
  30.  * @package   Services_Scribd
  31.  * @author    Rich Schumacher <rich.schu@gmail.com>
  32.  * @copyright 2009 Rich Schumacher <rich.schu@gmail.com>
  33.  * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
  34.  * @link      http://www.scribd.com/developers/platform
  35.  */
  36. {
  37.     /**
  38.      * An array of arguments to send to the API
  39.      *
  40.      * @var array 
  41.      */
  42.     protected $arguments = array();
  43.  
  44.     /**
  45.      * The Scribd account to use for requests
  46.      *
  47.      * @var Services_Scribd_Account 
  48.      */
  49.     protected $account = null;
  50.  
  51.     /**
  52.      * The HTTP request adapter to use
  53.      * 
  54.      * @var string|HTTP_Request2_Adapter
  55.      */
  56.     protected $requestAdapter = null;
  57.  
  58.     /**
  59.      * An array of arguments that we must skip when calculating the API
  60.      * signature
  61.      *
  62.      * @var array 
  63.      */
  64.     private $_skipSignatureArguments = array(
  65.         'file'
  66.     );
  67.  
  68.     /**
  69.      * Prevents calls from bubbling up to Serices_Scribd::_construct()
  70.      *
  71.      * @param Services_Scribd_Account $account The account to use
  72.      *
  73.      * @return void 
  74.      */
  75.     public function __construct(Services_Scribd_Account $account)
  76.     {
  77.         $this->account = $account;
  78.     }
  79.  
  80.     /**
  81.      * Returns an array of endpoints for this driver
  82.      *
  83.      * @return array 
  84.      */
  85.     public function getAvailableEndpoints()
  86.     {
  87.         return $this->validEndpoints;
  88.     }
  89.  
  90.     /**
  91.      * Traps any requests to endpoints that are not defined
  92.      *
  93.      * @param string $endpoint The invalid endpoint requested
  94.      * @param array  $params   Array of params for this endpoint
  95.      *
  96.      * @throws Services_Scribd_Exception
  97.      * @return null 
  98.      */
  99.     public function __call($endpointarray $params)
  100.     {
  101.         throw new Services_Scribd_Exception(
  102.             'Invalid endpoint requested: ' $endpoint
  103.         );
  104.     }
  105.  
  106.     /**
  107.      * Sets the request adapter to use for this request
  108.      * 
  109.      * @param HTTP_Request2_Adapter $adapter An instance of th adapter
  110.      * 
  111.      * @return void 
  112.      */
  113.     public function setRequestAdapter(HTTP_Request2_Adapter $adapter)
  114.     {
  115.         $this->requestAdapter = $adapter;
  116.     }
  117.  
  118.     /**
  119.      * Builds, sends, and returns the response for an API request
  120.      *
  121.      * Using curl, actually send the request to the Scribd API. Delegates to
  122.      * helper methods to format the arguments, send request, response, etc.
  123.      *
  124.      * @param string $endpoint The requested endpoint
  125.      * @param string $method   The HTTP method to use, defaults to GET
  126.      *
  127.      * @throws Services_Scribd_Exception
  128.      * @return mixed 
  129.      */
  130.     protected function call($endpoint$method = HTTP_Request2::METHOD_GET)
  131.     {
  132.         if ($method !== HTTP_Request2::METHOD_GET
  133.             && $method !== HTTP_Request2::METHOD_POST
  134.         {
  135.             throw new Services_Scribd_Exception('Invalid HTTP method: ' $method);
  136.         }
  137.  
  138.         $uri      $this->_buildRequestURI($endpoint$method);
  139.         $response $this->sendRequest($uri$method);
  140.  
  141.         $this->_reset();
  142.  
  143.         return $this->_formatResponse($response);
  144.     }
  145.  
  146.     /**
  147.      * Sends the request to the Scribd API
  148.      *
  149.      * @param string $uri    The API URI to request
  150.      * @param string $method The HTTP method to use
  151.      *
  152.      * @throws Services_Scribd_Exception
  153.      * @return void 
  154.      */
  155.     protected function sendRequest($uri$method)
  156.     {
  157.         $config = array(
  158.             'timeout' => $this->timeout
  159.         );
  160.  
  161.         $request = new HTTP_Request2($uri$method$config);
  162.         $request->setHeader('User-Agent''Services_Scribd-0.2.0');
  163.  
  164.         if ($this->requestAdapter !== null{
  165.             $request->setAdapter($this->requestAdapter);
  166.         }
  167.  
  168.         if ($method === HTTP_Request2::METHOD_POST{
  169.             if (array_key_exists('file'$this->arguments)) {
  170.                 $request->addUpload('file'$this->arguments['file']);
  171.                 unset($this->arguments['file']);
  172.             }
  173.             $request $request->addPostParameter($this->arguments);
  174.         }
  175.  
  176.         try {
  177.             $response $request->send();
  178.         catch (HTTP_Request2_Exception $e{
  179.             throw new Services_Scribd_Exception($e->getMessage()$e->getCode());
  180.         }
  181.  
  182.         if ($response->getStatus(!== 200{
  183.             throw new Services_Scribd_Exception(
  184.                 'Invalid response returned from server',
  185.                 $response->getStatus()
  186.             );
  187.         }
  188.  
  189.         return $response->getBody();
  190.     }
  191.  
  192.     /**
  193.      * Builds the API request URI
  194.      *
  195.      * Delegates the merging and request signing to more specific methods.
  196.      *
  197.      * @param string $endpoint The requested endpoint
  198.      * @param string $method   The HTTP method to use, defaults to GET
  199.      *
  200.      * @return string 
  201.      */
  202.     private function _buildRequestURI($endpoint$method)
  203.     {
  204.         $this->_mergeRequestArguments($endpoint);
  205.  
  206.         $this->_signRequest();
  207.  
  208.         if ($method === HTTP_Request2::METHOD_POST{
  209.             return Services_Scribd::API;
  210.         }
  211.  
  212.         $queryString http_build_query($this->arguments);
  213.  
  214.         return Services_Scribd::API . '?' $queryString;
  215.     }
  216.  
  217.     /**
  218.      * Merges required API arguments with request specific arguments
  219.      *
  220.      * @param string $endpoint The requested endpoint
  221.      *
  222.      * @return void 
  223.      */
  224.     private function _mergeRequestArguments($endpoint)
  225.     {
  226.         $requiredArguments = array(
  227.             'method'  => $endpoint,
  228.             'api_key' => $this->account->apiKey
  229.         );
  230.  
  231.         if ($this->account->apiSessionKey !== null{
  232.             $this->arguments['session_key'$this->account->apiSessionKey;
  233.         }
  234.  
  235.         if ($this->account->myUserId !== null{
  236.             $this->arguments['my_user_id'$this->account->myUserId;
  237.         }
  238.  
  239.         // Get rid of any nulls
  240.         $this->arguments = array_diff($this->argumentsarray(null));
  241.  
  242.         // ...and merge them with the required arguments
  243.         $this->arguments = array_merge($requiredArguments$this->arguments);
  244.     }
  245.  
  246.     /**
  247.      * Signs the request
  248.      *
  249.      * Generates an API signature if the Services_Scribd::$apiSecret variable
  250.      * has been set to help protect against evesdropping attacks.
  251.      *
  252.      * @link http://www.scribd.com/developers/platform#signing
  253.      * @see Services_Scribd::$apiSecret
  254.      * @return void 
  255.      */
  256.     private function _signRequest()
  257.     {
  258.         if ($this->account->apiSecret === null{
  259.             return;
  260.         }
  261.  
  262.         if (!empty($this->arguments['api_sig'])) {
  263.             unset($this->arguments['api_sig']);
  264.         }
  265.  
  266.         ksort($this->arguments);
  267.  
  268.         $apiSig = null;
  269.  
  270.         foreach ($this->arguments as $key => $value{
  271.             if (!in_array($key$this->_skipSignatureArguments)) {
  272.                 $apiSig .= $key $value;
  273.             }
  274.         }
  275.  
  276.         $this->arguments['api_sig'md5($this->account->apiSecret . $apiSig);
  277.     }
  278.  
  279.     /**
  280.      * Returns a SimpleXMLElement element from the raw XML response
  281.      *
  282.      * @param string $response The XML response from the API
  283.      *
  284.      * @throws Services_Scribd_Exception
  285.      * @return SimpleXMLElement 
  286.      */
  287.     private function _formatResponse($response)
  288.     {
  289.         libxml_use_internal_errors(true);
  290.         $xml simplexml_load_string($response);
  291.         if (!$xml instanceof SimpleXmlElement{
  292.             throw new Services_Scribd_Exception(
  293.                 'Could not parse XML response'
  294.             );
  295.         }
  296.  
  297.         if (string) $xml['stat'!== 'ok'{
  298.             $code    = (int) $xml->error['code'];
  299.             $message = (string) $xml->error['message'];
  300.             throw new Services_Scribd_Exception($message$code);
  301.         }
  302.  
  303.         return $xml;
  304.     }
  305.  
  306.     /**
  307.      * Performs any cleanup after the request has been sent
  308.      *
  309.      * @return void 
  310.      */
  311.     private function _reset()
  312.     {
  313.         $this->arguments = array();
  314.     }
  315. }
  316.  
  317. ?>

Documentation generated on Sat, 06 Apr 2013 14:30:03 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.