Zend/Oauth/Token.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_Oauth
  17  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  18  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  19
  20  */
  21
  22 /** Zend_Oauth_Http_Utility */
  23 require_once 'Zend/Oauth/Http/Utility.php';
  24
  25 /**
  26  * @category   Zend
  27  * @package    Zend_Oauth
  28  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  29  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  30  */
  31 abstract class Zend_Oauth_Token
  32 {
  33     /**@+
  34      * Token constants
  35      */
  36     const TOKEN_PARAM_KEY                = 'oauth_token';
  37     const TOKEN_SECRET_PARAM_KEY         = 'oauth_token_secret';
  38     const TOKEN_PARAM_CALLBACK_CONFIRMED = 'oauth_callback_confirmed';
  39     /**@-*/
  40
  41     /**
  42      * Token parameters
  43      *
  44      * @var array
  45      */
  46     protected $_params = array();
  47
  48     /**
  49      * OAuth response object
  50      *
  51      * @var Zend_Http_Response
  52      */
  53     protected $_response = null;
  54
  55     /**
  56      * @var Zend_Oauth_Http_Utility
  57      */
  58     protected $_httpUtility = null;
  59
  60     /**
  61      * Constructor; basic setup for any Token subclass.
  62      *
  63      * @param  null|Zend_Http_Response $response
  64      * @param  null|Zend_Oauth_Http_Utility $utility
  65      * @return void
  66      */
  67     public function __construct(
  68         Zend_Http_Response $response = null,
  69         Zend_Oauth_Http_Utility $utility = null
  70     ) {
  71         if ($response !== null) {
  72             $this->_response = $response;
  73             $params = $this->_parseParameters($response);
  74             if (count($params) > 0) {
  75                 $this->setParams($params);
  76             }
  77         }
  78         if ($utility !== null) {
  79             $this->_httpUtility = $utility;
  80         } else {
  81             $this->_httpUtility = new Zend_Oauth_Http_Utility;
  82         }
  83     }
  84
  85     /**
  86      * Attempts to validate the Token parsed from the HTTP response - really
  87      * it's just very basic existence checks which are minimal.
  88      *
  89      * @return bool
  90      */
  91     public function isValid()
  92     {
  93         if (isset($this->_params[self::TOKEN_PARAM_KEY])
  94             && !empty($this->_params[self::TOKEN_PARAM_KEY])
  95             && isset($this->_params[self::TOKEN_SECRET_PARAM_KEY])
  96         ) {
  97             return true;
  98         }
  99         return false;
 100     }
 101
 102     /**
 103      * Return the HTTP response object used to initialise this instance.
 104      *
 105      * @return Zend_Http_Response
 106      */
 107     public function getResponse()
 108     {
 109         return $this->_response;
 110     }
 111
 112     /**
 113      * Sets the value for the this Token's secret which may be used when signing
 114      * requests with this Token.
 115      *
 116      * @param  string $secret
 117      * @return Zend_Oauth_Token
 118      */
 119     public function setTokenSecret($secret)
 120     {
 121         $this->setParam(self::TOKEN_SECRET_PARAM_KEY, $secret);
 122         return $this;
 123     }
 124
 125     /**
 126      * Retrieve this Token's secret which may be used when signing
 127      * requests with this Token.
 128      *
 129      * @return string
 130      */
 131     public function getTokenSecret()
 132     {
 133         return $this->getParam(self::TOKEN_SECRET_PARAM_KEY);
 134     }
 135
 136     /**
 137      * Sets the value for a parameter (e.g. token secret or other) and run
 138      * a simple filter to remove any trailing newlines.
 139      *
 140      * @param  string $key
 141      * @param  string $value
 142      * @return Zend_Oauth_Token
 143      */
 144     public function setParam($key, $value)
 145     {
 146         $this->_params[$key] = trim($value, "\n");
 147         return $this;
 148     }
 149
 150     /**
 151      * Sets the value for some parameters (e.g. token secret or other) and run
 152      * a simple filter to remove any trailing newlines.
 153      *
 154      * @param  array $params
 155      * @return Zend_Oauth_Token
 156      */
 157     public function setParams(array $params)
 158     {
 159         foreach ($params as $key=>$value) {
 160             $this->setParam($key, $value);
 161         }
 162         return $this;
 163     }
 164
 165     /**
 166      * Get the value for a parameter (e.g. token secret or other).
 167      *
 168      * @param  string $key
 169      * @return mixed
 170      */
 171     public function getParam($key)
 172     {
 173         if (isset($this->_params[$key])) {
 174             return $this->_params[$key];
 175         }
 176         return null;
 177     }
 178
 179     /**
 180      * Sets the value for a Token.
 181      *
 182      * @param  string $token
 183      * @return Zend_Oauth_Token
 184      */
 185     public function setToken($token)
 186     {
 187         $this->setParam(self::TOKEN_PARAM_KEY, $token);
 188         return $this;
 189     }
 190
 191     /**
 192      * Gets the value for a Token.
 193      *
 194      * @return string
 195      */
 196     public function getToken()
 197     {
 198         return $this->getParam(self::TOKEN_PARAM_KEY);
 199     }
 200
 201     /**
 202      * Generic accessor to enable access as public properties.
 203      *
 204      * @return string
 205      */
 206     public function __get($key)
 207     {
 208         return $this->getParam($key);
 209     }
 210
 211     /**
 212      * Generic mutator to enable access as public properties.
 213      *
 214      * @param  string $key
 215      * @param  string $value
 216      * @return void
 217      */
 218     public function __set($key, $value)
 219     {
 220         $this->setParam($key, $value);
 221     }
 222
 223     /**
 224      * Convert Token to a string, specifically a raw encoded query string.
 225      *
 226      * @return string
 227      */
 228     public function toString()
 229     {
 230         return $this->_httpUtility->toEncodedQueryString($this->_params);
 231     }
 232
 233     /**
 234      * Convert Token to a string, specifically a raw encoded query string.
 235      * Aliases to self::toString()
 236      *
 237      * @return string
 238      */
 239     public function __toString()
 240     {
 241         return $this->toString();
 242     }
 243
 244     /**
 245      * Parse a HTTP response body and collect returned parameters
 246      * as raw url decoded key-value pairs in an associative array.
 247      *
 248      * @param  Zend_Http_Response $response
 249      * @return array
 250      */
 251     protected function _parseParameters(Zend_Http_Response $response)
 252     {
 253         $params = array();
 254         $body   = $response->getBody();
 255         if (empty($body)) {
 256             return;
 257         }
 258
 259         // validate body based on acceptable characters...todo
 260         $parts = explode('&', $body);
 261         foreach ($parts as $kvpair) {
 262             $pair = explode('=', $kvpair);
 263             $params[rawurldecode($pair[0])] = rawurldecode($pair[1]);
 264         }
 265         return $params;
 266     }
 267
 268     /**
 269      * Limit serialisation stored data to the parameters
 270      */
 271     public function __sleep()
 272     {
 273         return array('_params');
 274     }
 275
 276     /**
 277      * After serialisation, re-instantiate a HTTP utility class for use
 278      */
 279     public function __wakeup()
 280     {
 281         if ($this->_httpUtility === null) {
 282             $this->_httpUtility = new Zend_Oauth_Http_Utility;
 283         }
 284     }
 285 }