| [ Index ] |
PHP Cross Reference of moodle-2.8 |
[Summary view] [Print] [Text view]
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 [email protected] 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 * @version $Id$ 22 */ 23 24 /** 25 * @see Zend_Gdata 26 */ 27 require_once 'Zend/Gdata.php'; 28 29 /** 30 * @see Zend_Gdata_Gapps_UserFeed 31 */ 32 require_once 'Zend/Gdata/Gapps/UserFeed.php'; 33 34 /** 35 * @see Zend_Gdata_Gapps_NicknameFeed 36 */ 37 require_once 'Zend/Gdata/Gapps/NicknameFeed.php'; 38 39 /** 40 * @see Zend_Gdata_Gapps_EmailListFeed 41 */ 42 require_once 'Zend/Gdata/Gapps/EmailListFeed.php'; 43 44 /** 45 * @see Zend_Gdata_Gapps_EmailListRecipientFeed 46 */ 47 require_once 'Zend/Gdata/Gapps/EmailListRecipientFeed.php'; 48 49 50 /** 51 * Service class for interacting with the Google Apps Provisioning API. 52 * 53 * Like other service classes in this module, this class provides access via 54 * an HTTP client to Google servers for working with entries and feeds. 55 * 56 * Because of the nature of this API, all access must occur over an 57 * authenticated connection. 58 * 59 * @link http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html 60 * 61 * @category Zend 62 * @package Zend_Gdata 63 * @subpackage Gapps 64 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 65 * @license http://framework.zend.com/license/new-bsd New BSD License 66 */ 67 class Zend_Gdata_Gapps extends Zend_Gdata 68 { 69 70 const APPS_BASE_FEED_URI = 'https://apps-apis.google.com/a/feeds'; 71 const AUTH_SERVICE_NAME = 'apps'; 72 73 /** 74 * Path to user feeds on the Google Apps server. 75 */ 76 const APPS_USER_PATH = '/user/2.0'; 77 78 /** 79 * Path to nickname feeds on the Google Apps server. 80 */ 81 const APPS_NICKNAME_PATH = '/nickname/2.0'; 82 83 /** 84 * Path to email list feeds on the Google Apps server. 85 */ 86 const APPS_EMAIL_LIST_PATH = '/emailList/2.0'; 87 88 /** 89 * Path to email list recipient feeds on the Google Apps server. 90 */ 91 const APPS_EMAIL_LIST_RECIPIENT_POSTFIX = '/recipient'; 92 93 /** 94 * The domain which is being administered via the Provisioning API. 95 * 96 * @var string 97 */ 98 protected $_domain = null; 99 100 /** 101 * Namespaces used for Zend_Gdata_Gapps 102 * 103 * @var array 104 */ 105 public static $namespaces = array( 106 array('apps', 'http://schemas.google.com/apps/2006', 1, 0) 107 ); 108 109 /** 110 * Create Gdata_Gapps object 111 * 112 * @param Zend_Http_Client $client (optional) The HTTP client to use when 113 * when communicating with the Google Apps servers. 114 * @param string $domain (optional) The Google Apps domain which is to be 115 * accessed. 116 * @param string $applicationId The identity of the app in the form of Company-AppName-Version 117 */ 118 public function __construct($client = null, $domain = null, $applicationId = 'MyCompany-MyApp-1.0') 119 { 120 $this->registerPackage('Zend_Gdata_Gapps'); 121 $this->registerPackage('Zend_Gdata_Gapps_Extension'); 122 parent::__construct($client, $applicationId); 123 $this->_httpClient->setParameterPost('service', self::AUTH_SERVICE_NAME); 124 $this->_domain = $domain; 125 } 126 127 /** 128 * Convert an exception to an ServiceException if an AppsForYourDomain 129 * XML document is contained within the original exception's HTTP 130 * response. If conversion fails, throw the original error. 131 * 132 * @param Zend_Gdata_Exception $e The exception to convert. 133 * @throws Zend_Gdata_Gapps_ServiceException 134 * @throws mixed 135 */ 136 public static function throwServiceExceptionIfDetected($e) { 137 // Check to make sure that there actually response! 138 // This can happen if the connection dies before the request 139 // completes. (See ZF-5949) 140 $response = $e->getResponse(); 141 if (!$response) { 142 require_once('Zend/Gdata/App/IOException.php'); 143 throw new Zend_Gdata_App_IOException('No HTTP response received (possible connection failure)'); 144 } 145 146 try { 147 // Check to see if there is an AppsForYourDomainErrors 148 // datastructure in the response. If so, convert it to 149 // an exception and throw it. 150 require_once 'Zend/Gdata/Gapps/ServiceException.php'; 151 $error = new Zend_Gdata_Gapps_ServiceException(); 152 $error->importFromString($response->getBody()); 153 throw $error; 154 } catch (Zend_Gdata_App_Exception $e2) { 155 // Unable to convert the response to a ServiceException, 156 // most likely because the server didn't return an 157 // AppsForYourDomainErrors document. Throw the original 158 // exception. 159 throw $e; 160 } 161 } 162 163 /** 164 * Imports a feed located at $uri. 165 * This method overrides the default behavior of Zend_Gdata_App, 166 * providing support for Zend_Gdata_Gapps_ServiceException. 167 * 168 * @param string $uri 169 * @param Zend_Http_Client $client (optional) The client used for 170 * communication 171 * @param string $className (optional) The class which is used as the 172 * return type 173 * @throws Zend_Gdata_App_Exception 174 * @throws Zend_Gdata_App_HttpException 175 * @throws Zend_Gdata_Gapps_ServiceException 176 * @return Zend_Gdata_App_Feed 177 */ 178 public static function import($uri, $client = null, $className='Zend_Gdata_App_Feed') 179 { 180 try { 181 return parent::import($uri, $client, $className); 182 } catch (Zend_Gdata_App_HttpException $e) { 183 self::throwServiceExceptionIfDetected($e); 184 } 185 } 186 187 /** 188 * GET a URI using client object. 189 * This method overrides the default behavior of Zend_Gdata_App, 190 * providing support for Zend_Gdata_Gapps_ServiceException. 191 * 192 * @param string $uri GET URI 193 * @param array $extraHeaders Extra headers to add to the request, as an 194 * array of string-based key/value pairs. 195 * @throws Zend_Gdata_App_HttpException 196 * @throws Zend_Gdata_Gapps_ServiceException 197 * @return Zend_Http_Response 198 */ 199 public function get($uri, $extraHeaders = array()) 200 { 201 try { 202 return parent::get($uri, $extraHeaders); 203 } catch (Zend_Gdata_App_HttpException $e) { 204 self::throwServiceExceptionIfDetected($e); 205 } 206 } 207 208 /** 209 * POST data with client object. 210 * This method overrides the default behavior of Zend_Gdata_App, 211 * providing support for Zend_Gdata_Gapps_ServiceException. 212 * 213 * @param mixed $data The Zend_Gdata_App_Entry or XML to post 214 * @param string $uri (optional) POST URI 215 * @param integer $remainingRedirects (optional) 216 * @param string $contentType Content-type of the data 217 * @param array $extraHaders Extra headers to add tot he request 218 * @return Zend_Http_Response 219 * @throws Zend_Gdata_App_HttpException 220 * @throws Zend_Gdata_App_InvalidArgumentException 221 * @throws Zend_Gdata_Gapps_ServiceException 222 */ 223 public function post($data, $uri = null, $remainingRedirects = null, 224 $contentType = null, $extraHeaders = null) 225 { 226 try { 227 return parent::post($data, $uri, $remainingRedirects, $contentType, $extraHeaders); 228 } catch (Zend_Gdata_App_HttpException $e) { 229 self::throwServiceExceptionIfDetected($e); 230 } 231 } 232 233 /** 234 * PUT data with client object 235 * This method overrides the default behavior of Zend_Gdata_App, 236 * providing support for Zend_Gdata_Gapps_ServiceException. 237 * 238 * @param mixed $data The Zend_Gdata_App_Entry or XML to post 239 * @param string $uri (optional) PUT URI 240 * @param integer $remainingRedirects (optional) 241 * @param string $contentType Content-type of the data 242 * @param array $extraHaders Extra headers to add tot he request 243 * @return Zend_Http_Response 244 * @throws Zend_Gdata_App_HttpException 245 * @throws Zend_Gdata_App_InvalidArgumentException 246 * @throws Zend_Gdata_Gapps_ServiceException 247 */ 248 public function put($data, $uri = null, $remainingRedirects = null, 249 $contentType = null, $extraHeaders = null) 250 { 251 try { 252 return parent::put($data, $uri, $remainingRedirects, $contentType, $extraHeaders); 253 } catch (Zend_Gdata_App_HttpException $e) { 254 self::throwServiceExceptionIfDetected($e); 255 } 256 } 257 258 /** 259 * DELETE entry with client object 260 * This method overrides the default behavior of Zend_Gdata_App, 261 * providing support for Zend_Gdata_Gapps_ServiceException. 262 * 263 * @param mixed $data The Zend_Gdata_App_Entry or URL to delete 264 * @param integer $remainingRedirects (optional) 265 * @return void 266 * @throws Zend_Gdata_App_HttpException 267 * @throws Zend_Gdata_App_InvalidArgumentException 268 * @throws Zend_Gdata_Gapps_ServiceException 269 */ 270 public function delete($data, $remainingRedirects = null) 271 { 272 try { 273 return parent::delete($data, $remainingRedirects); 274 } catch (Zend_Gdata_App_HttpException $e) { 275 self::throwServiceExceptionIfDetected($e); 276 } 277 } 278 279 /** 280 * Set domain for this service instance. This should be a fully qualified 281 * domain, such as 'foo.example.com'. 282 * 283 * This value is used when calculating URLs for retrieving and posting 284 * entries. If no value is specified, a URL will have to be manually 285 * constructed prior to using any methods which interact with the Google 286 * Apps provisioning service. 287 * 288 * @param string $value The domain to be used for this session. 289 */ 290 public function setDomain($value) 291 { 292 $this->_domain = $value; 293 } 294 295 /** 296 * Get domain for this service instance. This should be a fully qualified 297 * domain, such as 'foo.example.com'. If no domain is set, null will be 298 * returned. 299 * 300 * @return string The domain to be used for this session, or null if not 301 * set. 302 */ 303 public function getDomain() 304 { 305 return $this->_domain; 306 } 307 308 /** 309 * Returns the base URL used to access the Google Apps service, based 310 * on the current domain. The current domain can be temporarily 311 * overridden by providing a fully qualified domain as $domain. 312 * 313 * @param string $domain (optional) A fully-qualified domain to use 314 * instead of the default domain for this service instance. 315 * @throws Zend_Gdata_App_InvalidArgumentException 316 */ 317 public function getBaseUrl($domain = null) 318 { 319 if ($domain !== null) { 320 return self::APPS_BASE_FEED_URI . '/' . $domain; 321 } else if ($this->_domain !== null) { 322 return self::APPS_BASE_FEED_URI . '/' . $this->_domain; 323 } else { 324 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 325 throw new Zend_Gdata_App_InvalidArgumentException( 326 'Domain must be specified.'); 327 } 328 } 329 330 /** 331 * Retrieve a UserFeed containing multiple UserEntry objects. 332 * 333 * @param mixed $location (optional) The location for the feed, as a URL 334 * or Query. 335 * @return Zend_Gdata_Gapps_UserFeed 336 * @throws Zend_Gdata_App_Exception 337 * @throws Zend_Gdata_App_HttpException 338 * @throws Zend_Gdata_Gapps_ServiceException 339 */ 340 public function getUserFeed($location = null) 341 { 342 if ($location === null) { 343 $uri = $this->getBaseUrl() . self::APPS_USER_PATH; 344 } else if ($location instanceof Zend_Gdata_Query) { 345 $uri = $location->getQueryUrl(); 346 } else { 347 $uri = $location; 348 } 349 return parent::getFeed($uri, 'Zend_Gdata_Gapps_UserFeed'); 350 } 351 352 /** 353 * Retreive NicknameFeed object containing multiple NicknameEntry objects. 354 * 355 * @param mixed $location (optional) The location for the feed, as a URL 356 * or Query. 357 * @return Zend_Gdata_Gapps_NicknameFeed 358 * @throws Zend_Gdata_App_Exception 359 * @throws Zend_Gdata_App_HttpException 360 * @throws Zend_Gdata_Gapps_ServiceException 361 */ 362 public function getNicknameFeed($location = null) 363 { 364 if ($location === null) { 365 $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH; 366 } else if ($location instanceof Zend_Gdata_Query) { 367 $uri = $location->getQueryUrl(); 368 } else { 369 $uri = $location; 370 } 371 return parent::getFeed($uri, 'Zend_Gdata_Gapps_NicknameFeed'); 372 } 373 374 /** 375 * Retreive EmailListFeed object containing multiple EmailListEntry 376 * objects. 377 * 378 * @param mixed $location (optional) The location for the feed, as a URL 379 * or Query. 380 * @return Zend_Gdata_Gapps_EmailListFeed 381 * @throws Zend_Gdata_App_Exception 382 * @throws Zend_Gdata_App_HttpException 383 * @throws Zend_Gdata_Gapps_ServiceException 384 */ 385 public function getEmailListFeed($location = null) 386 { 387 if ($location === null) { 388 $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH; 389 } else if ($location instanceof Zend_Gdata_Query) { 390 $uri = $location->getQueryUrl(); 391 } else { 392 $uri = $location; 393 } 394 return parent::getFeed($uri, 'Zend_Gdata_Gapps_EmailListFeed'); 395 } 396 397 /** 398 * Retreive EmailListRecipientFeed object containing multiple 399 * EmailListRecipientEntry objects. 400 * 401 * @param mixed $location The location for the feed, as a URL or Query. 402 * @return Zend_Gdata_Gapps_EmailListRecipientFeed 403 * @throws Zend_Gdata_App_Exception 404 * @throws Zend_Gdata_App_HttpException 405 * @throws Zend_Gdata_Gapps_ServiceException 406 */ 407 public function getEmailListRecipientFeed($location) 408 { 409 if ($location === null) { 410 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 411 throw new Zend_Gdata_App_InvalidArgumentException( 412 'Location must not be null'); 413 } else if ($location instanceof Zend_Gdata_Query) { 414 $uri = $location->getQueryUrl(); 415 } else { 416 $uri = $location; 417 } 418 return parent::getFeed($uri, 'Zend_Gdata_Gapps_EmailListRecipientFeed'); 419 } 420 421 /** 422 * Retreive a single UserEntry object. 423 * 424 * @param mixed $location The location for the feed, as a URL or Query. 425 * @return Zend_Gdata_Gapps_UserEntry 426 * @throws Zend_Gdata_App_Exception 427 * @throws Zend_Gdata_App_HttpException 428 * @throws Zend_Gdata_Gapps_ServiceException 429 */ 430 public function getUserEntry($location) 431 { 432 if ($location === null) { 433 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 434 throw new Zend_Gdata_App_InvalidArgumentException( 435 'Location must not be null'); 436 } else if ($location instanceof Zend_Gdata_Query) { 437 $uri = $location->getQueryUrl(); 438 } else { 439 $uri = $location; 440 } 441 return parent::getEntry($uri, 'Zend_Gdata_Gapps_UserEntry'); 442 } 443 444 /** 445 * Retreive a single NicknameEntry object. 446 * 447 * @param mixed $location The location for the feed, as a URL or Query. 448 * @return Zend_Gdata_Gapps_NicknameEntry 449 * @throws Zend_Gdata_App_Exception 450 * @throws Zend_Gdata_App_HttpException 451 * @throws Zend_Gdata_Gapps_ServiceException 452 */ 453 public function getNicknameEntry($location) 454 { 455 if ($location === null) { 456 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 457 throw new Zend_Gdata_App_InvalidArgumentException( 458 'Location must not be null'); 459 } else if ($location instanceof Zend_Gdata_Query) { 460 $uri = $location->getQueryUrl(); 461 } else { 462 $uri = $location; 463 } 464 return parent::getEntry($uri, 'Zend_Gdata_Gapps_NicknameEntry'); 465 } 466 467 /** 468 * Retreive a single EmailListEntry object. 469 * 470 * @param mixed $location The location for the feed, as a URL or Query. 471 * @return Zend_Gdata_Gapps_EmailListEntry 472 * @throws Zend_Gdata_App_Exception 473 * @throws Zend_Gdata_App_HttpException 474 * @throws Zend_Gdata_Gapps_ServiceException 475 */ 476 public function getEmailListEntry($location) 477 { 478 if ($location === null) { 479 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 480 throw new Zend_Gdata_App_InvalidArgumentException( 481 'Location must not be null'); 482 } else if ($location instanceof Zend_Gdata_Query) { 483 $uri = $location->getQueryUrl(); 484 } else { 485 $uri = $location; 486 } 487 return parent::getEntry($uri, 'Zend_Gdata_Gapps_EmailListEntry'); 488 } 489 490 /** 491 * Retreive a single EmailListRecipientEntry object. 492 * 493 * @param mixed $location The location for the feed, as a URL or Query. 494 * @return Zend_Gdata_Gapps_EmailListRecipientEntry 495 * @throws Zend_Gdata_App_Exception 496 * @throws Zend_Gdata_App_HttpException 497 * @throws Zend_Gdata_Gapps_ServiceException 498 */ 499 public function getEmailListRecipientEntry($location) 500 { 501 if ($location === null) { 502 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 503 throw new Zend_Gdata_App_InvalidArgumentException( 504 'Location must not be null'); 505 } else if ($location instanceof Zend_Gdata_Query) { 506 $uri = $location->getQueryUrl(); 507 } else { 508 $uri = $location; 509 } 510 return parent::getEntry($uri, 'Zend_Gdata_Gapps_EmailListRecipientEntry'); 511 } 512 513 /** 514 * Create a new user from a UserEntry. 515 * 516 * @param Zend_Gdata_Gapps_UserEntry $user The user entry to insert. 517 * @param string $uri (optional) The URI where the user should be 518 * uploaded to. If null, the default user creation URI for 519 * this domain will be used. 520 * @return Zend_Gdata_Gapps_UserEntry The inserted user entry as 521 * returned by the server. 522 * @throws Zend_Gdata_App_Exception 523 * @throws Zend_Gdata_App_HttpException 524 * @throws Zend_Gdata_Gapps_ServiceException 525 */ 526 public function insertUser($user, $uri = null) 527 { 528 if ($uri === null) { 529 $uri = $this->getBaseUrl() . self::APPS_USER_PATH; 530 } 531 $newEntry = $this->insertEntry($user, $uri, 'Zend_Gdata_Gapps_UserEntry'); 532 return $newEntry; 533 } 534 535 /** 536 * Create a new nickname from a NicknameEntry. 537 * 538 * @param Zend_Gdata_Gapps_NicknameEntry $nickname The nickname entry to 539 * insert. 540 * @param string $uri (optional) The URI where the nickname should be 541 * uploaded to. If null, the default nickname creation URI for 542 * this domain will be used. 543 * @return Zend_Gdata_Gapps_NicknameEntry The inserted nickname entry as 544 * returned by the server. 545 * @throws Zend_Gdata_App_Exception 546 * @throws Zend_Gdata_App_HttpException 547 * @throws Zend_Gdata_Gapps_ServiceException 548 */ 549 public function insertNickname($nickname, $uri = null) 550 { 551 if ($uri === null) { 552 $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH; 553 } 554 $newEntry = $this->insertEntry($nickname, $uri, 'Zend_Gdata_Gapps_NicknameEntry'); 555 return $newEntry; 556 } 557 558 /** 559 * Create a new email list from an EmailListEntry. 560 * 561 * @param Zend_Gdata_Gapps_EmailListEntry $emailList The email list entry 562 * to insert. 563 * @param string $uri (optional) The URI where the email list should be 564 * uploaded to. If null, the default email list creation URI for 565 * this domain will be used. 566 * @return Zend_Gdata_Gapps_EmailListEntry The inserted email list entry 567 * as returned by the server. 568 * @throws Zend_Gdata_App_Exception 569 * @throws Zend_Gdata_App_HttpException 570 * @throws Zend_Gdata_Gapps_ServiceException 571 */ 572 public function insertEmailList($emailList, $uri = null) 573 { 574 if ($uri === null) { 575 $uri = $this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH; 576 } 577 $newEntry = $this->insertEntry($emailList, $uri, 'Zend_Gdata_Gapps_EmailListEntry'); 578 return $newEntry; 579 } 580 581 /** 582 * Create a new email list recipient from an EmailListRecipientEntry. 583 * 584 * @param Zend_Gdata_Gapps_EmailListRecipientEntry $recipient The recipient 585 * entry to insert. 586 * @param string $uri (optional) The URI where the recipient should be 587 * uploaded to. If null, the default recipient creation URI for 588 * this domain will be used. 589 * @return Zend_Gdata_Gapps_EmailListRecipientEntry The inserted 590 * recipient entry as returned by the server. 591 * @throws Zend_Gdata_App_Exception 592 * @throws Zend_Gdata_App_HttpException 593 * @throws Zend_Gdata_Gapps_ServiceException 594 */ 595 public function insertEmailListRecipient($recipient, $uri = null) 596 { 597 if ($uri === null) { 598 require_once 'Zend/Gdata/App/InvalidArgumentException.php'; 599 throw new Zend_Gdata_App_InvalidArgumentException( 600 'URI must not be null'); 601 } elseif ($uri instanceof Zend_Gdata_Gapps_EmailListEntry) { 602 $uri = $uri->getLink('edit')->href; 603 } 604 $newEntry = $this->insertEntry($recipient, $uri, 'Zend_Gdata_Gapps_EmailListRecipientEntry'); 605 return $newEntry; 606 } 607 608 /** 609 * Provides a magic factory method to instantiate new objects with 610 * shorter syntax than would otherwise be required by the Zend Framework 611 * naming conventions. For more information, see Zend_Gdata_App::__call(). 612 * 613 * This overrides the default behavior of __call() so that query classes 614 * do not need to have their domain manually set when created with 615 * a magic factory method. 616 * 617 * @see Zend_Gdata_App::__call() 618 * @param string $method The method name being called 619 * @param array $args The arguments passed to the call 620 * @throws Zend_Gdata_App_Exception 621 */ 622 public function __call($method, $args) { 623 if (preg_match('/^new(\w+Query)/', $method, $matches)) { 624 $class = $matches[1]; 625 $foundClassName = null; 626 foreach ($this->_registeredPackages as $name) { 627 try { 628 // Autoloading disabled on next line for compatibility 629 // with magic factories. See ZF-6660. 630 if (!class_exists($name . '_' . $class, false)) { 631 require_once 'Zend/Loader.php'; 632 @Zend_Loader::loadClass($name . '_' . $class); 633 } 634 $foundClassName = $name . '_' . $class; 635 break; 636 } catch (Zend_Exception $e) { 637 // package wasn't here- continue searching 638 } 639 } 640 if ($foundClassName != null) { 641 $reflectionObj = new ReflectionClass($foundClassName); 642 // Prepend the domain to the query 643 $args = array_merge(array($this->getDomain()), $args); 644 return $reflectionObj->newInstanceArgs($args); 645 } else { 646 require_once 'Zend/Gdata/App/Exception.php'; 647 throw new Zend_Gdata_App_Exception( 648 "Unable to find '$class}' in registered packages"); 649 } 650 } else { 651 return parent::__call($method, $args); 652 } 653 654 } 655 656 // Convenience methods 657 // Specified at http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html#appendix_e 658 659 /** 660 * Create a new user entry and send it to the Google Apps servers. 661 * 662 * @param string $username The username for the new user. 663 * @param string $givenName The given name for the new user. 664 * @param string $familyName The family name for the new user. 665 * @param string $password The password for the new user as a plaintext string 666 * (if $passwordHashFunction is null) or a SHA-1 hashed 667 * value (if $passwordHashFunction = 'SHA-1'). 668 * @param string $quotaLimitInMB (optional) The quota limit for the new user in MB. 669 * @return Zend_Gdata_Gapps_UserEntry (optional) The new user entry as returned by 670 * server. 671 * @throws Zend_Gdata_App_Exception 672 * @throws Zend_Gdata_App_HttpException 673 * @throws Zend_Gdata_Gapps_ServiceException 674 */ 675 public function createUser ($username, $givenName, $familyName, $password, 676 $passwordHashFunction = null, $quotaLimitInMB = null) { 677 $user = $this->newUserEntry(); 678 $user->login = $this->newLogin(); 679 $user->login->username = $username; 680 $user->login->password = $password; 681 $user->login->hashFunctionName = $passwordHashFunction; 682 $user->name = $this->newName(); 683 $user->name->givenName = $givenName; 684 $user->name->familyName = $familyName; 685 if ($quotaLimitInMB !== null) { 686 $user->quota = $this->newQuota(); 687 $user->quota->limit = $quotaLimitInMB; 688 } 689 return $this->insertUser($user); 690 } 691 692 /** 693 * Retrieve a user based on their username. 694 * 695 * @param string $username The username to search for. 696 * @return Zend_Gdata_Gapps_UserEntry The username to search for, or null 697 * if no match found. 698 * @throws Zend_Gdata_App_InvalidArgumentException 699 * @throws Zend_Gdata_App_HttpException 700 */ 701 public function retrieveUser ($username) { 702 $query = $this->newUserQuery($username); 703 try { 704 $user = $this->getUserEntry($query); 705 } catch (Zend_Gdata_Gapps_ServiceException $e) { 706 // Set the user to null if not found 707 if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) { 708 $user = null; 709 } else { 710 throw $e; 711 } 712 } 713 return $user; 714 } 715 716 /** 717 * Retrieve a page of users in alphabetical order, starting with the 718 * provided username. 719 * 720 * @param string $startUsername (optional) The first username to retrieve. 721 * If null or not declared, the page will begin with the first 722 * user in the domain. 723 * @return Zend_Gdata_Gapps_UserFeed Collection of Zend_Gdata_UserEntry 724 * objects representing all users in the domain. 725 * @throws Zend_Gdata_App_Exception 726 * @throws Zend_Gdata_App_HttpException 727 * @throws Zend_Gdata_Gapps_ServiceException 728 */ 729 public function retrievePageOfUsers ($startUsername = null) { 730 $query = $this->newUserQuery(); 731 $query->setStartUsername($startUsername); 732 return $this->getUserFeed($query); 733 } 734 735 /** 736 * Retrieve all users in the current domain. Be aware that 737 * calling this function on a domain with many users will take a 738 * signifigant amount of time to complete. On larger domains this may 739 * may cause execution to timeout without proper precautions in place. 740 * 741 * @return Zend_Gdata_Gapps_UserFeed Collection of Zend_Gdata_UserEntry 742 * objects representing all users in the domain. 743 * @throws Zend_Gdata_App_Exception 744 * @throws Zend_Gdata_App_HttpException 745 * @throws Zend_Gdata_Gapps_ServiceException 746 */ 747 public function retrieveAllUsers () { 748 return $this->retrieveAllEntriesForFeed($this->retrievePageOfUsers()); 749 } 750 751 /** 752 * Overwrite a specified username with the provided UserEntry. The 753 * UserEntry does not need to contain an edit link. 754 * 755 * This method is provided for compliance with the Google Apps 756 * Provisioning API specification. Normally users will instead want to 757 * call UserEntry::save() instead. 758 * 759 * @see Zend_Gdata_App_Entry::save 760 * @param string $username The username whose data will be overwritten. 761 * @param Zend_Gdata_Gapps_UserEntry $userEntry The user entry which 762 * will be overwritten. 763 * @return Zend_Gdata_Gapps_UserEntry The UserEntry returned by the 764 * server. 765 * @throws Zend_Gdata_App_Exception 766 * @throws Zend_Gdata_App_HttpException 767 * @throws Zend_Gdata_Gapps_ServiceException 768 */ 769 public function updateUser($username, $userEntry) { 770 return $this->updateEntry($userEntry, $this->getBaseUrl() . 771 self::APPS_USER_PATH . '/' . $username); 772 } 773 774 /** 775 * Mark a given user as suspended. 776 * 777 * @param string $username The username associated with the user who 778 * should be suspended. 779 * @return Zend_Gdata_Gapps_UserEntry The UserEntry for the modified 780 * user. 781 * @throws Zend_Gdata_App_Exception 782 * @throws Zend_Gdata_App_HttpException 783 * @throws Zend_Gdata_Gapps_ServiceException 784 */ 785 public function suspendUser($username) { 786 $user = $this->retrieveUser($username); 787 $user->login->suspended = true; 788 return $user->save(); 789 } 790 791 /** 792 * Mark a given user as not suspended. 793 * 794 * @param string $username The username associated with the user who 795 * should be restored. 796 * @return Zend_Gdata_Gapps_UserEntry The UserEntry for the modified 797 * user. 798 * @throws Zend_Gdata_App_Exception 799 * @throws Zend_Gdata_App_HttpException 800 * @throws Zend_Gdata_Gapps_ServiceException 801 */ 802 public function restoreUser($username) { 803 $user = $this->retrieveUser($username); 804 $user->login->suspended = false; 805 return $user->save(); 806 } 807 808 /** 809 * Delete a user by username. 810 * 811 * @param string $username The username associated with the user who 812 * should be deleted. 813 * @throws Zend_Gdata_App_Exception 814 * @throws Zend_Gdata_App_HttpException 815 * @throws Zend_Gdata_Gapps_ServiceException 816 */ 817 public function deleteUser($username) { 818 $this->delete($this->getBaseUrl() . self::APPS_USER_PATH . '/' . 819 $username); 820 } 821 822 /** 823 * Create a nickname for a given user. 824 * 825 * @param string $username The username to which the new nickname should 826 * be associated. 827 * @param string $nickname The new nickname to be created. 828 * @return Zend_Gdata_Gapps_NicknameEntry The nickname entry which was 829 * created by the server. 830 * @throws Zend_Gdata_App_Exception 831 * @throws Zend_Gdata_App_HttpException 832 * @throws Zend_Gdata_Gapps_ServiceException 833 */ 834 public function createNickname($username, $nickname) { 835 $entry = $this->newNicknameEntry(); 836 $nickname = $this->newNickname($nickname); 837 $login = $this->newLogin($username); 838 $entry->nickname = $nickname; 839 $entry->login = $login; 840 return $this->insertNickname($entry); 841 } 842 843 /** 844 * Retrieve the entry for a specified nickname. 845 * 846 * @param string $nickname The nickname to be retrieved. 847 * @return Zend_Gdata_Gapps_NicknameEntry The requested nickname entry. 848 * @throws Zend_Gdata_App_Exception 849 * @throws Zend_Gdata_App_HttpException 850 * @throws Zend_Gdata_Gapps_ServiceException 851 */ 852 public function retrieveNickname($nickname) { 853 $query = $this->newNicknameQuery(); 854 $query->setNickname($nickname); 855 try { 856 $nickname = $this->getNicknameEntry($query); 857 } catch (Zend_Gdata_Gapps_ServiceException $e) { 858 // Set the nickname to null if not found 859 if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) { 860 $nickname = null; 861 } else { 862 throw $e; 863 } 864 } 865 return $nickname; 866 } 867 868 /** 869 * Retrieve all nicknames associated with a specific username. 870 * 871 * @param string $username The username whose nicknames should be 872 * returned. 873 * @return Zend_Gdata_Gapps_NicknameFeed A feed containing all nicknames 874 * for the given user, or null if 875 * @throws Zend_Gdata_App_Exception 876 * @throws Zend_Gdata_App_HttpException 877 * @throws Zend_Gdata_Gapps_ServiceException 878 */ 879 public function retrieveNicknames($username) { 880 $query = $this->newNicknameQuery(); 881 $query->setUsername($username); 882 $nicknameFeed = $this->retrieveAllEntriesForFeed( 883 $this->getNicknameFeed($query)); 884 return $nicknameFeed; 885 } 886 887 /** 888 * Retrieve a page of nicknames in alphabetical order, starting with the 889 * provided nickname. 890 * 891 * @param string $startNickname (optional) The first nickname to 892 * retrieve. If null or not declared, the page will begin with 893 * the first nickname in the domain. 894 * @return Zend_Gdata_Gapps_NicknameFeed Collection of Zend_Gdata_NicknameEntry 895 * objects representing all nicknames in the domain. 896 * @throws Zend_Gdata_App_Exception 897 * @throws Zend_Gdata_App_HttpException 898 * @throws Zend_Gdata_Gapps_ServiceException 899 */ 900 public function retrievePageOfNicknames ($startNickname = null) { 901 $query = $this->newNicknameQuery(); 902 $query->setStartNickname($startNickname); 903 return $this->getNicknameFeed($query); 904 } 905 906 /** 907 * Retrieve all nicknames in the current domain. Be aware that 908 * calling this function on a domain with many nicknames will take a 909 * signifigant amount of time to complete. On larger domains this may 910 * may cause execution to timeout without proper precautions in place. 911 * 912 * @return Zend_Gdata_Gapps_NicknameFeed Collection of Zend_Gdata_NicknameEntry 913 * objects representing all nicknames in the domain. 914 * @throws Zend_Gdata_App_Exception 915 * @throws Zend_Gdata_App_HttpException 916 * @throws Zend_Gdata_Gapps_ServiceException 917 */ 918 public function retrieveAllNicknames () { 919 return $this->retrieveAllEntriesForFeed($this->retrievePageOfNicknames()); 920 } 921 922 /** 923 * Delete a specified nickname. 924 * 925 * @param string $nickname The name of the nickname to be deleted. 926 * @throws Zend_Gdata_App_Exception 927 * @throws Zend_Gdata_App_HttpException 928 * @throws Zend_Gdata_Gapps_ServiceException 929 */ 930 public function deleteNickname($nickname) { 931 $this->delete($this->getBaseUrl() . self::APPS_NICKNAME_PATH . '/' . $nickname); 932 } 933 934 /** 935 * Create a new email list. 936 * 937 * @param string $emailList The name of the email list to be created. 938 * @return Zend_Gdata_Gapps_EmailListEntry The email list entry 939 * as created on the server. 940 * @throws Zend_Gdata_App_Exception 941 * @throws Zend_Gdata_App_HttpException 942 * @throws Zend_Gdata_Gapps_ServiceException 943 */ 944 public function createEmailList($emailList) { 945 $entry = $this->newEmailListEntry(); 946 $list = $this->newEmailList(); 947 $list->name = $emailList; 948 $entry->emailList = $list; 949 return $this->insertEmailList($entry); 950 } 951 952 /** 953 * Retrieve all email lists associated with a recipient. 954 * 955 * @param string $username The recipient whose associated email lists 956 * should be returned. 957 * @return Zend_Gdata_Gapps_EmailListFeed The list of email lists found as 958 * Zend_Gdata_EmailListEntry objects. 959 * @throws Zend_Gdata_App_Exception 960 * @throws Zend_Gdata_App_HttpException 961 * @throws Zend_Gdata_Gapps_ServiceException 962 */ 963 public function retrieveEmailLists($recipient) { 964 $query = $this->newEmailListQuery(); 965 $query->recipient = $recipient; 966 return $this->getEmailListFeed($query); 967 } 968 969 /** 970 * Retrieve a page of email lists in alphabetical order, starting with the 971 * provided email list. 972 * 973 * @param string $startEmailListName (optional) The first list to 974 * retrieve. If null or not defined, the page will begin 975 * with the first email list in the domain. 976 * @return Zend_Gdata_Gapps_EmailListFeed Collection of Zend_Gdata_EmailListEntry 977 * objects representing all nicknames in the domain. 978 * @throws Zend_Gdata_App_Exception 979 * @throws Zend_Gdata_App_HttpException 980 * @throws Zend_Gdata_Gapps_ServiceException 981 */ 982 public function retrievePageOfEmailLists ($startNickname = null) { 983 $query = $this->newEmailListQuery(); 984 $query->setStartEmailListName($startNickname); 985 return $this->getEmailListFeed($query); 986 } 987 988 /** 989 * Retrieve all email lists associated with the curent domain. Be aware that 990 * calling this function on a domain with many email lists will take a 991 * signifigant amount of time to complete. On larger domains this may 992 * may cause execution to timeout without proper precautions in place. 993 * 994 * @return Zend_Gdata_Gapps_EmailListFeed The list of email lists found 995 * as Zend_Gdata_Gapps_EmailListEntry objects. 996 * @throws Zend_Gdata_App_Exception 997 * @throws Zend_Gdata_App_HttpException 998 * @throws Zend_Gdata_Gapps_ServiceException 999 */ 1000 public function retrieveAllEmailLists() { 1001 return $this->retrieveAllEntriesForFeed($this->retrievePageOfEmailLists()); 1002 } 1003 1004 /** 1005 * Delete a specified email list. 1006 * 1007 * @param string $emailList The name of the emailList to be deleted. 1008 * @throws Zend_Gdata_App_Exception 1009 * @throws Zend_Gdata_App_HttpException 1010 * @throws Zend_Gdata_Gapps_ServiceException 1011 */ 1012 public function deleteEmailList($emailList) { 1013 $this->delete($this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/' 1014 . $emailList); 1015 } 1016 1017 /** 1018 * Add a specified recipient to an existing emailList. 1019 * 1020 * @param string $recipientAddress The address of the recipient to be 1021 * added to the email list. 1022 * @param string $emailList The name of the email address to which the 1023 * recipient should be added. 1024 * @return Zend_Gdata_Gapps_EmailListRecipientEntry The recipient entry 1025 * created by the server. 1026 * @throws Zend_Gdata_App_Exception 1027 * @throws Zend_Gdata_App_HttpException 1028 * @throws Zend_Gdata_Gapps_ServiceException 1029 */ 1030 public function addRecipientToEmailList($recipientAddress, $emailList) { 1031 $entry = $this->newEmailListRecipientEntry(); 1032 $who = $this->newWho(); 1033 $who->email = $recipientAddress; 1034 $entry->who = $who; 1035 $address = $this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/' . 1036 $emailList . self::APPS_EMAIL_LIST_RECIPIENT_POSTFIX . '/'; 1037 return $this->insertEmailListRecipient($entry, $address); 1038 } 1039 1040 /** 1041 * Retrieve a page of email list recipients in alphabetical order, 1042 * starting with the provided email list recipient. 1043 * 1044 * @param string $emaiList The email list which should be searched. 1045 * @param string $startRecipient (optinal) The address of the first 1046 * recipient, or null to start with the first recipient in 1047 * the list. 1048 * @return Zend_Gdata_Gapps_EmailListRecipientFeed Collection of 1049 * Zend_Gdata_EmailListRecipientEntry objects representing all 1050 * recpients in the specified list. 1051 * @throws Zend_Gdata_App_Exception 1052 * @throws Zend_Gdata_App_HttpException 1053 * @throws Zend_Gdata_Gapps_ServiceException 1054 */ 1055 public function retrievePageOfRecipients ($emailList, 1056 $startRecipient = null) { 1057 $query = $this->newEmailListRecipientQuery(); 1058 $query->setEmailListName($emailList); 1059 $query->setStartRecipient($startRecipient); 1060 return $this->getEmailListRecipientFeed($query); 1061 } 1062 1063 /** 1064 * Retrieve all recipients associated with an email list. Be aware that 1065 * calling this function on a domain with many email lists will take a 1066 * signifigant amount of time to complete. On larger domains this may 1067 * may cause execution to timeout without proper precautions in place. 1068 * 1069 * @param string $emaiList The email list which should be searched. 1070 * @return Zend_Gdata_Gapps_EmailListRecipientFeed The list of email lists 1071 * found as Zend_Gdata_Gapps_EmailListRecipientEntry objects. 1072 * @throws Zend_Gdata_App_Exception 1073 * @throws Zend_Gdata_App_HttpException 1074 * @throws Zend_Gdata_Gapps_ServiceException 1075 */ 1076 public function retrieveAllRecipients($emailList) { 1077 return $this->retrieveAllEntriesForFeed( 1078 $this->retrievePageOfRecipients($emailList)); 1079 } 1080 1081 /** 1082 * Remove a specified recipient from an email list. 1083 * 1084 * @param string $recipientAddress The recipient to be removed. 1085 * @param string $emailList The list from which the recipient should 1086 * be removed. 1087 * @throws Zend_Gdata_App_Exception 1088 * @throws Zend_Gdata_App_HttpException 1089 * @throws Zend_Gdata_Gapps_ServiceException 1090 */ 1091 public function removeRecipientFromEmailList($recipientAddress, $emailList) { 1092 $this->delete($this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/' 1093 . $emailList . self::APPS_EMAIL_LIST_RECIPIENT_POSTFIX . '/' 1094 . $recipientAddress); 1095 } 1096 1097 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Fri Nov 28 20:29:05 2014 | Cross-referenced by PHPXref 0.7.1 |