Nicknames serve as email aliases for existing users. Each nickname contains precisely two key properties: its name and its owner. Any email addressed to a nickname is forwarded to the user who owns that nickname.
Nicknames are represented as an instances of
Zend_Gdata_Gapps_NicknameEntry.
Nicknames can be created by calling the
createNickname() convenience method:
<?php
$gdata->createNickname('foo', 'bar');
Nicknames can also be created by instantiating NicknameEntry,
providing the nickname with a name and an owner, then calling
insertNickname() on a service object to upload
the entry to the server.
<?php
$nickname = $gdata->newNicknameEntry();
$nickname->login = $gdata->newLogin('foo');
$nickname->nickname = $gdata->newNickname('bar');
$nickname = $gdata->insertNickname($nickname);
Nicknames can be retrieved by calling the
retrieveNickname() convenience method. This will
return NULL if a user is not found.
<?php
$nickname = $gdata->retrieveNickname('bar');
echo 'Nickname: ' . $nickname->nickname->name . "\n";
echo 'Owner: ' . $nickname->login->username . "\n";
Individual nicknames can also be retrieved by creating an
instance of Zend_Gdata_Gapps_NicknameQuery, setting its
nickname property to equal the nickname that is to be
retrieved, and calling getNicknameEntry() on a
service object with that query.
<?php
$query = $gdata->newNicknameQuery('bar');
$nickname = $gdata->getNicknameEntry($query);
echo 'Nickname: ' . $nickname->nickname->name . "\n";
echo 'Owner: ' . $nickname->login->username . "\n";
As with users, if no corresponding nickname is found a
ServiceException will be thrown with an error code of
Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST. Again, these
will be discussed in the exceptions chapter.
To retrieve all nicknames associated with a given user, call
the convenience method retrieveNicknames().
<?php
$feed = $gdata->retrieveNicknames('foo');
foreach ($feed as $nickname) {
echo ' * ' . $nickname->nickname->name . "\n";
}
This will create a Zend_Gdata_Gapps_NicknameFeed object which
holds each nickname associated with the specified user.
Alternatively, create a new Zend_Gdata_Gapps_NicknameQuery,
set its username property to the desired user, and submit the
query by calling getNicknameFeed() on a service
object.
<?php
$query = $gdata->newNicknameQuery();
$query->setUsername('foo');
$feed = $gdata->getNicknameFeed($query);
foreach ($feed as $nickname) {
echo ' * ' . $nickname->nickname->name . "\n";
}
To retrieve all nicknames in a feed, simply call the
convenience method retrieveAllNicknames()
<?php
$feed = $gdata->retrieveAllNicknames();
foreach ($feed as $nickname) {
echo ' * ' . $nickname->nickname->name . ' => ' .
$nickname->login->username . "\n";
}
This will create a Zend_Gdata_Gapps_NicknameFeed object which
holds each nickname on the domain.
Alternatively, call getNicknameFeed() on a
service object with no arguments.
<?php
$feed = $gdata->getNicknameFeed();
foreach ($feed as $nickname) {
echo ' * ' . $nickname->nickname->name . ' => ' .
$nickname->login->username . "\n";
}
Deleting a nickname to which you already hold a NicknameEntry
for is a simple as calling delete() on that
entry.
<?php
$nickname = $gdata->retrieveNickname('bar');
$nickname->delete();
For nicknames which you do not hold a NicknameEntry for, use
the deleteNickname() convenience method.
<?php
$gdata->deleteNickname('bar');