Each user account on a Google Apps hosted domain is represented as
an instance of Zend_Gdata_Gapps_UserEntry. This class provides
access to all account properties including name, username,
password, access rights, and current quota.
User accounts can be created by calling the
createUser() convenience method:
<?php
$gdata->createUser('foo', 'Random', 'User', '••••••••');
Users can also be created by instantiating UserEntry,
providing a username, given name, family name, and password,
then calling insertUser() on a service object to
upload the entry to the server.
<?php
$user = $gdata->newUserEntry();
$user->login = $gdata->newLogin();
$user->login->username = 'foo';
$user->login->password = '••••••••';
$user->name = $gdata->newName();
$user->name->givenName = 'Random';
$user->name->familyName = 'User';
$user = $gdata->insertUser($user);
The user's password should normally be provided as cleartext. Optionally, the password can be provided as an SHA-1 digest if login->passwordHashFunction is set to 'SHA-1'.
Individual user accounts can be retrieved by calling the
retrieveUser() convenience method. If the user is
not found, NULL will be returned.
<?php
$user = $gdata->retrieveUser('foo');
echo 'Username: ' . $user->login->userName . "\n";
echo 'Given Name: ' . $user->name->givenName . "\n";
echo 'Family Name: ' . $user->name->familyName . "\n";
echo 'Suspended: ' . ($user->login->suspended ? 'Yes' : 'No') . "\n";
echo 'Admin: ' . ($user->login->admin ? 'Yes' : 'No') . "\n"
echo 'Must Change Password: ' .
($user->login->changePasswordAtNextLogin ? 'Yes' : 'No') . "\n";
echo 'Has Agreed To Terms: ' .
($user->login->agreedToTerms ? 'Yes' : 'No') . "\n";
Users can also be retrieved by creating an
instance of Zend_Gdata_Gapps_UserQuery, setting its username
property to equal the username of the user that is to be
retrieved, and calling getUserEntry() on a
service object with that query.
<?php
$query = $gdata->newUserQuery('foo');
$user = $gdata->getUserEntry($query);
echo 'Username: ' . $user->login->userName . "\n";
echo 'Given Name: ' . $user->login->givenName . "\n";
echo 'Family Name: ' . $user->login->familyName . "\n";
echo 'Suspended: ' . ($user->login->suspended ? 'Yes' : 'No') . "\n";
echo 'Admin: ' . ($user->login->admin ? 'Yes' : 'No') . "\n"
echo 'Must Change Password: ' .
($user->login->changePasswordAtNextLogin ? 'Yes' : 'No') . "\n";
echo 'Has Agreed To Terms: ' .
($user->login->agreedToTerms ? 'Yes' : 'No') . "\n";
If the specified user cannot be located a ServiceException
will be thrown with an error code of
Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST.
ServiceExceptions will be covered in the exceptions chapter.
To retrieve all users in a domain, call the
retrieveAllUsers() convenience method.
<?php
$feed = $gdata->retrieveAllUsers();
foreach ($feed as $user) {
echo " * " . $user->login->username . ' (' . $user->name->givenName .
' ' . $user->name->familyName . ")\n";
}
This will create a Zend_Gdata_Gapps_UserFeed object which
holds each user on the domain.
Alternatively, call getUserFeed() with no
options. Keep in mind that on larger
domains this feed may be paged by the server. For more
information on paging, see the paging chapter.
<?php
$feed = $gdata->getUserFeed();
foreach ($feed as $user) {
echo " * " . $user->login->username . ' (' . $user->name->givenName .
' ' . $user->name->familyName . ")\n";
}
The easiest way to update a user account is to retrieve the
user as described in the previous sections, make any desired
changes, then call save() on that user. Any
changes made will be propagated to the server.
<?php
$user = $gdata->retrieveUser('foo');
$user->name->givenName = 'Foo';
$user->name->familyName = 'Bar';
$user = $user->save();
A user's password can be reset to a new value by updating the login->password property.
<?php
$user = $gdata->retrieveUser('foo');
$user->login->password = '••••••••';
$user = $user->save();
Note that it is not possible to recover a password in this manner as stored passwords are not made available via the Provisioning API for security reasons.
A user can be forced to change their password at their
next login by setting the
login->changePasswordAtNextLogin property to
TRUE.
<?php
$user = $gdata->retrieveUser('foo');
$user->login->changePasswordAtNextLogin = true;
$user = $user->save();
Similarly, this can be undone by setting the
login->changePasswordAtNextLogin property to
FALSE.
Users can be restricted from logging in without deleting
their user account by instead
suspending their user account.
Accounts can be suspended or restored by using the
suspendUser() and
restoreUser() convenience methods:
<?php
$gdata->suspendUser('foo');
$gdata->restoreUser('foo');
Alternatively, you can set the UserEntry's
login->suspended property to
TRUE.
<?php
$user = $gdata->retrieveUser('foo');
$user->login->suspended = true;
$user = $user->save();
To restore the user's access, set the
login->suspended property to
FALSE.
Users can be granted the ability to administer your domain
by setting their login->admin property to
TRUE.
<?php
$user = $gdata->retrieveUser('foo');
$user->login->admin = true;
$user = $user->save();
And as expected, setting a user's login->admin
property to FALSE revokes their
administrative rights.
Deleting a user account to which you already hold a UserEntry
is a simple as calling delete() on that
entry.
<?php
$user = $gdata->retrieveUser('foo');
$user->delete();
If you do not have access to a UserEntry object for an
account, use the deleteUser() convenience method.
<?php
$gdata->deleteUser('foo');