|
Perforce Chronicle 2012.2/486814
API Documentation
|
This is the user model. More...
Public Member Functions | |
| authenticate () | |
| Performs an authentication attempt. | |
| createPersonalAdapter ($ticket=null, P4Cms_Site $site=null) | |
| Generate a storage adapter that communicates with Perforce as this user. | |
| delete () | |
| Delete this user entry. | |
| getAggregateRole (P4Cms_Acl $acl=null) | |
| Generate a single role that inherits from all of the roles that this user has and register it with the acl temporarily (the role is not saved). | |
| getAllowedPrivileges ($resource, P4Cms_Acl $acl=null) | |
| Return list of all privileges for which user has access to a given resource. | |
| getEmail () | |
| Return the user's email-address. | |
| getFullName () | |
| Return the user's full name. | |
| getPassword () | |
| Get the in-memory password (if one is set). | |
| getPersonalAdapter () | |
| Get the personalized record storage adapter for this user. | |
| getRoles () | |
| Get the roles that this user belongs to. | |
| hasPersonalAdapter () | |
| Determine if a personalized adapter has been set for this user. | |
| isAdministrator () | |
| Determine if this user has administrator role. | |
| isAllowed ($resource, $privilege=null, P4Cms_Acl $acl=null) | |
| Determine if this user is allowed to access a particular resource and (optionally) a particular privilege on the resource. | |
| isAnonymous () | |
| Determine if this user is anonymous (has no id). | |
| isMember () | |
| Determine if this user has member role. | |
| isPassword ($password) | |
| Test if the given password is correct for this user. | |
| save () | |
| Save this user entry. | |
| setAdapter (P4Cms_Record_Adapter $adapter) | |
| Overrides parent to set adapter's connection for associated P4_User in addition. | |
| setEmail ($email) | |
| Set the user's email-address. | |
| setFullName ($name) | |
| Set the user's full name. | |
| setId ($id) | |
| Set the user id - extended to proxy to p4 user. | |
| setPassword ($newPassword, $oldPassword=null) | |
| Set the user's password to the given password. | |
| setPersonalAdapter (P4Cms_Record_Adapter $adapter=null) | |
| Set the personal storage adapter for this user. | |
Static Public Member Functions | |
| static | clearActive () |
| Clear the active user. | |
| static | clearRolesCache () |
| Clear the static roles cache entirely. | |
| static | count ($options=array(), P4Cms_Record_Adapter $adapter=null) |
| Count all users - extended to route through fetch all. | |
| static | exists ($username, $options=null, P4Cms_Record_Adapter $adapter=null) |
| Check if the named user exists. | |
| static | fetch ($username, array $options=null, P4Cms_Record_Adapter $adapter=null) |
| Fetch the named user. | |
| static | fetchActive () |
| Fetch the currently active user. | |
| static | fetchAll (array $options=null, P4Cms_Record_Adapter $adapter=null) |
| Fetch all users in the system (ie. | |
| static | fetchByRole ($role, P4Cms_Record_Adapter $adapter=null) |
| Fetch all role member users. | |
| static | generatePassword ($length, $strength=0) |
| Generate a pseudo-random password, alternating consonants and vowels to assist human readability. | |
| static | hasActive () |
| Determine if there is an active user. | |
| static | setActive (P4Cms_User $user) |
| Set the active user. | |
Public Attributes | |
| const | FETCH_BY_NAME = 'name' |
| const | FETCH_MAXIMUM = 'maximum' |
| const | FETCH_SYSTEM_USER = 'systemUser' |
Protected Member Functions | |
| _getP4User () | |
| Get the p4 user object that corresponds to this user. | |
| _setP4User ($user) | |
| Set the corresponding p4 user object instance. | |
Protected Attributes | |
| $_p4User = null | |
| $_personalAdapter = null | |
Static Protected Attributes | |
| static | $_acl = null |
| static | $_activeUser = null |
| static | $_fields |
| static | $_idField = 'id' |
| static | $_rolesCache = array() |
This is the user model.
Each user corresponds to a user in Perforce.
| P4Cms_User::_getP4User | ( | ) | [protected] |
Get the p4 user object that corresponds to this user.
{
// only instantiate user once.
if (!$this->_p4User instanceof P4_User) {
$connection = $this->hasAdapter()
? $this->getAdapter()->getConnection()
: null;
$this->_p4User = new P4_User($connection);
}
return $this->_p4User;
}
| P4Cms_User::_setP4User | ( | $ | user | ) | [protected] |
Set the corresponding p4 user object instance.
Used when fetching users to prime the user object.
| P4Cms_User_Exception | if the user is anonymous or if the given user is not a valid P4_User object. |
{
// anonymous users can't have a corresponding perforce user.
if ($this->isAnonymous()) {
throw new P4Cms_User_Exception(
"Cannot set p4 user for an anonymous user."
);
}
if (!$user instanceof P4_User) {
throw new P4Cms_User_Exception(
"Cannot set p4 user. The given user is not a valid P4_User object."
);
}
$this->_p4User = $user;
return $this;
}
| P4Cms_User::authenticate | ( | ) |
Performs an authentication attempt.
| Zend_Auth_Adapter_Exception | If authentication cannot be performed |
{
// authenticate against current p4 server.
$p4 = P4_Connection::factory(
$this->getAdapter()->getConnection()->getPort(),
$this->getId(),
null,
$this->getPassword()
);
try {
$ticket = $p4->login();
// deny if user has no real roles
if (!$this->getRoles()->count()) {
return new Zend_Auth_Result(
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS,
null,
array('At least one role is required for successful authentication.')
);
}
return new Zend_Auth_Result(
Zend_Auth_Result::SUCCESS,
array('id' => $this->getId(), 'ticket' => $ticket)
);
} catch (P4_Connection_LoginException $e) {
return new Zend_Auth_Result(
$e->getCode(),
null,
array($e->getMessage())
);
}
}
| static P4Cms_User::clearActive | ( | ) | [static] |
Clear the active user.
{
static::$_activeUser = null;
}
| static P4Cms_User::clearRolesCache | ( | ) | [static] |
Clear the static roles cache entirely.
{
static::$_rolesCache = array();
}
| static P4Cms_User::count | ( | $ | options = array(), |
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Count all users - extended to route through fetch all.
| array | $options | optional - array of options to augment count |
| P4Cms_Record_Adapter | $adapter | optional - storage adapter to use. |
{
return static::fetchAll($options, $adapter)->count();
}
| P4Cms_User::createPersonalAdapter | ( | $ | ticket = null, |
| P4Cms_Site $ | site = null |
||
| ) |
Generate a storage adapter that communicates with Perforce as this user.
| string | $ticket | optional - auth ticket to use for p4 connection |
| P4Cms_Site | $site | optional - site to get personal adapter for (defaults to active site) |
{
$site = $site ?: P4Cms_Site::fetchActive();
// to avoid problems that result from multiple processes
// sharing one client (namely race conditions), we generate
// a temporary client for each request.
$tempClientId = P4_Client::makeTempId();
// create connection based on the active site.
$connection = P4_Connection::factory(
$site->getConnection()->getPort(),
$this->getId(),
$tempClientId,
null,
$ticket ?: null
);
// store client files under given site's workspaces path.
$root = $site->getWorkspacesPath() . "/" . $tempClientId;
// provide a custom clean-up callback to delete the workspace folder.
$cleanup = function($entry, $defaultCallback) use ($root)
{
$defaultCallback($entry);
P4Cms_FileUtility::deleteRecursive($root);
};
// create the client with the values we've setup above, using
// makeTemp() so that it will be destroyed automatically.
P4_Client::makeTemp(
array(
'Client' => $tempClientId,
'Stream' => $site->getId(),
'Root' => $root
),
$cleanup,
$connection
);
// create personal adapter based on site adapter.
$adapter = new P4Cms_Record_Adapter;
$adapter->setConnection($connection)
->setBasePath("//" . $connection->getClient())
->setProperties($site->getStorageAdapter()->getProperties());
return $adapter;
}
| P4Cms_User::delete | ( | ) |
Delete this user entry.
{
// if user with personal adapter (active user) is going to be deleted,
// run disconnect callbacks before removing the user from Perforce,
// otherwise user may be resurrected if disconnect callbacks use
// user's connection (e.g. for user's workspace clean-up etc.)
if ($this->hasPersonalAdapter()) {
$connection = $this->getPersonalAdapter()->getConnection();
// run disconnect callbacks and clear them after to ensure they
// are not called again after user is removed from Perforce
$connection->runDisconnectCallbacks()
->clearDisconnectCallbacks();
}
// delete the user spec last
$this->_getP4User()->delete();
// disconnect user with personal adapter
if (isset($connection)) {
$connection->disconnect();
}
return $this;
}
| static P4Cms_User::exists | ( | $ | username, |
| $ | options = null, |
||
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Check if the named user exists.
| string | $username | the username of the user to look for. |
| array | null | $options | optional - no options are presently supported. |
| P4Cms_Record_Adapter | $adapter | optional - storage adapter to use. |
{
if (!is_array($options) && !is_null($options)) {
throw new InvalidArgumentException(
'Options must be an array or null'
);
}
try {
static::fetch($username, null, $adapter);
return true;
} catch (P4Cms_Model_NotFoundException $e) {
return false;
} catch (InvalidArgumentException $e) {
return false;
}
}
| static P4Cms_User::fetch | ( | $ | username, |
| array $ | options = null, |
||
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Fetch the named user.
| string | $username | the username of the user to fetch. |
| array | null | $options | optional - no options are presently supported. |
| P4Cms_Record_Adapter | $adapter | optional - storage adapter to use. |
| P4Cms_Model_NotFoundException | if the requested user does not exist. |
{
if (!is_array($options) && !is_null($options)) {
throw new InvalidArgumentException(
'Options must be an array or null'
);
}
$adapter = $adapter ?: static::getDefaultAdapter();
// attempt to fetch user from perforce.
try {
$p4User = P4_User::fetch($username, $adapter->getConnection());
} catch (P4_Spec_NotFoundException $e) {
throw new P4Cms_Model_NotFoundException(
"Cannot fetch user. User '$username' does not exist."
);
}
// create new user instance
$user = new static;
$user->setAdapter($adapter)
->setId($username)
->_setP4User($p4User);
return $user;
}
| static P4Cms_User::fetchActive | ( | ) | [static] |
Fetch the currently active user.
Guaranteed to return the active user model or throw an exception.
| P4Cms_User_Exception | if there is no currently active user. |
{
if (!static::$_activeUser || !static::$_activeUser instanceof P4Cms_User) {
throw new P4Cms_User_Exception("There is no currently active user.");
}
return static::$_activeUser;
}
| static P4Cms_User::fetchAll | ( | array $ | options = null, |
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Fetch all users in the system (ie.
get users from Perforce).
| array | $options | optional - array of options to augment fetch behavior. supported options are: |
FETCH_MAXIMUM - set to integer value to limit to the first 'max' number of entries. FETCH_BY_NAME - set to user name pattern (e.g. 'jdo*'), can be a single string or array of strings. FETCH_SYSTEM_USER - set to true to include the system user defaults to false (system user is excluded)
| P4Cms_Record_Adapter | $adapter | optional - storage adapter to use. |
{
$adapter = $adapter ?: static::getDefaultAdapter();
$users = new P4Cms_Model_Iterator;
foreach (P4_User::fetchAll($options, $adapter->getConnection()) as $p4User) {
$user = new static;
$user->setAdapter($adapter)
->setId($p4User->getId())
->_setP4User($p4User);
$users[] = $user;
}
// exclude system user by default
if ((!isset($options[static::FETCH_SYSTEM_USER]) || !$options[static::FETCH_SYSTEM_USER])
&& P4Cms_Site::hasActive()
) {
// we assume the active site is running as the system user; get the id
$systemUser = P4Cms_Site::fetchActive()->getConnection()->getUser();
$users->filter('id', $systemUser, array(P4Cms_Model_Iterator::FILTER_INVERSE));
}
return $users;
}
| static P4Cms_User::fetchByRole | ( | $ | role, |
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Fetch all role member users.
| P4Cms_Acl_Role | string | array | $role | role or list of roles to fetch members of. |
| P4Cms_Record_Adapter | $adapter | optional, storage adapter to use. |
{
if (is_string($role) || $role instanceof P4Cms_Acl_Role) {
$roles = array($role);
} else if (is_array($role)) {
$roles = $role;
} else {
throw new InvalidArgumentException(
"Role must be an instance of P4Cms_Acl_Role or a string or an array."
);
}
$users = array();
foreach ($roles as $role) {
// if role is not instance of P4Cms_Acl_Role, try to fetch it
if (!$role instanceof P4Cms_Acl_Role) {
if (!P4Cms_Acl_Role::exists($role, null, $adapter)) {
break;
}
$role = P4Cms_Acl_Role::fetch($role, null, $adapter);
}
// add role users to the users list
$users = array_merge($users, $role->getUsers());
}
// early exit if no users to fetch
if (!count($users)) {
return new P4Cms_Model_Iterator;
}
// fetch all member users
return static::fetchAll(array(static::FETCH_BY_NAME => array_unique($users)), $adapter);
}
| static P4Cms_User::generatePassword | ( | $ | length, |
| $ | strength = 0 |
||
| ) | [static] |
Generate a pseudo-random password, alternating consonants and vowels to assist human readability.
Password strength is flexible:
0 = lowercase letters only 1 = add uppercase consonants 2 = add uppercase vowels 3 = add numbers 4 = add special characters
| integer | $length | the desired length of the password. |
| integer | $strength | the desired strength of the password. |
{
// vowels and consonants excluding the letters o, i and l
// because they can be mistaken for other letters or numbers.
$vowels = 'aeuy';
$consonants = 'bcdfghjkmnpqrstvwxyz';
if ($strength >= 1) {
$consonants .= strtoupper($consonants);
}
if ($strength >= 2) {
$vowels .= strtoupper($vowels);
}
// excludes the numbers 0 and 1 because they can be mistaken for letters.
if ($strength >= 3) {
$consonants .= '23456789';
}
if ($strength >= 4) {
$consonants .= '@$%^';
}
$password = '';
$alt = rand() % 2;
for ($i = 0; $i < $length; $i++) {
if ($alt == 1) {
$password .= $consonants[ (rand() % strlen($consonants)) ];
$alt = 0;
} else {
$password .= $vowels[ (rand() % strlen($vowels)) ];
$alt = 1;
}
}
return $password;
}
| P4Cms_User::getAggregateRole | ( | P4Cms_Acl $ | acl = null | ) |
Generate a single role that inherits from all of the roles that this user has and register it with the acl temporarily (the role is not saved).
This allows us to specify a single role when checking if the user is allowed access to a given resource/privilege.
| P4Cms_Acl | null | $acl | optional - the acl to check against. defaults to the currently active acl. |
| P4Cms_User_Exception | if the user has no roles. |
{
$acl = $acl ?: P4Cms_Acl::fetchActive();
// can't get aggregate role if no roles.
$roles = $this->getRoles();
if (count($roles) == 0) {
throw new P4Cms_User_Exception(
"Cannot get aggregate role for a user with no roles."
);
}
// no need to aggregate if user has one role.
if (count($roles) <= 1) {
return $roles->first()->getId();
}
// generate unique name.
$i = 0;
$roles = $roles->invoke('getId');
$roleId = $this->getId() . "-" . implode('-', $roles);
while ($acl->hasRole($roleId)) {
$roleId = $this->getId() . "-" . implode('-', $roles) . "-" . ++$i;
}
// register role as super if any of the partial roles is super
foreach ($roles as $role) {
if (P4Cms_Acl_Role::isSuper($role)) {
P4Cms_Acl_Role::addSuperRole($roleId);
break;
}
}
// add role to acl, but don't save role.
$acl->addRole($roleId, $roles);
return $roleId;
}
| P4Cms_User::getAllowedPrivileges | ( | $ | resource, |
| P4Cms_Acl $ | acl = null |
||
| ) |
Return list of all privileges for which user has access to a given resource.
| P4Cms_Acl_Resource | string | $resource | the resource to check access to. |
| P4Cms_Acl | null | $acl | optional - the acl to check against. defaults to the currently active acl. |
{
$acl = $acl ?: P4Cms_Acl::fetchActive();
$roles = $this->getRoles()->toArray(true);
$privileges = array();
// user is allowed access if any of the roles are.
foreach ($roles as $role) {
$privileges = array_merge(
$privileges,
$acl->getAllowedPrivileges($role, $resource)
);
}
return array_unique($privileges);
}
| P4Cms_User::getEmail | ( | ) |
Return the user's email-address.
{
return $this->_getP4User()->getEmail();
}
| P4Cms_User::getFullName | ( | ) |
Return the user's full name.
{
return $this->_getP4User()->getFullName();
}
| P4Cms_User::getPassword | ( | ) |
Get the in-memory password (if one is set).
{
return $this->_getP4User()->getPassword();
}
| P4Cms_User::getPersonalAdapter | ( | ) |
Get the personalized record storage adapter for this user.
| P4Cms_User_Exception | if no personal adapter has been set. |
{
// balk if no adapter set.
if (!$this->_personalAdapter instanceof P4Cms_Record_Adapter) {
throw new P4Cms_User_Exception(
"Cannot get personal storage adapter. No personal adapter has been set."
);
}
return $this->_personalAdapter;
}
| P4Cms_User::getRoles | ( | ) |
Get the roles that this user belongs to.
Caches the results of P4Cms_Acl_Role::fetchAll().
{
// if user is un-identified, user belongs to anonymous role
if ($this->isAnonymous()) {
$role = new P4Cms_Acl_Role;
$role->setId(P4Cms_Acl_Role::ROLE_ANONYMOUS);
$roles = new P4Cms_Model_Iterator;
$roles[] = $role;
return $roles;
}
// for other users, roles are cached based on the adapter and user id
$adapter = $this->getAdapter();
$userId = $this->getId();
$cacheKey = spl_object_hash($adapter) . md5($userId);
// load the user roles (but only fetch them once)
if (!array_key_exists($cacheKey, static::$_rolesCache)) {
// fetch roles that user is a member of
$roles = P4Cms_Acl_Role::fetchAll(
array(P4Cms_Acl_Role::FETCH_BY_MEMBER => $userId),
$adapter
);
static::$_rolesCache[$cacheKey] = $roles;
}
return static::$_rolesCache[$cacheKey];
}
| static P4Cms_User::hasActive | ( | ) | [static] |
Determine if there is an active user.
{
try {
static::fetchActive();
return true;
} catch (Exception $e) {
return false;
}
}
| P4Cms_User::hasPersonalAdapter | ( | ) |
Determine if a personalized adapter has been set for this user.
{
try {
$this->getPersonalAdapter();
return true;
} catch (P4Cms_User_Exception $e) {
return false;
}
}
| P4Cms_User::isAdministrator | ( | ) |
Determine if this user has administrator role.
{
return in_array(P4Cms_Acl_Role::ROLE_ADMINISTRATOR, $this->getRoles()->invoke('getId'));
}
| P4Cms_User::isAllowed | ( | $ | resource, |
| $ | privilege = null, |
||
| P4Cms_Acl $ | acl = null |
||
| ) |
Determine if this user is allowed to access a particular resource and (optionally) a particular privilege on the resource.
| P4Cms_Acl_Resource | string | $resource | the resource to check access to. |
| P4Cms_Acl_Privilege | string | null | $privilege | optional - the privilege to check. |
| P4Cms_Acl | null | $acl | optional - the acl to check against. defaults to the currently active acl. |
p4cms.acl.users.privileges Gathers the resource privileges for authorization checks, or for presentation by the User module. P4Cms_Acl_Resource $resource The resource that must be checked for appropriate privileges.
Reimplemented in Cron_Model_User.
{
$acl = $acl ?: P4Cms_Acl::fetchActive();
// user is allowed access if any of the roles are.
foreach ($this->getRoles() as $role) {
try {
if ($acl->isAllowed($role, $resource, $privilege)) {
return true;
}
} catch (Zend_Acl_Exception $e) {
// acl throws if the resource doesn't exist, but
// we don't consider this a throw-able offense here.
// we do however treat it as permission denied.
}
}
return false;
}
| P4Cms_User::isAnonymous | ( | ) |
Determine if this user is anonymous (has no id).
{
return !(bool) strlen($this->getId());
}
| P4Cms_User::isMember | ( | ) |
Determine if this user has member role.
{
return in_array(P4Cms_Acl_Role::ROLE_MEMBER, $this->getRoles()->invoke('getId'));
}
| P4Cms_User::isPassword | ( | $ | password | ) |
Test if the given password is correct for this user.
| string | $password | the password to test. |
{
return $this->_getP4User()->isPassword($password);
}
| P4Cms_User::save | ( | ) |
Save this user entry.
{
// save the user spec.
$this->_getP4User()->save();
return $this;
}
| static P4Cms_User::setActive | ( | P4Cms_User $ | user | ) | [static] |
Set the active user.
| P4Cms_User | $user | the user model instance to make active. |
{
static::$_activeUser = $user;
}
| P4Cms_User::setAdapter | ( | P4Cms_Record_Adapter $ | adapter | ) |
Overrides parent to set adapter's connection for associated P4_User in addition.
| P4Cms_Record_Adapter | $adapter | the adapter to use for this instance. |
Reimplemented from P4Cms_Record_Connected.
{
$this->_getP4User()->setConnection($adapter->getConnection());
return parent::setAdapter($adapter);
}
| P4Cms_User::setEmail | ( | $ | ) |
Set the user's email-address.
| string | null | the user's email address |
{
$this->_getP4User()->setEmail($email);
return $this;
}
| P4Cms_User::setFullName | ( | $ | name | ) |
Set the user's full name.
| string | null | $name | the user's full name |
{
$this->_getP4User()->setFullName($name);
return $this;
}
| P4Cms_User::setId | ( | $ | id | ) |
Set the user id - extended to proxy to p4 user.
| string | int | null | $id | the identifier of this record. |
Reimplemented from P4Cms_Model.
{
$this->_getP4User()->setId($id);
return parent::setId($id);
}
| P4Cms_User::setPassword | ( | $ | newPassword, |
| $ | oldPassword = null |
||
| ) |
Set the user's password to the given password.
Does not take effect until save() is called.
| string | null | $newPassword | the new password string or null to clear in-memory password. |
| string | $oldPassword | optional - existing password. |
{
$this->_getP4User()->setPassword($newPassword, $oldPassword);
return $this;
}
| P4Cms_User::setPersonalAdapter | ( | P4Cms_Record_Adapter $ | adapter = null | ) |
Set the personal storage adapter for this user.
| P4Cms_Record_Adapter | $adapter | the personal adapter |
{
$this->_personalAdapter = $adapter;
return $this;
}
P4Cms_User::$_acl = null [static, protected] |
P4Cms_User::$_activeUser = null [static, protected] |
P4Cms_User::$_fields [static, protected] |
array(
'fullName' => array(
'accessor' => 'getFullName',
'mutator' => 'setFullName'
),
'email' => array(
'accessor' => 'getEmail',
'mutator' => 'setEmail'
),
'password' => array(
'accessor' => 'getPassword',
'mutator' => 'setPassword'
)
)
Reimplemented from P4Cms_Model.
P4Cms_User::$_idField = 'id' [static, protected] |
Reimplemented from P4Cms_Model.
P4Cms_User::$_p4User = null [protected] |
P4Cms_User::$_personalAdapter = null [protected] |
P4Cms_User::$_rolesCache = array() [static, protected] |
| const P4Cms_User::FETCH_BY_NAME = 'name' |
| const P4Cms_User::FETCH_MAXIMUM = 'maximum' |
| const P4Cms_User::FETCH_SYSTEM_USER = 'systemUser' |