Source for file Caller.php

Documentation is available at Caller.php

  1. <?
  2.  
  3. /** Calls API methods using REST requests.
  4.  *
  5.  * @package    php-lastfm-api
  6.  * @author  Felix Bruns <felixbruns@web.de>
  7.  * @version    1.0
  8.  */
  9. abstract class Caller {
  10.     /** A Cache instance
  11.      *
  12.      * @var Cache 
  13.      * @access    protected
  14.      */
  15.     protected $cache;
  16.  
  17.     /** Last.fm API key
  18.      *
  19.      * @var string 
  20.      * @access    protected
  21.      */
  22.     protected $apiKey;
  23.  
  24.     /** Last.fm API secret
  25.      *
  26.      * @var string 
  27.      * @access    protected
  28.      */
  29.     protected $apiSecret;
  30.  
  31.     /** Last.fm API base URL
  32.      *
  33.      * @var string 
  34.      * @access    public
  35.      */
  36.     const API_URL = 'http://ws.audioscrobbler.com/2.0/';
  37.  
  38.     /** Get a Caller instance.
  39.      *
  40.      * @return    Caller    A Caller instance.
  41.      * @static
  42.      * @access    public
  43.      */
  44.     public abstract static function getInstance();
  45.  
  46.     /** Call an API method.
  47.      *
  48.      * @param    string    $method            API method to call. (Required)
  49.      * @param    array    $params            Request parameters to send. (Optional)
  50.      * @param    string    $requestMethod    Request-method for calling (defaults to 'GET'). (Optional)
  51.      * @return    SimpleXMLElement        A SimpleXMLElement object.
  52.      *
  53.      * @access    public
  54.      */
  55.     public function call($method, array $params = array(), $requestMethod = 'GET'){
  56.         /* Set call parameters */
  57.         $callParams = array(
  58.             'method'  => $method,
  59.             'api_key' => $this->apiKey
  60.         );
  61.  
  62.         /* Add call parameters to other request parameters */
  63.         $params = array_merge($callParams, $params);
  64.         $params = Util::toUTF8($params);
  65.  
  66.         /* Call API */
  67.         return $this->internalCall($params, $requestMethod);
  68.     }
  69.  
  70.     /** Call an API method which needs to be signed.
  71.      *
  72.      * @param    string    $method            API method to call. (Required)
  73.      * @param    array    $params            Request parameters to send. (Optional)
  74.      * @param    Session    $session        A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Optional)
  75.      * @param    string    $requestMethod    Request-method for calling (defaults to 'GET'). (Optional)
  76.      * @return    SimpleXMLElement        A SimpleXMLElement object.
  77.      *
  78.      * @access    public
  79.      */
  80.     public function signedCall($method, array $params = array(), $session = null,
  81.                                $requestMethod = 'GET'){
  82.         /* Set call parameters */
  83.         $callParams = array(
  84.             'method'  => $method,
  85.             'api_key' => $this->apiKey
  86.         );
  87.  
  88.         /* If session is set, add session key */
  89.         if($session != null){
  90.             $callParams['sk'] = $session->getKey();
  91.         }
  92.  
  93.         /* Add call parameters to other request parameters */
  94.         $params = array_merge($callParams, $params);
  95.         $params = Util::toUTF8($params);
  96.  
  97.         /* Add API signature */
  98.         $params['api_sig'] = Auth::getApiSignature($params, $this->apiSecret);
  99.  
  100.         /* Call API */
  101.         return $this->internalCall($params, $requestMethod);
  102.     }
  103.  
  104.     /** Send a query using a specified request-method.
  105.      *
  106.      * @param    string    $query            Query to send. (Required)
  107.      * @param    string    $requestMethod    Request-method for calling (defaults to 'GET'). (Optional)
  108.      * @return    SimpleXMLElement        A SimpleXMLElement object.
  109.      *
  110.      * @access    protected
  111.      * @internal
  112.      */
  113.     protected abstract function internalCall($params, $requestMethod = 'GET');
  114.  
  115.     /** Set the last.fm API key to be used.
  116.      *
  117.      * @param    string    $apiKey    A last.fm API key. (Required)
  118.      * @access    public
  119.      */
  120.     public function setApiKey($apiKey){
  121.         $this->apiKey = $apiKey;
  122.     }
  123.  
  124.     /** Get the last.fm API key which is used.
  125.      *
  126.      * @return    string    A last.fm API key.
  127.      * @access    public
  128.      */
  129.     public function getApiKey(){
  130.         return $this->apiKey;
  131.     }
  132.  
  133.     /** Set the last.fm API secret to be used.
  134.      *
  135.      * @param    string    $apiSecret    A last.fm API secret. (Required)
  136.      * @access    public
  137.      */
  138.     public function setApiSecret($apiSecret){
  139.         $this->apiSecret = $apiSecret;
  140.     }
  141.  
  142.     /** Get the last.fm API secret which is used.
  143.      *
  144.      * @return    string    A last.fm API secret.
  145.      * @access    public
  146.      */
  147.     public function getApiSecret(){
  148.         return $this->apiSecret;
  149.     }
  150.  
  151.     /** Sets the active {@link Cache} (null to disable caching).
  152.      *
  153.      * @param    Cache    $cache    A Cache object. (Required)
  154.      * @access    public
  155.      */
  156.     public function setCache($cache){
  157.         $this->cache = $cache;
  158.     }
  159.  
  160.     /** Get the current {@link Cache}.
  161.      *
  162.      * @return    Cache    A Cache object.
  163.      * @access    public
  164.      */
  165.     public function getCache(){
  166.         return $this->cache;
  167.     }
  168. }
  169.  
  170. ?>

Documentation generated on Mon, 22 Dec 2008 16:57:32 +0100 by phpDocumentor 1.4.1