source: trunk/www.guidonia.net/wp/wp-content/plugins/webtv/Drivers/Zend/Gdata/Gapps.php@ 44

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