PHP Class Piwik\Plugins\UsersManager\API

You can create users via "addUser", update existing users via "updateUser" and delete users via "deleteUser". There are many ways to list users based on their login "getUser" and "getUsers", their email "getUserByEmail", or which users have permission (view or admin) to access the specified websites "getUsersWithSiteAccess". Existing Permissions are listed given a login via "getSitesAccessFromUser", or a website ID via "getUsersAccessFromSite", or you can list all users and websites for a given permission via "getUsersSitesFromAccess". Permissions are set and updated via the method "setUserAccess". See also the documentation about Managing Users in Piwik.

Inheritance: extends Piwik\Plugin\API

Show file Open project: piwik/piwik Class Usage Examples

Public Methods

Method	Description
__construct ( Model $model, Piwik\Plugins\UsersManager\UserAccessFilter $filter, Password $password )
addUser ( $userLogin, $password, $email, $alias = false, $_isPasswordHashed = false )	Add a user in the database.
createTokenAuth ( string $userLogin ) : string	Generates a new random authentication token.
deleteUser ( string $userLogin ) : boolean	Delete a user and all its access, given its login.
getAllUsersPreferences ( array $preferenceNames ) : array	Returns an array of Preferences
getInstance ( ) : API	You can create your own Users Plugin to override this class.
getSitesAccessFromUser ( string $userLogin ) : array	For each website ID, returns the access level of the given $userLogin.
getTokenAuth ( string $userLogin, string $md5Password ) : string	Returns the user's API token.
getUser ( string $userLogin ) : array	Returns the user information (login, password hash, alias, email, date_registered, etc.)
getUserByEmail ( string $userEmail ) : array	Returns the user information (login, password hash, alias, email, date_registered, etc.)
getUserLoginFromUserEmail ( string $userEmail ) : boolean	Returns the first login name of an existing user that has the given email address. If no user can be found for this user an error will be returned.
getUserPreference ( string $userLogin, string $preferenceName ) : boolean \| string	Gets a user preference
getUsers ( string $userLogins = '' ) : array	Returns the list of all the users
getUsersAccessFromSite ( integer $idSite ) : array	For each user, returns his access level for the given $idSite.
getUsersHavingSuperUserAccess ( ) : array	Returns a list of all Super Users containing there userLogin and email address.
getUsersLogin ( ) : array	Returns the list of all the users login
getUsersSitesFromAccess ( $access ) : array	For each user, returns the list of website IDs where the user has the supplied $access level.
getUsersWithSiteAccess ( $idSite, $access )
hasSuperUserAccess ( ) : boolean	Detect whether the current user has super user access or not.
initUserPreferenceWithDefault ( string $userLogin, string $preferenceName )	Sets a user preference in the DB using the preference's default value.
regenerateTokenAuth ( string $userLogin )	Regenerate the token_auth associated with a user.
setSuperUserAccess ( string $userLogin, boolean \| integer $hasSuperUserAccess )	Enable or disable Super user access to the given user login. Note: When granting Super User access all previous permissions of the user will be removed as the user gains access to everything.
setUserAccess ( string $userLogin, string $access, integer \| array $idSites ) : boolean	Set an access level to a given user for a list of websites ID.
setUserPreference ( string $userLogin, string $preferenceName, string $preferenceValue ) : void	Sets a user preference
updateUser ( $userLogin, $password = false, $email = false, $alias = false, $_isPasswordHashed = false )	Updates a user in the database.
userEmailExists ( string $userEmail ) : boolean	Returns true if user with given email (userEmail) is known in the database, or the Super User
userExists ( string $userLogin ) : boolean	Returns true if the given userLogin is known in the database

Private Methods

Method	Description
checkAccessType ( $access )
checkEmail ( $email )
checkLogin ( $userLogin )
checkUserEmailExists ( string $userEmail )	Throws an exception is the user email cannot be found
checkUserExists ( string $userLogin )	Throws an exception is the user login doesn't exist
checkUserHasNotSuperUserAccess ( $userLogin )
checkUserIsNotAnonymous ( $userLogin )
enrichUser ( $user )
enrichUsers ( $users )
getCleanAlias ( $alias, $userLogin )
getDefaultUserPreference ( $preferenceName, $login )
getPreferenceId ( $login, $preference )
getPreferenceValue ( $userLogin, $preferenceName )
isUserTheOnlyUserHavingSuperUserAccess ( $userLogin )

Method Details

__construct() public method

public __construct ( Model $model, Piwik\Plugins\UsersManager\UserAccessFilter $filter, Password $password )
$model	Model
$filter	Piwik\Plugins\UsersManager\UserAccessFilter
$password	Piwik\Auth\Password

addUser() public method

A user is defined by - a login that has to be unique and valid - a password that has to be valid - an alias - an email that has to be in a correct format

createTokenAuth() public method

Generates a new random authentication token.

public createTokenAuth ( string $userLogin ) : string
$userLogin	string	Login
return	string

deleteUser() public method

Delete a user and all its access, given its login.

public deleteUser ( string $userLogin ) : boolean
$userLogin	string	the user login.
return	boolean	true on success

getAllUsersPreferences() public method

Returns an array of Preferences

public getAllUsersPreferences ( array $preferenceNames ) : array
$preferenceNames	array	array of preference names
return	array

getInstance() public static method

Example of how you would overwrite the UsersManager_API with your own class: Call the following in your plugin __construct() for example: StaticContainer::getContainer()->set('UsersManager_API', \Piwik\Plugins\MyCustomUsersManager\API::getInstance());

public static getInstance ( ) : API
return	API

getSitesAccessFromUser() public method

If the user doesn't have any access to a website ('noaccess'), this website will not be in the returned array. If the user doesn't have any access, the returned array will be an empty array.

public getSitesAccessFromUser ( string $userLogin ) : array
$userLogin	string	User that has to be valid
return	array	The returned array has the format array( idsite1 => 'view', idsite2 => 'admin', idsite3 => 'view', ... )

getTokenAuth() public method

If the username/password combination is incorrect an invalid token will be returned.

public getTokenAuth ( string $userLogin, string $md5Password ) : string
$userLogin	string	Login
$md5Password	string	hashed string of the password (using current hash function; MD5-named for historical reasons)
return	string

getUser() public method

Returns the user information (login, password hash, alias, email, date_registered, etc.)

public getUser ( string $userLogin ) : array
$userLogin	string	the user login
return	array	the user information

getUserByEmail() public method

Returns the user information (login, password hash, alias, email, date_registered, etc.)

public getUserByEmail ( string $userEmail ) : array
$userEmail	string	the user email
return	array	the user information

getUserLoginFromUserEmail() public method

Returns the first login name of an existing user that has the given email address. If no user can be found for this user an error will be returned.

public getUserLoginFromUserEmail ( string $userEmail ) : boolean
$userEmail	string
return	boolean	true if the user is known

getUserPreference() public method

Gets a user preference

public getUserPreference ( string $userLogin, string $preferenceName ) : boolean \| string
$userLogin	string
$preferenceName	string
return	boolean \| string

getUsers() public method

Returns the list of all the users

public getUsers ( string $userLogins = '' ) : array
$userLogins	string	Comma separated list of users to select. If not specified, will return all users
return	array	the list of all the users

getUsersAccessFromSite() public method

If a user doesn't have any access to the $idSite ('noaccess'), the user will not be in the returned array.

public getUsersAccessFromSite ( integer $idSite ) : array
$idSite	integer	website ID
return	array	The returned array has the format array( login1 => 'view', login2 => 'admin', login3 => 'view', ... )

getUsersHavingSuperUserAccess() public method

Returns a list of all Super Users containing there userLogin and email address.

public getUsersHavingSuperUserAccess ( ) : array
return	array

getUsersLogin() public method

Returns the list of all the users login

public getUsersLogin ( ) : array
return	array	the list of all the users login

getUsersSitesFromAccess() public method

If a user doesn't have the given $access to any website IDs, the user will not be in the returned array.

public getUsersSitesFromAccess ( $access ) : array
return	array	The returned array has the format array( login1 => array ( idsite1,idsite2), login2 => array(idsite2), ... )

getUsersWithSiteAccess() public method

public getUsersWithSiteAccess ( $idSite, $access )

hasSuperUserAccess() public method

Detect whether the current user has super user access or not.

public hasSuperUserAccess ( ) : boolean
return	boolean

initUserPreferenceWithDefault() public method

Sets a user preference in the DB using the preference's default value.

public initUserPreferenceWithDefault ( string $userLogin, string $preferenceName )
$userLogin	string
$preferenceName	string

regenerateTokenAuth() public method

If the user currently logged in regenerates his own token, he will be logged out. His previous token will be rendered invalid.

public regenerateTokenAuth ( string $userLogin )
$userLogin	string

setSuperUserAccess() public method

Enable or disable Super user access to the given user login. Note: When granting Super User access all previous permissions of the user will be removed as the user gains access to everything.

public setSuperUserAccess ( string $userLogin, boolean \| integer $hasSuperUserAccess )
$userLogin	string	the user login.
$hasSuperUserAccess	boolean \| integer	true or '1' to grant Super User access, false or '0' to remove Super User access.

setUserAccess() public method

If access = 'noaccess' the current access (if any) will be deleted. If access = 'view' or 'admin' the current access level is deleted and updated with the new value.

public setUserAccess ( string $userLogin, string $access, integer \| array $idSites ) : boolean
$userLogin	string	The user login
$access	string	Access to grant. Must have one of the following value : noaccess, view, admin
$idSites	integer \| array	The array of idSites on which to apply the access level for the user. If the value is "all" then we apply the access level to all the websites ID for which the current authentificated user has an 'admin' access.
return	boolean	true on success

setUserPreference() public method

Sets a user preference

public setUserPreference ( string $userLogin, string $preferenceName, string $preferenceValue ) : void
$userLogin	string
$preferenceName	string
$preferenceValue	string
return	void

updateUser() public method

Only login and password are required (case when we update the password). If the password changes and the user has an old token_auth (legacy MD5 format) associated, the token will be regenerated. This could break a user's API calls.

See also: addUser() for all the parameters

public updateUser ( $userLogin, $password = false, $email = false, $alias = false, $_isPasswordHashed = false )

userEmailExists() public method

Returns true if user with given email (userEmail) is known in the database, or the Super User

public userEmailExists ( string $userEmail ) : boolean
$userEmail	string
return	boolean	true if the user is known

userExists() public method

Returns true if the given userLogin is known in the database

public userExists ( string $userLogin ) : boolean
$userLogin	string
return	boolean	true if the user is known