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.
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
27 require_once 'Zend/Gdata.php';
30 * @see Zend_Gdata_Gapps_UserFeed
32 require_once 'Zend/Gdata/Gapps/UserFeed.php';
35 * @see Zend_Gdata_Gapps_NicknameFeed
37 require_once 'Zend/Gdata/Gapps/NicknameFeed.php';
40 * @see Zend_Gdata_Gapps_GroupFeed
42 require_once 'Zend/Gdata/Gapps/GroupFeed.php';
45 * @see Zend_Gdata_Gapps_MemberFeed
47 require_once 'Zend/Gdata/Gapps/MemberFeed.php';
50 * @see Zend_Gdata_Gapps_OwnerFeed
52 require_once 'Zend/Gdata/Gapps/OwnerFeed.php';
55 * @see Zend_Gdata_Gapps_EmailListFeed
57 require_once 'Zend/Gdata/Gapps/EmailListFeed.php';
60 * @see Zend_Gdata_Gapps_EmailListRecipientFeed
62 require_once 'Zend/Gdata/Gapps/EmailListRecipientFeed.php';
66 * Service class for interacting with the Google Apps Provisioning API.
68 * Like other service classes in this module, this class provides access via
69 * an HTTP client to Google servers for working with entries and feeds.
71 * Because of the nature of this API, all access must occur over an
72 * authenticated connection.
74 * @link http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html
79 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
80 * @license http://framework.zend.com/license/new-bsd New BSD License
82 class Zend_Gdata_Gapps extends Zend_Gdata
85 const APPS_BASE_FEED_URI = 'https://apps-apis.google.com/a/feeds';
86 const AUTH_SERVICE_NAME = 'apps';
89 * Path to user feeds on the Google Apps server.
91 const APPS_USER_PATH = '/user/2.0';
94 * Path to nickname feeds on the Google Apps server.
96 const APPS_NICKNAME_PATH = '/nickname/2.0';
99 * Path to group feeds on the Google Apps server.
101 const APPS_GROUP_PATH = '/group/2.0';
104 * Path to email list feeds on the Google Apps server.
106 const APPS_EMAIL_LIST_PATH = '/emailList/2.0';
109 * Path to email list recipient feeds on the Google Apps server.
111 const APPS_EMAIL_LIST_RECIPIENT_POSTFIX = '/recipient';
114 * The domain which is being administered via the Provisioning API.
118 protected $_domain = null;
121 * Namespaces used for Zend_Gdata_Gapps
125 public static $namespaces = array(
126 array('apps', 'http://schemas.google.com/apps/2006', 1, 0)
130 * Create Gdata_Gapps object
132 * @param Zend_Http_Client $client (optional) The HTTP client to use when
133 * when communicating with the Google Apps servers.
134 * @param string $domain (optional) The Google Apps domain which is to be
136 * @param string $applicationId The identity of the app in the form of Company-AppName-Version
138 public function __construct($client = null, $domain = null, $applicationId = 'MyCompany-MyApp-1.0')
140 $this->registerPackage('Zend_Gdata_Gapps');
141 $this->registerPackage('Zend_Gdata_Gapps_Extension');
142 parent::__construct($client, $applicationId);
143 $this->_httpClient->setParameterPost('service', self::AUTH_SERVICE_NAME);
144 $this->_domain = $domain;
148 * Convert an exception to an ServiceException if an AppsForYourDomain
149 * XML document is contained within the original exception's HTTP
150 * response. If conversion fails, throw the original error.
152 * @param Zend_Gdata_Exception $e The exception to convert.
153 * @throws Zend_Gdata_Gapps_ServiceException
156 public static function throwServiceExceptionIfDetected($e) {
157 // Check to make sure that there actually response!
158 // This can happen if the connection dies before the request
159 // completes. (See ZF-5949)
160 $response = $e->getResponse();
162 require_once('Zend/Gdata/App/IOException.php');
163 throw new Zend_Gdata_App_IOException('No HTTP response received (possible connection failure)');
167 // Check to see if there is an AppsForYourDomainErrors
168 // datastructure in the response. If so, convert it to
169 // an exception and throw it.
170 require_once 'Zend/Gdata/Gapps/ServiceException.php';
171 $error = new Zend_Gdata_Gapps_ServiceException();
172 $error->importFromString($response->getBody());
174 } catch (Zend_Gdata_App_Exception $e2) {
175 // Unable to convert the response to a ServiceException,
176 // most likely because the server didn't return an
177 // AppsForYourDomainErrors document. Throw the original
184 * Imports a feed located at $uri.
185 * This method overrides the default behavior of Zend_Gdata_App,
186 * providing support for Zend_Gdata_Gapps_ServiceException.
189 * @param Zend_Http_Client $client (optional) The client used for
191 * @param string $className (optional) The class which is used as the
193 * @throws Zend_Gdata_App_Exception
194 * @throws Zend_Gdata_App_HttpException
195 * @throws Zend_Gdata_Gapps_ServiceException
196 * @return Zend_Gdata_App_Feed
198 public static function import($uri, $client = null, $className='Zend_Gdata_App_Feed')
201 return parent::import($uri, $client, $className);
202 } catch (Zend_Gdata_App_HttpException $e) {
203 self::throwServiceExceptionIfDetected($e);
208 * GET a URI using client object.
209 * This method overrides the default behavior of Zend_Gdata_App,
210 * providing support for Zend_Gdata_Gapps_ServiceException.
212 * @param string $uri GET URI
213 * @param array $extraHeaders Extra headers to add to the request, as an
214 * array of string-based key/value pairs.
215 * @throws Zend_Gdata_App_HttpException
216 * @throws Zend_Gdata_Gapps_ServiceException
217 * @return Zend_Http_Response
219 public function get($uri, $extraHeaders = array())
222 return parent::get($uri, $extraHeaders);
223 } catch (Zend_Gdata_App_HttpException $e) {
224 self::throwServiceExceptionIfDetected($e);
229 * POST data with client object.
230 * This method overrides the default behavior of Zend_Gdata_App,
231 * providing support for Zend_Gdata_Gapps_ServiceException.
233 * @param mixed $data The Zend_Gdata_App_Entry or XML to post
234 * @param string $uri (optional) POST URI
235 * @param integer $remainingRedirects (optional)
236 * @param string $contentType Content-type of the data
237 * @param array $extraHaders Extra headers to add tot he request
238 * @return Zend_Http_Response
239 * @throws Zend_Gdata_App_HttpException
240 * @throws Zend_Gdata_App_InvalidArgumentException
241 * @throws Zend_Gdata_Gapps_ServiceException
243 public function post($data, $uri = null, $remainingRedirects = null,
244 $contentType = null, $extraHeaders = null)
247 return parent::post($data, $uri, $remainingRedirects, $contentType, $extraHeaders);
248 } catch (Zend_Gdata_App_HttpException $e) {
249 self::throwServiceExceptionIfDetected($e);
254 * PUT data with client object
255 * This method overrides the default behavior of Zend_Gdata_App,
256 * providing support for Zend_Gdata_Gapps_ServiceException.
258 * @param mixed $data The Zend_Gdata_App_Entry or XML to post
259 * @param string $uri (optional) PUT URI
260 * @param integer $remainingRedirects (optional)
261 * @param string $contentType Content-type of the data
262 * @param array $extraHaders Extra headers to add tot he request
263 * @return Zend_Http_Response
264 * @throws Zend_Gdata_App_HttpException
265 * @throws Zend_Gdata_App_InvalidArgumentException
266 * @throws Zend_Gdata_Gapps_ServiceException
268 public function put($data, $uri = null, $remainingRedirects = null,
269 $contentType = null, $extraHeaders = null)
272 return parent::put($data, $uri, $remainingRedirects, $contentType, $extraHeaders);
273 } catch (Zend_Gdata_App_HttpException $e) {
274 self::throwServiceExceptionIfDetected($e);
279 * DELETE entry with client object
280 * This method overrides the default behavior of Zend_Gdata_App,
281 * providing support for Zend_Gdata_Gapps_ServiceException.
283 * @param mixed $data The Zend_Gdata_App_Entry or URL to delete
284 * @param integer $remainingRedirects (optional)
286 * @throws Zend_Gdata_App_HttpException
287 * @throws Zend_Gdata_App_InvalidArgumentException
288 * @throws Zend_Gdata_Gapps_ServiceException
290 public function delete($data, $remainingRedirects = null)
293 return parent::delete($data, $remainingRedirects);
294 } catch (Zend_Gdata_App_HttpException $e) {
295 self::throwServiceExceptionIfDetected($e);
300 * Set domain for this service instance. This should be a fully qualified
301 * domain, such as 'foo.example.com'.
303 * This value is used when calculating URLs for retrieving and posting
304 * entries. If no value is specified, a URL will have to be manually
305 * constructed prior to using any methods which interact with the Google
306 * Apps provisioning service.
308 * @param string $value The domain to be used for this session.
310 public function setDomain($value)
312 $this->_domain = $value;
316 * Get domain for this service instance. This should be a fully qualified
317 * domain, such as 'foo.example.com'. If no domain is set, null will be
320 * @return string The domain to be used for this session, or null if not
323 public function getDomain()
325 return $this->_domain;
329 * Returns the base URL used to access the Google Apps service, based
330 * on the current domain. The current domain can be temporarily
331 * overridden by providing a fully qualified domain as $domain.
333 * @param string $domain (optional) A fully-qualified domain to use
334 * instead of the default domain for this service instance.
335 * @throws Zend_Gdata_App_InvalidArgumentException
337 public function getBaseUrl($domain = null)
339 if ($domain !== null) {
340 return self::APPS_BASE_FEED_URI . '/' . $domain;
341 } else if ($this->_domain !== null) {
342 return self::APPS_BASE_FEED_URI . '/' . $this->_domain;
344 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
345 throw new Zend_Gdata_App_InvalidArgumentException(
346 'Domain must be specified.');
351 * Retrieve a UserFeed containing multiple UserEntry objects.
353 * @param mixed $location (optional) The location for the feed, as a URL
355 * @return Zend_Gdata_Gapps_UserFeed
356 * @throws Zend_Gdata_App_Exception
357 * @throws Zend_Gdata_App_HttpException
358 * @throws Zend_Gdata_Gapps_ServiceException
360 public function getUserFeed($location = null)
362 if ($location === null) {
363 $uri = $this->getBaseUrl() . self::APPS_USER_PATH;
364 } else if ($location instanceof Zend_Gdata_Query) {
365 $uri = $location->getQueryUrl();
369 return parent::getFeed($uri, 'Zend_Gdata_Gapps_UserFeed');
373 * Retreive NicknameFeed object containing multiple NicknameEntry objects.
375 * @param mixed $location (optional) The location for the feed, as a URL
377 * @return Zend_Gdata_Gapps_NicknameFeed
378 * @throws Zend_Gdata_App_Exception
379 * @throws Zend_Gdata_App_HttpException
380 * @throws Zend_Gdata_Gapps_ServiceException
382 public function getNicknameFeed($location = null)
384 if ($location === null) {
385 $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;
386 } else if ($location instanceof Zend_Gdata_Query) {
387 $uri = $location->getQueryUrl();
391 return parent::getFeed($uri, 'Zend_Gdata_Gapps_NicknameFeed');
395 * Retreive GroupFeed object containing multiple GroupEntry
398 * @param mixed $location (optional) The location for the feed, as a URL
400 * @return Zend_Gdata_Gapps_GroupFeed
401 * @throws Zend_Gdata_App_Exception
402 * @throws Zend_Gdata_App_HttpException
403 * @throws Zend_Gdata_Gapps_ServiceException
405 public function getGroupFeed($location = null)
407 if ($location === null) {
408 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
409 $uri .= $this->getDomain();
410 } else if ($location instanceof Zend_Gdata_Query) {
411 $uri = $location->getQueryUrl();
415 return parent::getFeed($uri, 'Zend_Gdata_Gapps_GroupFeed');
419 * Retreive MemberFeed object containing multiple MemberEntry
422 * @param mixed $location (optional) The location for the feed, as a URL
424 * @return Zend_Gdata_Gapps_MemberFeed
425 * @throws Zend_Gdata_App_Exception
426 * @throws Zend_Gdata_App_HttpException
427 * @throws Zend_Gdata_Gapps_ServiceException
429 public function getMemberFeed($location = null)
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();
440 return parent::getFeed($uri, 'Zend_Gdata_Gapps_MemberFeed');
444 * Retreive OwnerFeed object containing multiple OwnerEntry
447 * @param mixed $location (optional) The location for the feed, as a URL
449 * @return Zend_Gdata_Gapps_OwnerFeed
450 * @throws Zend_Gdata_App_Exception
451 * @throws Zend_Gdata_App_HttpException
452 * @throws Zend_Gdata_Gapps_ServiceException
454 public function getOwnerFeed($location = null)
456 if ($location === null) {
457 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
458 throw new Zend_Gdata_App_InvalidArgumentException(
459 'Location must not be null');
460 } else if ($location instanceof Zend_Gdata_Query) {
461 $uri = $location->getQueryUrl();
465 return parent::getFeed($uri, 'Zend_Gdata_Gapps_OwnerFeed');
469 * Retreive EmailListFeed object containing multiple EmailListEntry
472 * @param mixed $location (optional) The location for the feed, as a URL
474 * @return Zend_Gdata_Gapps_EmailListFeed
475 * @throws Zend_Gdata_App_Exception
476 * @throws Zend_Gdata_App_HttpException
477 * @throws Zend_Gdata_Gapps_ServiceException
479 public function getEmailListFeed($location = null)
481 if ($location === null) {
482 $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;
483 } else if ($location instanceof Zend_Gdata_Query) {
484 $uri = $location->getQueryUrl();
488 return parent::getFeed($uri, 'Zend_Gdata_Gapps_EmailListFeed');
492 * Retreive EmailListRecipientFeed object containing multiple
493 * EmailListRecipientEntry objects.
495 * @param mixed $location The location for the feed, as a URL or Query.
496 * @return Zend_Gdata_Gapps_EmailListRecipientFeed
497 * @throws Zend_Gdata_App_Exception
498 * @throws Zend_Gdata_App_HttpException
499 * @throws Zend_Gdata_Gapps_ServiceException
501 public function getEmailListRecipientFeed($location)
503 if ($location === null) {
504 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
505 throw new Zend_Gdata_App_InvalidArgumentException(
506 'Location must not be null');
507 } else if ($location instanceof Zend_Gdata_Query) {
508 $uri = $location->getQueryUrl();
512 return parent::getFeed($uri, 'Zend_Gdata_Gapps_EmailListRecipientFeed');
516 * Retreive a single UserEntry object.
518 * @param mixed $location The location for the feed, as a URL or Query.
519 * @return Zend_Gdata_Gapps_UserEntry
520 * @throws Zend_Gdata_App_Exception
521 * @throws Zend_Gdata_App_HttpException
522 * @throws Zend_Gdata_Gapps_ServiceException
524 public function getUserEntry($location)
526 if ($location === null) {
527 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
528 throw new Zend_Gdata_App_InvalidArgumentException(
529 'Location must not be null');
530 } else if ($location instanceof Zend_Gdata_Query) {
531 $uri = $location->getQueryUrl();
535 return parent::getEntry($uri, 'Zend_Gdata_Gapps_UserEntry');
539 * Retreive a single NicknameEntry object.
541 * @param mixed $location The location for the feed, as a URL or Query.
542 * @return Zend_Gdata_Gapps_NicknameEntry
543 * @throws Zend_Gdata_App_Exception
544 * @throws Zend_Gdata_App_HttpException
545 * @throws Zend_Gdata_Gapps_ServiceException
547 public function getNicknameEntry($location)
549 if ($location === null) {
550 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
551 throw new Zend_Gdata_App_InvalidArgumentException(
552 'Location must not be null');
553 } else if ($location instanceof Zend_Gdata_Query) {
554 $uri = $location->getQueryUrl();
558 return parent::getEntry($uri, 'Zend_Gdata_Gapps_NicknameEntry');
562 * Retreive a single GroupEntry object.
564 * @param mixed $location The location for the feed, as a URL or Query.
565 * @return Zend_Gdata_Gapps_GroupEntry
566 * @throws Zend_Gdata_App_Exception
567 * @throws Zend_Gdata_App_HttpException
568 * @throws Zend_Gdata_Gapps_ServiceException
570 public function getGroupEntry($location = null)
572 if ($location === null) {
573 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
574 throw new Zend_Gdata_App_InvalidArgumentException(
575 'Location must not be null');
576 } else if ($location instanceof Zend_Gdata_Query) {
577 $uri = $location->getQueryUrl();
581 return parent::getEntry($uri, 'Zend_Gdata_Gapps_GroupEntry');
585 * Retreive a single MemberEntry object.
587 * @param mixed $location The location for the feed, as a URL or Query.
588 * @return Zend_Gdata_Gapps_MemberEntry
589 * @throws Zend_Gdata_App_Exception
590 * @throws Zend_Gdata_App_HttpException
591 * @throws Zend_Gdata_Gapps_ServiceException
593 public function getMemberEntry($location = null)
595 if ($location === null) {
596 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
597 throw new Zend_Gdata_App_InvalidArgumentException(
598 'Location must not be null');
599 } else if ($location instanceof Zend_Gdata_Query) {
600 $uri = $location->getQueryUrl();
604 return parent::getEntry($uri, 'Zend_Gdata_Gapps_MemberEntry');
608 * Retreive a single OwnerEntry object.
610 * @param mixed $location The location for the feed, as a URL or Query.
611 * @return Zend_Gdata_Gapps_OwnerEntry
612 * @throws Zend_Gdata_App_Exception
613 * @throws Zend_Gdata_App_HttpException
614 * @throws Zend_Gdata_Gapps_ServiceException
616 public function getOwnerEntry($location = null)
618 if ($location === null) {
619 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
620 throw new Zend_Gdata_App_InvalidArgumentException(
621 'Location must not be null');
622 } else if ($location instanceof Zend_Gdata_Query) {
623 $uri = $location->getQueryUrl();
627 return parent::getEntry($uri, 'Zend_Gdata_Gapps_OwnerEntry');
631 * Retreive a single EmailListEntry object.
633 * @param mixed $location The location for the feed, as a URL or Query.
634 * @return Zend_Gdata_Gapps_EmailListEntry
635 * @throws Zend_Gdata_App_Exception
636 * @throws Zend_Gdata_App_HttpException
637 * @throws Zend_Gdata_Gapps_ServiceException
639 public function getEmailListEntry($location)
641 if ($location === null) {
642 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
643 throw new Zend_Gdata_App_InvalidArgumentException(
644 'Location must not be null');
645 } else if ($location instanceof Zend_Gdata_Query) {
646 $uri = $location->getQueryUrl();
650 return parent::getEntry($uri, 'Zend_Gdata_Gapps_EmailListEntry');
654 * Retreive a single EmailListRecipientEntry object.
656 * @param mixed $location The location for the feed, as a URL or Query.
657 * @return Zend_Gdata_Gapps_EmailListRecipientEntry
658 * @throws Zend_Gdata_App_Exception
659 * @throws Zend_Gdata_App_HttpException
660 * @throws Zend_Gdata_Gapps_ServiceException
662 public function getEmailListRecipientEntry($location)
664 if ($location === null) {
665 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
666 throw new Zend_Gdata_App_InvalidArgumentException(
667 'Location must not be null');
668 } else if ($location instanceof Zend_Gdata_Query) {
669 $uri = $location->getQueryUrl();
673 return parent::getEntry($uri, 'Zend_Gdata_Gapps_EmailListRecipientEntry');
677 * Create a new user from a UserEntry.
679 * @param Zend_Gdata_Gapps_UserEntry $user The user entry to insert.
680 * @param string $uri (optional) The URI where the user should be
681 * uploaded to. If null, the default user creation URI for
682 * this domain will be used.
683 * @return Zend_Gdata_Gapps_UserEntry The inserted user entry as
684 * returned by the server.
685 * @throws Zend_Gdata_App_Exception
686 * @throws Zend_Gdata_App_HttpException
687 * @throws Zend_Gdata_Gapps_ServiceException
689 public function insertUser($user, $uri = null)
692 $uri = $this->getBaseUrl() . self::APPS_USER_PATH;
694 $newEntry = $this->insertEntry($user, $uri, 'Zend_Gdata_Gapps_UserEntry');
699 * Create a new nickname from a NicknameEntry.
701 * @param Zend_Gdata_Gapps_NicknameEntry $nickname The nickname entry to
703 * @param string $uri (optional) The URI where the nickname should be
704 * uploaded to. If null, the default nickname creation URI for
705 * this domain will be used.
706 * @return Zend_Gdata_Gapps_NicknameEntry The inserted nickname entry as
707 * returned by the server.
708 * @throws Zend_Gdata_App_Exception
709 * @throws Zend_Gdata_App_HttpException
710 * @throws Zend_Gdata_Gapps_ServiceException
712 public function insertNickname($nickname, $uri = null)
715 $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;
717 $newEntry = $this->insertEntry($nickname, $uri, 'Zend_Gdata_Gapps_NicknameEntry');
722 * Create a new group from a GroupEntry.
724 * @param Zend_Gdata_Gapps_GroupEntry $group The group entry to insert.
725 * @param string $uri (optional) The URI where the group should be
726 * uploaded to. If null, the default user creation URI for
727 * this domain will be used.
728 * @return Zend_Gdata_Gapps_GroupEntry The inserted group entry as
729 * returned by the server.
730 * @throws Zend_Gdata_App_Exception
731 * @throws Zend_Gdata_App_HttpException
732 * @throws Zend_Gdata_Gapps_ServiceException
734 public function insertGroup($group, $uri = null)
737 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
738 $uri .= $this->getDomain();
740 $newEntry = $this->insertEntry($group, $uri, 'Zend_Gdata_Gapps_GroupEntry');
745 * Create a new member from a MemberEntry.
747 * @param Zend_Gdata_Gapps_MemberEntry $member The member entry to insert.
748 * @param string $uri (optional) The URI where the group should be
749 * uploaded to. If null, the default user creation URI for
750 * this domain will be used.
751 * @return Zend_Gdata_Gapps_MemberEntry The inserted member entry as
752 * returned by the server.
753 * @throws Zend_Gdata_App_Exception
754 * @throws Zend_Gdata_App_HttpException
755 * @throws Zend_Gdata_Gapps_ServiceException
757 public function insertMember($member, $uri = null)
760 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
761 throw new Zend_Gdata_App_InvalidArgumentException(
762 'URI must not be null');
764 $newEntry = $this->insertEntry($member, $uri, 'Zend_Gdata_Gapps_MemberEntry');
769 * Create a new group from a OwnerEntry.
771 * @param Zend_Gdata_Gapps_OwnerEntry $owner The owner entry to insert.
772 * @param string $uri (optional) The URI where the owner should be
773 * uploaded to. If null, the default user creation URI for
774 * this domain will be used.
775 * @return Zend_Gdata_Gapps_OwnerEntry The inserted owner entry as
776 * returned by the server.
777 * @throws Zend_Gdata_App_Exception
778 * @throws Zend_Gdata_App_HttpException
779 * @throws Zend_Gdata_Gapps_ServiceException
781 public function insertOwner($owner, $uri = null)
784 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
785 throw new Zend_Gdata_App_InvalidArgumentException(
786 'URI must not be null');
788 $newEntry = $this->insertEntry($owner, $uri, 'Zend_Gdata_Gapps_OwnerEntry');
793 * Create a new email list from an EmailListEntry.
795 * @param Zend_Gdata_Gapps_EmailListEntry $emailList The email list entry
797 * @param string $uri (optional) The URI where the email list should be
798 * uploaded to. If null, the default email list creation URI for
799 * this domain will be used.
800 * @return Zend_Gdata_Gapps_EmailListEntry The inserted email list entry
801 * as returned by the server.
802 * @throws Zend_Gdata_App_Exception
803 * @throws Zend_Gdata_App_HttpException
804 * @throws Zend_Gdata_Gapps_ServiceException
806 public function insertEmailList($emailList, $uri = null)
809 $uri = $this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH;
811 $newEntry = $this->insertEntry($emailList, $uri, 'Zend_Gdata_Gapps_EmailListEntry');
816 * Create a new email list recipient from an EmailListRecipientEntry.
818 * @param Zend_Gdata_Gapps_EmailListRecipientEntry $recipient The recipient
820 * @param string $uri (optional) The URI where the recipient should be
821 * uploaded to. If null, the default recipient creation URI for
822 * this domain will be used.
823 * @return Zend_Gdata_Gapps_EmailListRecipientEntry The inserted
824 * recipient entry as returned by the server.
825 * @throws Zend_Gdata_App_Exception
826 * @throws Zend_Gdata_App_HttpException
827 * @throws Zend_Gdata_Gapps_ServiceException
829 public function insertEmailListRecipient($recipient, $uri = null)
832 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
833 throw new Zend_Gdata_App_InvalidArgumentException(
834 'URI must not be null');
835 } elseif ($uri instanceof Zend_Gdata_Gapps_EmailListEntry) {
836 $uri = $uri->getLink('edit')->href;
838 $newEntry = $this->insertEntry($recipient, $uri, 'Zend_Gdata_Gapps_EmailListRecipientEntry');
843 * Provides a magic factory method to instantiate new objects with
844 * shorter syntax than would otherwise be required by the Zend Framework
845 * naming conventions. For more information, see Zend_Gdata_App::__call().
847 * This overrides the default behavior of __call() so that query classes
848 * do not need to have their domain manually set when created with
849 * a magic factory method.
851 * @see Zend_Gdata_App::__call()
852 * @param string $method The method name being called
853 * @param array $args The arguments passed to the call
854 * @throws Zend_Gdata_App_Exception
856 public function __call($method, $args) {
857 if (preg_match('/^new(\w+Query)/', $method, $matches)) {
858 $class = $matches[1];
859 $foundClassName = null;
860 foreach ($this->_registeredPackages as $name) {
862 // Autoloading disabled on next line for compatibility
863 // with magic factories. See ZF-6660.
864 if (!class_exists($name . '_' . $class, false)) {
865 require_once 'Zend/Loader.php';
866 @Zend_Loader::loadClass($name . '_' . $class);
868 $foundClassName = $name . '_' . $class;
870 } catch (Zend_Exception $e) {
871 // package wasn't here- continue searching
874 if ($foundClassName != null) {
875 $reflectionObj = new ReflectionClass($foundClassName);
876 // Prepend the domain to the query
877 $args = array_merge(array($this->getDomain()), $args);
878 return $reflectionObj->newInstanceArgs($args);
880 require_once 'Zend/Gdata/App/Exception.php';
881 throw new Zend_Gdata_App_Exception(
882 "Unable to find '${class}' in registered packages");
885 return parent::__call($method, $args);
890 // Convenience methods
891 // Specified at http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html#appendix_e
894 * Create a new user entry and send it to the Google Apps servers.
896 * @param string $username The username for the new user.
897 * @param string $givenName The given name for the new user.
898 * @param string $familyName The family name for the new user.
899 * @param string $password The password for the new user as a plaintext string
900 * (if $passwordHashFunction is null) or a SHA-1 hashed
901 * value (if $passwordHashFunction = 'SHA-1').
902 * @param string $quotaLimitInMB (optional) The quota limit for the new user in MB.
903 * @return Zend_Gdata_Gapps_UserEntry (optional) The new user entry as returned by
905 * @throws Zend_Gdata_App_Exception
906 * @throws Zend_Gdata_App_HttpException
907 * @throws Zend_Gdata_Gapps_ServiceException
909 public function createUser ($username, $givenName, $familyName, $password,
910 $passwordHashFunction = null, $quotaLimitInMB = null) {
911 $user = $this->newUserEntry();
912 $user->login = $this->newLogin();
913 $user->login->username = $username;
914 $user->login->password = $password;
915 $user->login->hashFunctionName = $passwordHashFunction;
916 $user->name = $this->newName();
917 $user->name->givenName = $givenName;
918 $user->name->familyName = $familyName;
919 if ($quotaLimitInMB !== null) {
920 $user->quota = $this->newQuota();
921 $user->quota->limit = $quotaLimitInMB;
923 return $this->insertUser($user);
927 * Retrieve a user based on their username.
929 * @param string $username The username to search for.
930 * @return Zend_Gdata_Gapps_UserEntry The username to search for, or null
932 * @throws Zend_Gdata_App_InvalidArgumentException
933 * @throws Zend_Gdata_App_HttpException
935 public function retrieveUser ($username) {
936 $query = $this->newUserQuery($username);
938 $user = $this->getUserEntry($query);
939 } catch (Zend_Gdata_Gapps_ServiceException $e) {
940 // Set the user to null if not found
941 if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
951 * Retrieve a page of users in alphabetical order, starting with the
954 * @param string $startUsername (optional) The first username to retrieve.
955 * If null or not declared, the page will begin with the first
956 * user in the domain.
957 * @return Zend_Gdata_Gapps_UserFeed Collection of Zend_Gdata_UserEntry
958 * objects representing all users in the domain.
959 * @throws Zend_Gdata_App_Exception
960 * @throws Zend_Gdata_App_HttpException
961 * @throws Zend_Gdata_Gapps_ServiceException
963 public function retrievePageOfUsers ($startUsername = null) {
964 $query = $this->newUserQuery();
965 $query->setStartUsername($startUsername);
966 return $this->getUserFeed($query);
970 * Retrieve all users in the current domain. Be aware that
971 * calling this function on a domain with many users will take a
972 * signifigant amount of time to complete. On larger domains this may
973 * may cause execution to timeout without proper precautions in place.
975 * @return Zend_Gdata_Gapps_UserFeed Collection of Zend_Gdata_UserEntry
976 * objects representing all users in the domain.
977 * @throws Zend_Gdata_App_Exception
978 * @throws Zend_Gdata_App_HttpException
979 * @throws Zend_Gdata_Gapps_ServiceException
981 public function retrieveAllUsers () {
982 return $this->retrieveAllEntriesForFeed($this->retrievePageOfUsers());
986 * Overwrite a specified username with the provided UserEntry. The
987 * UserEntry does not need to contain an edit link.
989 * This method is provided for compliance with the Google Apps
990 * Provisioning API specification. Normally users will instead want to
991 * call UserEntry::save() instead.
993 * @see Zend_Gdata_App_Entry::save
994 * @param string $username The username whose data will be overwritten.
995 * @param Zend_Gdata_Gapps_UserEntry $userEntry The user entry which
996 * will be overwritten.
997 * @return Zend_Gdata_Gapps_UserEntry The UserEntry returned by the
999 * @throws Zend_Gdata_App_Exception
1000 * @throws Zend_Gdata_App_HttpException
1001 * @throws Zend_Gdata_Gapps_ServiceException
1003 public function updateUser($username, $userEntry) {
1004 return $this->updateEntry($userEntry, $this->getBaseUrl() .
1005 self::APPS_USER_PATH . '/' . $username);
1009 * Mark a given user as suspended.
1011 * @param string $username The username associated with the user who
1012 * should be suspended.
1013 * @return Zend_Gdata_Gapps_UserEntry The UserEntry for the modified
1015 * @throws Zend_Gdata_App_Exception
1016 * @throws Zend_Gdata_App_HttpException
1017 * @throws Zend_Gdata_Gapps_ServiceException
1019 public function suspendUser($username) {
1020 $user = $this->retrieveUser($username);
1021 $user->login->suspended = true;
1022 return $user->save();
1026 * Mark a given user as not suspended.
1028 * @param string $username The username associated with the user who
1029 * should be restored.
1030 * @return Zend_Gdata_Gapps_UserEntry The UserEntry for the modified
1032 * @throws Zend_Gdata_App_Exception
1033 * @throws Zend_Gdata_App_HttpException
1034 * @throws Zend_Gdata_Gapps_ServiceException
1036 public function restoreUser($username) {
1037 $user = $this->retrieveUser($username);
1038 $user->login->suspended = false;
1039 return $user->save();
1043 * Delete a user by username.
1045 * @param string $username The username associated with the user who
1046 * should be deleted.
1047 * @throws Zend_Gdata_App_Exception
1048 * @throws Zend_Gdata_App_HttpException
1049 * @throws Zend_Gdata_Gapps_ServiceException
1051 public function deleteUser($username) {
1052 $this->delete($this->getBaseUrl() . self::APPS_USER_PATH . '/' .
1057 * Create a nickname for a given user.
1059 * @param string $username The username to which the new nickname should
1061 * @param string $nickname The new nickname to be created.
1062 * @return Zend_Gdata_Gapps_NicknameEntry The nickname entry which was
1063 * created by the server.
1064 * @throws Zend_Gdata_App_Exception
1065 * @throws Zend_Gdata_App_HttpException
1066 * @throws Zend_Gdata_Gapps_ServiceException
1068 public function createNickname($username, $nickname) {
1069 $entry = $this->newNicknameEntry();
1070 $nickname = $this->newNickname($nickname);
1071 $login = $this->newLogin($username);
1072 $entry->nickname = $nickname;
1073 $entry->login = $login;
1074 return $this->insertNickname($entry);
1078 * Retrieve the entry for a specified nickname.
1080 * @param string $nickname The nickname to be retrieved.
1081 * @return Zend_Gdata_Gapps_NicknameEntry The requested nickname entry.
1082 * @throws Zend_Gdata_App_Exception
1083 * @throws Zend_Gdata_App_HttpException
1084 * @throws Zend_Gdata_Gapps_ServiceException
1086 public function retrieveNickname($nickname) {
1087 $query = $this->newNicknameQuery();
1088 $query->setNickname($nickname);
1090 $nickname = $this->getNicknameEntry($query);
1091 } catch (Zend_Gdata_Gapps_ServiceException $e) {
1092 // Set the nickname to null if not found
1093 if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
1103 * Retrieve all nicknames associated with a specific username.
1105 * @param string $username The username whose nicknames should be
1107 * @return Zend_Gdata_Gapps_NicknameFeed A feed containing all nicknames
1108 * for the given user, or null if
1109 * @throws Zend_Gdata_App_Exception
1110 * @throws Zend_Gdata_App_HttpException
1111 * @throws Zend_Gdata_Gapps_ServiceException
1113 public function retrieveNicknames($username) {
1114 $query = $this->newNicknameQuery();
1115 $query->setUsername($username);
1116 $nicknameFeed = $this->retrieveAllEntriesForFeed(
1117 $this->getNicknameFeed($query));
1118 return $nicknameFeed;
1122 * Retrieve a page of nicknames in alphabetical order, starting with the
1123 * provided nickname.
1125 * @param string $startNickname (optional) The first nickname to
1126 * retrieve. If null or not declared, the page will begin with
1127 * the first nickname in the domain.
1128 * @return Zend_Gdata_Gapps_NicknameFeed Collection of Zend_Gdata_NicknameEntry
1129 * objects representing all nicknames in the domain.
1130 * @throws Zend_Gdata_App_Exception
1131 * @throws Zend_Gdata_App_HttpException
1132 * @throws Zend_Gdata_Gapps_ServiceException
1134 public function retrievePageOfNicknames ($startNickname = null) {
1135 $query = $this->newNicknameQuery();
1136 $query->setStartNickname($startNickname);
1137 return $this->getNicknameFeed($query);
1141 * Retrieve all nicknames in the current domain. Be aware that
1142 * calling this function on a domain with many nicknames will take a
1143 * signifigant amount of time to complete. On larger domains this may
1144 * may cause execution to timeout without proper precautions in place.
1146 * @return Zend_Gdata_Gapps_NicknameFeed Collection of Zend_Gdata_NicknameEntry
1147 * objects representing all nicknames in the domain.
1148 * @throws Zend_Gdata_App_Exception
1149 * @throws Zend_Gdata_App_HttpException
1150 * @throws Zend_Gdata_Gapps_ServiceException
1152 public function retrieveAllNicknames () {
1153 return $this->retrieveAllEntriesForFeed($this->retrievePageOfNicknames());
1157 * Delete a specified nickname.
1159 * @param string $nickname The name of the nickname to be deleted.
1160 * @throws Zend_Gdata_App_Exception
1161 * @throws Zend_Gdata_App_HttpException
1162 * @throws Zend_Gdata_Gapps_ServiceException
1164 public function deleteNickname($nickname) {
1165 $this->delete($this->getBaseUrl() . self::APPS_NICKNAME_PATH . '/' . $nickname);
1169 * Create a new group.
1171 * @param string $groupId A unique identifier for the group
1172 * @param string $groupName The name of the group
1173 * @param string $description A description of the group
1174 * @param string $emailPermission The subscription permission of the group
1175 * @return Zend_Gdata_Gapps_GroupEntry The group entry as created on the server.
1177 public function createGroup($groupId, $groupName, $description = null, $emailPermission = null)
1180 $group = $this->newGroupEntry();
1182 $properties[$i] = $this->newProperty();
1183 $properties[$i]->name = 'groupId';
1184 $properties[$i]->value = $groupId;
1186 $properties[$i] = $this->newProperty();
1187 $properties[$i]->name = 'groupName';
1188 $properties[$i]->value = $groupName;
1191 if($description != null) {
1192 $properties[$i] = $this->newProperty();
1193 $properties[$i]->name = 'description';
1194 $properties[$i]->value = $description;
1198 if($emailPermission != null) {
1199 $properties[$i] = $this->newProperty();
1200 $properties[$i]->name = 'emailPermission';
1201 $properties[$i]->value = $emailPermission;
1205 $group->property = $properties;
1207 return $this->insertGroup($group);
1211 * Retrieves a group based on group id
1213 * @param string $groupId The unique identifier for the group
1214 * @return Zend_Gdata_Gapps_GroupEntry The group entry as returned by the server.
1216 public function retrieveGroup($groupId)
1218 $query = $this->newGroupQuery($groupId);
1219 //$query->setGroupId($groupId);
1222 $group = $this->getGroupEntry($query);
1223 } catch (Zend_Gdata_Gapps_ServiceException $e) {
1224 // Set the group to null if not found
1225 if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
1235 * Retrieve all groups in the current domain. Be aware that
1236 * calling this function on a domain with many groups will take a
1237 * signifigant amount of time to complete. On larger domains this may
1238 * may cause execution to timeout without proper precautions in place.
1240 * @return Zend_Gdata_Gapps_GroupFeed Collection of Zend_Gdata_GroupEntry objects
1241 * representing all groups apart of the domain.
1243 public function retrieveAllGroups()
1245 return $this->retrieveAllEntriesForFeed($this->retrievePageOfGroups());
1251 * @param string $groupId The unique identifier for the group
1253 public function deleteGroup($groupId)
1255 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1256 $uri .= $this->getDomain() . '/' . $groupId;
1258 $this->delete($uri);
1262 * Check to see if a member id or group id is a member of group
1264 * @param string $memberId Member id or group group id
1265 * @param string $groupId Group to be checked for
1266 * @return bool True, if given entity is a member
1268 public function isMember($memberId, $groupId)
1270 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1271 $uri .= $this->getDomain() . '/' . $groupId . '/member/' . $memberId;
1273 //if the enitiy is not a member, an exception is thrown
1275 $results = $this->get($uri);
1276 } catch (Exception $e) {
1288 * Add an email address to a group as a member
1290 * @param string $recipientAddress Email address, member id, or group id
1291 * @param string $groupId The unique id of the group
1292 * @return Zend_Gdata_Gapps_MemberEntry The member entry returned by the server
1294 public function addMemberToGroup($recipientAddress, $groupId)
1296 $member = $this->newMemberEntry();
1298 $properties[] = $this->newProperty();
1299 $properties[0]->name = 'memberId';
1300 $properties[0]->value = $recipientAddress;
1302 $member->property = $properties;
1304 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1305 $uri .= $this->getDomain() . '/' . $groupId . '/member';
1307 return $this->insertMember($member, $uri);
1311 * Remove a member id from a group
1313 * @param string $memberId Member id or group id
1314 * @param string $groupId The unique id of the group
1316 public function removeMemberFromGroup($memberId, $groupId)
1318 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1319 $uri .= $this->getDomain() . '/' . $groupId . '/member/' . $memberId;
1321 return $this->delete($uri);
1325 * Retrieves all the members of a group
1327 * @param string $groupId The unique id of the group
1328 * @return Zend_Gdata_Gapps_MemberFeed Collection of MemberEntry objects
1329 * representing all members apart of the group.
1331 public function retrieveAllMembers($groupId)
1333 return $this->retrieveAllEntriesForFeed(
1334 $this->retrievePageOfMembers($groupId));
1338 * Add an email as an owner of a group
1340 * @param string $email Owner's email
1341 * @param string $groupId Group ownership to be checked for
1342 * @return Zend_Gdata_Gapps_OwnerEntry The OwnerEntry returned by the server
1344 public function addOwnerToGroup($email, $groupId)
1346 $owner = $this->newOwnerEntry();
1348 $properties[] = $this->newProperty();
1349 $properties[0]->name = 'email';
1350 $properties[0]->value = $email;
1352 $owner->property = $properties;
1354 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1355 $uri .= $this->getDomain() . '/' . $groupId . '/owner';
1357 return $this->insertOwner($owner, $uri);
1361 * Retrieves all the owners of a group
1363 * @param string $groupId The unique identifier for the group
1364 * @return Zend_Gdata_Gapps_OwnerFeed Collection of Zend_Gdata_OwnerEntry
1365 * objects representing all owners apart of the group.
1367 public function retrieveGroupOwners($groupId)
1369 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1370 $uri .= $this->getDomain() . '/' . $groupId . '/owner';
1372 return $this->getOwnerFeed($uri);
1376 * Checks to see if an email is an owner of a group
1378 * @param string $email Owner's email
1379 * @param string $groupId Group ownership to be checked for
1380 * @return bool True, if given entity is an owner
1382 public function isOwner($email, $groupId)
1384 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1385 $uri .= $this->getDomain() . '/' . $groupId . '/owner/' . $email;
1387 //if the enitiy is not an owner of the group, an exception is thrown
1389 $results = $this->get($uri);
1390 } catch (Exception $e) {
1402 * Remove email as an owner of a group
1404 * @param string $email Owner's email
1405 * @param string $groupId The unique identifier for the group
1407 public function removeOwnerFromGroup($email, $groupId)
1409 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1410 $uri .= $this->getDomain() . '/' . $groupId . '/owner/' . $email;
1412 return $this->delete($uri);
1416 * Update group properties with new values. any property not defined will not
1419 * @param string $groupId A unique identifier for the group
1420 * @param string $groupName The name of the group
1421 * @param string $description A description of the group
1422 * @param string $emailPermission The subscription permission of the group
1423 * @return Zend_Gdata_Gapps_GroupEntry The group entry as updated on the server.
1425 public function updateGroup($groupId, $groupName = null, $description = null,
1426 $emailPermission = null)
1429 $group = $this->newGroupEntry();
1431 $properties[$i] = $this->newProperty();
1432 $properties[$i]->name = 'groupId';
1433 $properties[$i]->value = $groupId;
1436 if($groupName != null) {
1437 $properties[$i] = $this->newProperty();
1438 $properties[$i]->name = 'groupName';
1439 $properties[$i]->value = $groupName;
1443 if($description != null) {
1444 $properties[$i] = $this->newProperty();
1445 $properties[$i]->name = 'description';
1446 $properties[$i]->value = $description;
1450 if($emailPermission != null) {
1451 $properties[$i] = $this->newProperty();
1452 $properties[$i]->name = 'emailPermission';
1453 $properties[$i]->value = $emailPermission;
1457 $group->property = $properties;
1459 $uri = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';
1460 $uri .= $this->getDomain() . '/' . $groupId;
1462 return $this->updateEntry($group, $uri, 'Zend_Gdata_Gapps_GroupEntry');
1466 * Retrieve all of the groups that a user is a member of
1468 * @param string $memberId Member username
1469 * @param bool $directOnly (Optional) If true, members with direct association
1470 * only will be considered
1471 * @return Zend_Gdata_Gapps_GroupFeed Collection of Zend_Gdata_GroupEntry
1472 * objects representing all groups member is apart of in the domain.
1474 public function retrieveGroups($memberId, $directOnly = null)
1476 $query = $this->newGroupQuery();
1477 $query->setMember($memberId);
1478 if($directOnly != null) {
1479 $query->setDirectOnly($directOnly);
1481 return $this->getGroupFeed($query);
1485 * Retrieve a page of groups in alphabetical order, starting with the
1488 * @param string $startGroup (optional) The first group to
1489 * retrieve. If null or not defined, the page will begin
1490 * with the first group in the domain.
1491 * @return Zend_Gdata_Gapps_GroupFeed Collection of Zend_Gdata_GroupEntry
1492 * objects representing the groups in the domain.
1493 * @throws Zend_Gdata_App_Exception
1494 * @throws Zend_Gdata_App_HttpException
1495 * @throws Zend_Gdata_Gapps_ServiceException
1497 public function retrievePageOfGroups ($startGroup = null)
1499 $query = $this->newGroupQuery();
1500 $query->setStartGroupId($startGroup);
1501 return $this->getGroupFeed($query);
1505 * Gets page of Members
1507 * @param string $groupId The group id which should be searched.
1508 * @param string $startMember (optinal) The address of the first member,
1509 * or null to start with the first member in the list.
1510 * @return Zend_Gdata_Gapps_MemberFeed Collection of Zend_Gdata_MemberEntry
1513 public function retrievePageOfMembers($groupId, $startMember = null)
1515 $query = $this->newMemberQuery($groupId);
1516 $query->setStartMemberId($startMember);
1517 return $this->getMemberFeed($query);
1521 * Create a new email list.
1523 * @param string $emailList The name of the email list to be created.
1524 * @return Zend_Gdata_Gapps_EmailListEntry The email list entry
1525 * as created on the server.
1526 * @throws Zend_Gdata_App_Exception
1527 * @throws Zend_Gdata_App_HttpException
1528 * @throws Zend_Gdata_Gapps_ServiceException
1530 public function createEmailList($emailList) {
1531 $entry = $this->newEmailListEntry();
1532 $list = $this->newEmailList();
1533 $list->name = $emailList;
1534 $entry->emailList = $list;
1535 return $this->insertEmailList($entry);
1539 * Retrieve all email lists associated with a recipient.
1541 * @param string $username The recipient whose associated email lists
1542 * should be returned.
1543 * @return Zend_Gdata_Gapps_EmailListFeed The list of email lists found as
1544 * Zend_Gdata_EmailListEntry objects.
1545 * @throws Zend_Gdata_App_Exception
1546 * @throws Zend_Gdata_App_HttpException
1547 * @throws Zend_Gdata_Gapps_ServiceException
1549 public function retrieveEmailLists($recipient) {
1550 $query = $this->newEmailListQuery();
1551 $query->recipient = $recipient;
1552 return $this->getEmailListFeed($query);
1556 * Retrieve a page of email lists in alphabetical order, starting with the
1557 * provided email list.
1559 * @param string $startEmailListName (optional) The first list to
1560 * retrieve. If null or not defined, the page will begin
1561 * with the first email list in the domain.
1562 * @return Zend_Gdata_Gapps_EmailListFeed Collection of Zend_Gdata_EmailListEntry
1563 * objects representing all nicknames in the domain.
1564 * @throws Zend_Gdata_App_Exception
1565 * @throws Zend_Gdata_App_HttpException
1566 * @throws Zend_Gdata_Gapps_ServiceException
1568 public function retrievePageOfEmailLists ($startNickname = null) {
1569 $query = $this->newEmailListQuery();
1570 $query->setStartEmailListName($startNickname);
1571 return $this->getEmailListFeed($query);
1575 * Retrieve all email lists associated with the curent domain. Be aware that
1576 * calling this function on a domain with many email lists will take a
1577 * signifigant amount of time to complete. On larger domains this may
1578 * may cause execution to timeout without proper precautions in place.
1580 * @return Zend_Gdata_Gapps_EmailListFeed The list of email lists found
1581 * as Zend_Gdata_Gapps_EmailListEntry objects.
1582 * @throws Zend_Gdata_App_Exception
1583 * @throws Zend_Gdata_App_HttpException
1584 * @throws Zend_Gdata_Gapps_ServiceException
1586 public function retrieveAllEmailLists() {
1587 return $this->retrieveAllEntriesForFeed($this->retrievePageOfEmailLists());
1591 * Delete a specified email list.
1593 * @param string $emailList The name of the emailList to be deleted.
1594 * @throws Zend_Gdata_App_Exception
1595 * @throws Zend_Gdata_App_HttpException
1596 * @throws Zend_Gdata_Gapps_ServiceException
1598 public function deleteEmailList($emailList) {
1599 $this->delete($this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/'
1604 * Add a specified recipient to an existing emailList.
1606 * @param string $recipientAddress The address of the recipient to be
1607 * added to the email list.
1608 * @param string $emailList The name of the email address to which the
1609 * recipient should be added.
1610 * @return Zend_Gdata_Gapps_EmailListRecipientEntry The recipient entry
1611 * created by the server.
1612 * @throws Zend_Gdata_App_Exception
1613 * @throws Zend_Gdata_App_HttpException
1614 * @throws Zend_Gdata_Gapps_ServiceException
1616 public function addRecipientToEmailList($recipientAddress, $emailList) {
1617 $entry = $this->newEmailListRecipientEntry();
1618 $who = $this->newWho();
1619 $who->email = $recipientAddress;
1621 $address = $this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/' .
1622 $emailList . self::APPS_EMAIL_LIST_RECIPIENT_POSTFIX . '/';
1623 return $this->insertEmailListRecipient($entry, $address);
1627 * Retrieve a page of email list recipients in alphabetical order,
1628 * starting with the provided email list recipient.
1630 * @param string $emaiList The email list which should be searched.
1631 * @param string $startRecipient (optinal) The address of the first
1632 * recipient, or null to start with the first recipient in
1634 * @return Zend_Gdata_Gapps_EmailListRecipientFeed Collection of
1635 * Zend_Gdata_EmailListRecipientEntry objects representing all
1636 * recpients in the specified list.
1637 * @throws Zend_Gdata_App_Exception
1638 * @throws Zend_Gdata_App_HttpException
1639 * @throws Zend_Gdata_Gapps_ServiceException
1641 public function retrievePageOfRecipients ($emailList,
1642 $startRecipient = null) {
1643 $query = $this->newEmailListRecipientQuery();
1644 $query->setEmailListName($emailList);
1645 $query->setStartRecipient($startRecipient);
1646 return $this->getEmailListRecipientFeed($query);
1650 * Retrieve all recipients associated with an email list. Be aware that
1651 * calling this function on a domain with many email lists will take a
1652 * signifigant amount of time to complete. On larger domains this may
1653 * may cause execution to timeout without proper precautions in place.
1655 * @param string $emaiList The email list which should be searched.
1656 * @return Zend_Gdata_Gapps_EmailListRecipientFeed The list of email lists
1657 * found as Zend_Gdata_Gapps_EmailListRecipientEntry objects.
1658 * @throws Zend_Gdata_App_Exception
1659 * @throws Zend_Gdata_App_HttpException
1660 * @throws Zend_Gdata_Gapps_ServiceException
1662 public function retrieveAllRecipients($emailList) {
1663 return $this->retrieveAllEntriesForFeed(
1664 $this->retrievePageOfRecipients($emailList));
1668 * Remove a specified recipient from an email list.
1670 * @param string $recipientAddress The recipient to be removed.
1671 * @param string $emailList The list from which the recipient should
1673 * @throws Zend_Gdata_App_Exception
1674 * @throws Zend_Gdata_App_HttpException
1675 * @throws Zend_Gdata_Gapps_ServiceException
1677 public function removeRecipientFromEmailList($recipientAddress, $emailList) {
1678 $this->delete($this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/'
1679 . $emailList . self::APPS_EMAIL_LIST_RECIPIENT_POSTFIX . '/'
1680 . $recipientAddress);