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' |