Zend/Gdata/Gapps/Extension/Login.php

   1 <?php
   2
   3 /**
   4  * Zend Framework
   5  *
   6  * LICENSE
   7  *
   8  * This source file is subject to the new BSD license that is bundled
   9  * with this package in the file LICENSE.txt.
  10  * It is also available through the world-wide-web at this URL:
  11  * http://framework.zend.com/license/new-bsd
  12  * If you did not receive a copy of the license and are unable to
  13  * obtain it through the world-wide-web, please send an email
  14  * to license@zend.com so we can send you a copy immediately.
  15  *
  16  * @category   Zend
  17  * @package    Zend_Gdata
  18  * @subpackage Gapps
  19  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  20  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21
  22  */
  23
  24 /**
  25  * @see Zend_Gdata_Extension
  26  */
  27 require_once 'Zend/Gdata/Extension.php';
  28
  29 /**
  30  * @see Zend_Gdata_Gapps
  31  */
  32 require_once 'Zend/Gdata/Gapps.php';
  33
  34 /**
  35  * Represents the apps:login element used by the Apps data API. This
  36  * class is used to describe properties of a user, and is usually contained
  37  * within instances of Zene_Gdata_Gapps_UserEntry or any other class
  38  * which is linked to a particular username.
  39  *
  40  * @category   Zend
  41  * @package    Zend_Gdata
  42  * @subpackage Gapps
  43  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  44  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  45  */
  46 class Zend_Gdata_Gapps_Extension_Login extends Zend_Gdata_Extension
  47 {
  48
  49     protected $_rootNamespace = 'apps';
  50     protected $_rootElement = 'login';
  51
  52     /**
  53      * The username for this user. This is used as the user's email address
  54      * and when logging in to Google Apps-hosted services.
  55      *
  56      * @var string
  57      */
  58     protected $_username = null;
  59
  60     /**
  61      * The password for the user. May be in cleartext or as an SHA-1
  62      * digest, depending on the value of _hashFunctionName.
  63      *
  64      * @var string
  65      */
  66     protected $_password = null;
  67
  68     /**
  69      * Specifies whether the password stored in _password is in cleartext
  70      * or is an SHA-1 digest of a password. If the password is cleartext,
  71      * then this should be null. If the password is an SHA-1 digest, then
  72      * this should be set to 'SHA-1'.
  73      *
  74      * At the time of writing, no other hash functions are supported
  75      *
  76      * @var string
  77      */
  78     protected $_hashFunctionName = null;
  79
  80     /**
  81      * True if the user has administrative rights for this domain, false
  82      * otherwise.
  83      *
  84      * @var boolean
  85      */
  86     protected $_admin = null;
  87
  88     /**
  89      * True if the user has agreed to the terms of service for Google Apps,
  90      * false otherwise.
  91      *
  92      * @var boolean.
  93      */
  94     protected $_agreedToTerms = null;
  95
  96     /**
  97      * True if this user has been suspended, false otherwise.
  98      *
  99      * @var boolean
 100      */
 101     protected $_suspended = null;
 102
 103     /**
 104      * True if the user will be required to change their password at
 105      * their next login, false otherwise.
 106      *
 107      * @var boolean
 108      */
 109     protected $_changePasswordAtNextLogin = null;
 110
 111     /**
 112      * Constructs a new Zend_Gdata_Gapps_Extension_Login object.
 113      *
 114      * @param string $username (optional) The username to be used for this
 115      *          login.
 116      * @param string $password (optional) The password to be used for this
 117      *          login.
 118      * @param string $hashFunctionName (optional) The name of the hash
 119      *          function used to protect the password, or null if no
 120      *          has function has been applied. As of this writing,
 121      *          the only valid values are 'SHA-1' or null.
 122      * @param boolean $admin (optional) Whether the user is an administrator
 123      *          or not.
 124      * @param boolean $suspended (optional) Whether this login is suspended or not.
 125      * @param boolean $changePasswordAtNextLogin (optional) Whether
 126      *          the user is required to change their password at their
 127      *          next login.
 128      * @param boolean $agreedToTerms (optional) Whether the user has
 129      *          agreed to the terms of service.
 130      */
 131     public function __construct($username = null, $password = null,
 132         $hashFunctionName = null, $admin = null, $suspended = null,
 133         $changePasswordAtNextLogin = null, $agreedToTerms = null)
 134     {
 135         $this->registerAllNamespaces(Zend_Gdata_Gapps::$namespaces);
 136         parent::__construct();
 137         $this->_username = $username;
 138         $this->_password = $password;
 139         $this->_hashFunctionName = $hashFunctionName;
 140         $this->_admin = $admin;
 141         $this->_agreedToTerms = $agreedToTerms;
 142         $this->_suspended = $suspended;
 143         $this->_changePasswordAtNextLogin = $changePasswordAtNextLogin;
 144     }
 145
 146     /**
 147      * Retrieves a DOMElement which corresponds to this element and all
 148      * child properties.  This is used to build an entry back into a DOM
 149      * and eventually XML text for sending to the server upon updates, or
 150      * for application storage/persistence.
 151      *
 152      * @param DOMDocument $doc The DOMDocument used to construct DOMElements
 153      * @return DOMElement The DOMElement representing this element and all
 154      * child properties.
 155      */
 156     public function getDOM($doc = null, $majorVersion = 1, $minorVersion = null)
 157     {
 158         $element = parent::getDOM($doc, $majorVersion, $minorVersion);
 159         if ($this->_username !== null) {
 160             $element->setAttribute('userName', $this->_username);
 161         }
 162         if ($this->_password !== null) {
 163             $element->setAttribute('password', $this->_password);
 164         }
 165         if ($this->_hashFunctionName !== null) {
 166             $element->setAttribute('hashFunctionName', $this->_hashFunctionName);
 167         }
 168         if ($this->_admin !== null) {
 169             $element->setAttribute('admin', ($this->_admin ? "true" : "false"));
 170         }
 171         if ($this->_agreedToTerms !== null) {
 172             $element->setAttribute('agreedToTerms', ($this->_agreedToTerms ? "true" : "false"));
 173         }
 174         if ($this->_suspended !== null) {
 175             $element->setAttribute('suspended', ($this->_suspended ? "true" : "false"));
 176         }
 177         if ($this->_changePasswordAtNextLogin !== null) {
 178             $element->setAttribute('changePasswordAtNextLogin', ($this->_changePasswordAtNextLogin ? "true" : "false"));
 179         }
 180
 181         return $element;
 182     }
 183
 184     /**
 185      * Given a DOMNode representing an attribute, tries to map the data into
 186      * instance members.  If no mapping is defined, the name and value are
 187      * stored in an array.
 188      *
 189      * @param DOMNode $attribute The DOMNode attribute needed to be handled
 190      * @throws Zend_Gdata_App_InvalidArgumentException
 191      */
 192     protected function takeAttributeFromDOM($attribute)
 193     {
 194         switch ($attribute->localName) {
 195         case 'userName':
 196             $this->_username = $attribute->nodeValue;
 197             break;
 198         case 'password':
 199             $this->_password = $attribute->nodeValue;
 200             break;
 201         case 'hashFunctionName':
 202             $this->_hashFunctionName = $attribute->nodeValue;
 203             break;
 204         case 'admin':
 205             if ($attribute->nodeValue == "true") {
 206                 $this->_admin = true;
 207             }
 208             else if ($attribute->nodeValue == "false") {
 209                 $this->_admin = false;
 210             }
 211             else {
 212                 require_once('Zend/Gdata/App/InvalidArgumentException.php');
 213                 throw new Zend_Gdata_App_InvalidArgumentException("Expected 'true' or 'false' for apps:login#admin.");
 214             }
 215             break;
 216         case 'agreedToTerms':
 217             if ($attribute->nodeValue == "true") {
 218                 $this->_agreedToTerms = true;
 219             }
 220             else if ($attribute->nodeValue == "false") {
 221                 $this->_agreedToTerms = false;
 222             }
 223             else {
 224                 require_once('Zend/Gdata/App/InvalidArgumentException.php');
 225                 throw new Zend_Gdata_App_InvalidArgumentException("Expected 'true' or 'false' for apps:login#agreedToTerms.");
 226             }
 227             break;
 228         case 'suspended':
 229             if ($attribute->nodeValue == "true") {
 230                 $this->_suspended = true;
 231             }
 232             else if ($attribute->nodeValue == "false") {
 233                 $this->_suspended = false;
 234             }
 235             else {
 236                 require_once('Zend/Gdata/App/InvalidArgumentException.php');
 237                 throw new Zend_Gdata_App_InvalidArgumentException("Expected 'true' or 'false' for apps:login#suspended.");
 238             }
 239             break;
 240         case 'changePasswordAtNextLogin':
 241             if ($attribute->nodeValue == "true") {
 242                 $this->_changePasswordAtNextLogin = true;
 243             }
 244             else if ($attribute->nodeValue == "false") {
 245                 $this->_changePasswordAtNextLogin = false;
 246             }
 247             else {
 248                 require_once('Zend/Gdata/App/InvalidArgumentException.php');
 249                 throw new Zend_Gdata_App_InvalidArgumentException("Expected 'true' or 'false' for apps:login#changePasswordAtNextLogin.");
 250             }
 251             break;
 252         default:
 253             parent::takeAttributeFromDOM($attribute);
 254         }
 255     }
 256
 257     /**
 258      * Get the value for this element's username attribute.
 259      *
 260      * @see setUsername
 261      * @return string The attribute being modified.
 262      */
 263     public function getUsername()
 264     {
 265         return $this->_username;
 266     }
 267
 268     /**
 269      * Set the value for this element's username attribute. This string
 270      * is used to uniquely identify the user in this domian and is used
 271      * to form this user's email address.
 272      *
 273      * @param string $value The desired value for this attribute.
 274      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 275      */
 276     public function setUsername($value)
 277     {
 278         $this->_username = $value;
 279         return $this;
 280     }
 281
 282     /**
 283      * Get the value for this element's password attribute.
 284      *
 285      * @see setPassword
 286      * @return string The requested attribute.
 287      */
 288     public function getPassword()
 289     {
 290         return $this->_password;
 291     }
 292
 293     /**
 294      * Set the value for this element's password attribute. As of this
 295      * writing, this can be either be provided as plaintext or hashed using
 296      * the SHA-1 algorithm for protection. If using a hash function,
 297      * this must be indicated by calling setHashFunctionName().
 298      *
 299      * @param string $value The desired value for this attribute.
 300      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 301      */
 302     public function setPassword($value)
 303     {
 304         $this->_password = $value;
 305         return $this;
 306     }
 307
 308     /**
 309      * Get the value for this element's hashFunctionName attribute.
 310      *
 311      * @see setHashFunctionName
 312      * @return string The requested attribute.
 313      */
 314     public function getHashFunctionName()
 315     {
 316         return $this->_hashFunctionName;
 317     }
 318
 319     /**
 320      * Set the value for this element's hashFunctionName attribute. This
 321      * indicates whether the password supplied with setPassword() is in
 322      * plaintext or has had a hash function applied to it. If null,
 323      * plaintext is assumed. As of this writing, the only valid hash
 324      * function is 'SHA-1'.
 325      *
 326      * @param string $value The desired value for this attribute.
 327      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 328      */
 329     public function setHashFunctionName($value)
 330     {
 331         $this->_hashFunctionName = $value;
 332         return $this;
 333     }
 334
 335     /**
 336      * Get the value for this element's admin attribute.
 337      *
 338      * @see setAdmin
 339      * @return boolean The requested attribute.
 340      * @throws Zend_Gdata_App_InvalidArgumentException
 341      */
 342     public function getAdmin()
 343     {
 344         if (!(is_bool($this->_admin))) {
 345             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 346             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for admin.');
 347         }
 348         return $this->_admin;
 349     }
 350
 351     /**
 352      * Set the value for this element's admin attribute. This indicates
 353      * whether this user is an administrator for this domain.
 354      *
 355      * @param boolean $value The desired value for this attribute.
 356      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 357      * @throws Zend_Gdata_App_InvalidArgumentException
 358      */
 359     public function setAdmin($value)
 360     {
 361         if (!(is_bool($value))) {
 362             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 363             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for $value.');
 364         }
 365         $this->_admin = $value;
 366         return $this;
 367     }
 368
 369     /**
 370      * Get the value for this element's agreedToTerms attribute.
 371      *
 372      * @see setAgreedToTerms
 373      * @return boolean The requested attribute.
 374      * @throws Zend_Gdata_App_InvalidArgumentException
 375      */
 376     public function getAgreedToTerms()
 377     {
 378         if (!(is_bool($this->_agreedToTerms))) {
 379             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 380             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for agreedToTerms.');
 381         }
 382         return $this->_agreedToTerms;
 383     }
 384
 385     /**
 386      * Set the value for this element's agreedToTerms attribute. This
 387      * indicates whether this user has agreed to the terms of service.
 388      *
 389      * @param boolean $value The desired value for this attribute.
 390      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 391      * @throws Zend_Gdata_App_InvalidArgumentException
 392      */
 393     public function setAgreedToTerms($value)
 394     {
 395         if (!(is_bool($value))) {
 396             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 397             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for $value.');
 398         }
 399         $this->_agreedToTerms = $value;
 400         return $this;
 401     }
 402
 403     /**
 404      * Get the value for this element's suspended attribute.
 405      *
 406      * @see setSuspended
 407      * @return boolean The requested attribute.
 408      * @throws Zend_Gdata_App_InvalidArgumentException
 409      */
 410     public function getSuspended()
 411     {
 412         if (!(is_bool($this->_suspended))) {
 413             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 414             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for suspended.');
 415         }
 416         return $this->_suspended;
 417     }
 418
 419     /**
 420      * Set the value for this element's suspended attribute. If true, the
 421      * user will not be able to login to this domain until unsuspended.
 422      *
 423      * @param boolean $value The desired value for this attribute.
 424      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 425      * @throws Zend_Gdata_App_InvalidArgumentException
 426      */
 427     public function setSuspended($value)
 428     {
 429         if (!(is_bool($value))) {
 430             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 431             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for $value.');
 432         }
 433         $this->_suspended = $value;
 434         return $this;
 435     }
 436
 437     /**
 438      * Get the value for this element's changePasswordAtNextLogin attribute.
 439      *
 440      * @see setChangePasswordAtNextLogin
 441      * @return boolean The requested attribute.
 442      * @throws Zend_Gdata_App_InvalidArgumentException
 443      */
 444     public function getChangePasswordAtNextLogin()
 445     {
 446         if (!(is_bool($this->_changePasswordAtNextLogin))) {
 447             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 448             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for changePasswordAtNextLogin.');
 449         }
 450         return $this->_changePasswordAtNextLogin;
 451     }
 452
 453     /**
 454      * Set the value for this element's changePasswordAtNextLogin attribute.
 455      * If true, the user will be forced to set a new password the next
 456      * time they login.
 457      *
 458      * @param boolean $value The desired value for this attribute.
 459      * @return Zend_Gdata_Gapps_Extension_Login Provides a fluent interface.
 460      * @throws Zend_Gdata_App_InvalidArgumentException
 461      */
 462     public function setChangePasswordAtNextLogin($value)
 463     {
 464         if (!(is_bool($value))) {
 465             require_once('Zend/Gdata/App/InvalidArgumentException.php');
 466             throw new Zend_Gdata_App_InvalidArgumentException('Expected boolean for $value.');
 467         }
 468         $this->_changePasswordAtNextLogin = $value;
 469         return $this;
 470     }
 471
 472     /**
 473      * Magic toString method allows using this directly via echo
 474      * Works best in PHP >= 4.2.0
 475      */
 476     public function __toString()
 477     {
 478         return "Username: " . $this->getUsername() .
 479             "\nPassword: " . (($this->getPassword() === null) ? "NOT SET" : "SET") .
 480             "\nPassword Hash Function: " . $this->getHashFunctionName() .
 481             "\nAdministrator: " . ($this->getAdmin() ? "Yes" : "No") .
 482             "\nAgreed To Terms: " . ($this->getAgreedToTerms() ? "Yes" : "No") .
 483             "\nSuspended: " . ($this->getSuspended() ? "Yes" : "No");
 484     }
 485 }