[Summary view] [Print] [Text view]

   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 [email protected] so we can send you a copy immediately.
  14   *
  15   * @category   Zend
  16   * @package    Zend_Service
  17   * @subpackage LiveDocx
  18   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  19   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20   * @version    $Id$
  21   */
  22  
  23  /**
  24   * @category   Zend
  25   * @package    Zend_Service
  26   * @subpackage LiveDocx
  27   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  28   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  29   * @since      LiveDocx 1.0
  30   */
  31  class Zend_Service_LiveDocx
  32  {
  33      /**
  34       * LiveDocx service version
  35       * @since LiveDocx 1.0
  36       */
  37      const VERSION = '1.2';
  38  
  39      /**
  40       * SOAP client used to connect to LiveDocx service
  41       * @var   Zend_Soap_Client
  42       * @since LiveDocx 1.0
  43       */
  44      protected $_soapClient;
  45          
  46      /**
  47       * WSDL of LiveDocx web service
  48       * @var   string
  49       * @since LiveDocx 1.0
  50       */
  51      protected $_wsdl;
  52          
  53      /**
  54       * Array of credentials (username and password) to log into backend server
  55       * @var   array
  56       * @since LiveDocx 1.2
  57       */
  58      protected $_credentials;
  59      
  60      /**
  61       * Set to true, when session is logged into backend server
  62       * @var   boolean
  63       * @since LiveDocx 1.2
  64       */
  65      protected $_loggedIn;
  66      
  67      /**
  68       * Constructor
  69       *
  70       * Optionally, pass an array of options (or Zend_Config object).
  71       * 
  72       * If an option with the key 'soapClient' is provided, that value will be 
  73       * used to set the internal SOAP client used to connect to the LiveDocx
  74       * service.
  75       * 
  76       * Use 'soapClient' in the case that you have a dedicated or (locally
  77       * installed) licensed LiveDocx server. For example:
  78       *
  79       * {code}
  80       * $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge(
  81       *     array (
  82       *         'username'   => 'myUsername',
  83       *         'password'   => 'myPassword',
  84       *         'soapClient' => new Zend_Soap_Client('https://api.example.com/path/mailmerge.asmx?WSDL')
  85       *     )
  86       * );
  87       * {code}
  88       * 
  89       * Replace the URI of the WSDL in the constructor of Zend_Soap_Client with
  90       * that of your dedicated or licensed LiveDocx server.
  91       *
  92       * If you are using the public LiveDocx server, simply pass 'username' and
  93       * 'password'. For example:
  94       *
  95       * {code}
  96       * $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge(
  97       *     array (
  98       *         'username' => 'myUsername',
  99       *         'password' => 'myPassword'
 100       *     )
 101       * );
 102       * {code}
 103       * 
 104       * If you prefer to not pass the username and password through the
 105       * constructor, you can also call the following methods:
 106       * 
 107       * {code}
 108       * $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
 109       * 
 110       * $phpLiveDocx->setUsername('myUsername')
 111       *             ->setPassword('myPassword');
 112       * {/code}
 113       * 
 114       * Or, if you want to specify your own SoapClient:
 115       * 
 116       * {code}
 117       * $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
 118       * 
 119       * $phpLiveDocx->setUsername('myUsername')
 120       *             ->setPassword('myPassword');
 121       * 
 122       * $phpLiveDocx->setSoapClient(
 123       *     new Zend_Soap_Client('https://api.example.com/path/mailmerge.asmx?WSDL')
 124       * );
 125       * {/code} 
 126       *
 127       * @param  array|Zend_Config $options
 128       * @return void
 129       * @throws Zend_Service_LiveDocx_Exception
 130       * @since  LiveDocx 1.0
 131       */    
 132      public function __construct($options = null)
 133      {
 134          $this->_credentials = array();
 135          $this->_loggedIn = false;
 136          
 137          if ($options instanceof Zend_Config) {
 138              $options = $options->toArray();
 139          }
 140          
 141          if (is_array($options)) {
 142              $this->setOptions($options);
 143          }
 144      }
 145      
 146      /**
 147       * Set options
 148       * One or more of username, password, soapClient
 149       * 
 150       * @param  $options
 151       * @return Zend_Service_LiveDocx
 152       * @since  LiveDocx 1.2
 153       */
 154      public function setOptions(array $options)
 155      {
 156          foreach ($options as $key => $value) {
 157              $method = 'set' . $key;
 158              if (method_exists($this, $method)) {
 159                  $this->$method($value);
 160              }
 161          }
 162          
 163          return $this;
 164      }
 165          
 166      /**
 167       * Clean up and log out of LiveDocx service
 168       *
 169       * @return boolean
 170       * @since  LiveDocx 1.0
 171       */
 172      public function __destruct()
 173      {
 174          return $this->logOut();
 175      }
 176      
 177      /**
 178       * Init Soap client - connect to SOAP service
 179       *
 180       * @param  string $endpoint
 181       * @throws Zend_Service_LiveDocx_Exception
 182       * @return void
 183       * @since  LiveDocx 1.2
 184       */
 185      protected function _initSoapClient($endpoint)
 186      {
 187          try {
 188              require_once 'Zend/Soap/Client.php';
 189              $this->_soapClient = new Zend_Soap_Client();
 190              $this->_soapClient->setWsdl($endpoint);                
 191          } catch (Zend_Soap_Client_Exception $e) {
 192              require_once 'Zend/Service/LiveDocx/Exception.php';
 193              throw new Zend_Service_LiveDocx_Exception('Cannot connect to LiveDocx service at ' . $endpoint, 0, $e);
 194          }            
 195      }
 196      
 197      /**
 198       * Get SOAP client
 199       *
 200       * @return Zend_Soap_Client
 201       * @since  LiveDocx 1.2
 202       */
 203      public function getSoapClient()
 204      {
 205          return $this->_soapClient;
 206      }
 207      
 208      /**
 209       * Set SOAP client
 210       *
 211       * @param  Zend_Soap_Client $soapClient
 212       * @return Zend_Service_LiveDocx
 213       * @since  LiveDocx 1.2
 214       */
 215      public function setSoapClient(Zend_Soap_Client $soapClient)
 216      {
 217          $this->_soapClient = $soapClient;
 218          return $this;
 219      }
 220  
 221      /**
 222       * Log in to LiveDocx service
 223       *
 224       * @param string $username
 225       * @param string $password
 226       *
 227       * @throws Zend_Service_LiveDocx_Exception
 228       * @return boolean
 229       * @since  LiveDocx 1.2
 230       */
 231      public function logIn()
 232      {
 233          if (!$this->isLoggedIn()) {
 234              if (null === $this->getUsername()) {
 235                  require_once 'Zend/Service/LiveDocx/Exception.php';
 236                  throw new Zend_Service_LiveDocx_Exception(
 237                      'Username has not been set. To set username specify the options array in the constructor or call setUsername($username) after instantiation'
 238                  );
 239              }
 240              
 241              if (null === $this->getPassword()) {
 242                  require_once 'Zend/Service/LiveDocx/Exception.php';
 243                  throw new Zend_Service_LiveDocx_Exception(
 244                      'Password has not been set. To set password specify the options array in the constructor or call setPassword($password) after instantiation'
 245                  );
 246              }
 247              
 248              if (null === $this->getSoapClient()) {
 249                  $this->_initSoapClient($this->_wsdl);
 250              }            
 251              
 252              try {
 253                  $this->getSoapClient()->LogIn(array(
 254                      'username' => $this->getUsername(),
 255                      'password' => $this->getPassword(),
 256                  ));
 257                  $this->_loggedIn = true;
 258              } catch (Exception $e) {
 259                  require_once 'Zend/Service/LiveDocx/Exception.php';
 260                  throw new Zend_Service_LiveDocx_Exception(
 261                      'Cannot login into LiveDocx service - username and/or password are invalid', 0, $e
 262                  );
 263              }            
 264          }
 265          
 266          return $this->_loggedIn;
 267      }
 268  
 269      /**
 270       * Log out of the LiveDocx service
 271       *
 272       * @throws Zend_Service_LiveDocx_Exception
 273       * @return boolean
 274       * @since  LiveDocx 1.2
 275       */
 276      public function logOut()
 277      {
 278          if ($this->isLoggedIn()) {
 279              try {
 280                  $this->getSoapClient()->LogOut();
 281                  $this->_loggedIn = false;
 282              } catch (Exception $e) {
 283                  require_once 'Zend/Service/LiveDocx/Exception.php';
 284                  throw new Zend_Service_LiveDocx_Exception(
 285                      'Cannot log out of LiveDocx service', 0, $e
 286                  );
 287              }            
 288          }
 289          
 290          return $this->_loggedIn;
 291      }
 292      
 293      /**
 294       * Return true, if session is currently logged into the backend server
 295       * 
 296       * @return boolean
 297       * @since  LiveDocx 1.2
 298       */
 299      public function isLoggedIn()
 300      {
 301          return $this->_loggedIn;
 302      }
 303      
 304      /**
 305       * Set username
 306       * 
 307       * @return Zend_Service_LiveDocx
 308       * @since  LiveDocx 1.0
 309       */
 310      public function setUsername($username)
 311      {
 312          $this->_credentials['username'] = $username;
 313          return $this;
 314      }
 315      
 316      /**
 317       * Set password
 318       * 
 319       * @return Zend_Service_LiveDocx
 320       * @since  LiveDocx 1.0
 321       */    
 322      public function setPassword($password)
 323      {
 324          $this->_credentials['password'] = $password;
 325          return $this;
 326      }
 327  
 328      /**
 329       * Set WSDL of LiveDocx web service
 330       * 
 331       * @return Zend_Service_LiveDocx
 332       * @since  LiveDocx 1.0
 333       */      
 334      public function setWsdl($wsdl) 
 335      {
 336          $this->_wsdl = $wsdl;
 337          return $this;
 338      }
 339        
 340      /**
 341       * Return current username
 342       * 
 343       * @return string|null
 344       * @since  LiveDocx 1.0
 345       */
 346      public function getUsername()
 347      {
 348          if (isset($this->_credentials['username'])) {
 349              return $this->_credentials['username'];
 350          }
 351          
 352          return null;
 353      }
 354      
 355      /**
 356       * Return current password
 357       * 
 358       * @return string|null
 359       * @since  LiveDocx 1.0
 360       */    
 361      public function getPassword()
 362      {
 363          if (isset($this->_credentials['password'])) {
 364              return $this->_credentials['password'];
 365          }
 366          
 367          return null; 
 368      }
 369      
 370      /**
 371       * Return WSDL of LiveDocx web service
 372       * 
 373       * @return Zend_Service_LiveDocx
 374       * @since  LiveDocx 1.0
 375       */      
 376      public function getWsdl() 
 377      {
 378          return $this->_wsdl;
 379      }    
 380  
 381      /**
 382       * Return the document format (extension) of a filename
 383       *
 384       * @param  string $filename
 385       * @return string
 386       * @since  LiveDocx 1.0
 387       */
 388      public function getFormat($filename)
 389      {
 390          return strtolower(substr(strrchr($filename, '.'), 1));
 391      }
 392      
 393      /**
 394       * Return the current API version
 395       *
 396       * @return string
 397       * @since  LiveDocx 1.0
 398       */
 399      public function getVersion()
 400      {
 401          return self::VERSION;
 402      }
 403      
 404      /**
 405       * Compare the current API version with another version
 406       *
 407       * @param  string $version (STRING NOT FLOAT)
 408       * @return int -1 (version is less than API version), 0 (versions are equal), or 1 (version is greater than API version)
 409       * @since  LiveDocx 1.0
 410       */
 411      public function compareVersion($version)
 412      {
 413          return version_compare($version, $this->getVersion());
 414      }
 415  }