library/Zend/Service/LiveDocx.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_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 }