Users extends AppModel
User management
Table of Contents
Methods
| __construct() | Initialize Users |
| add() | Adds the user record to the system |
| addOtp() | Adds the one-time password record to the system so we can ensure it is not used again. |
| auth() | Checks to ensure that the user specified can be authenticated |
| checkPassword() | Verifies whether or not the given plain-text password produces the supplied hash. |
| delete() | Permanently deletes a user record from the system. USE WITH EXTREME CAUTION |
| edit() | Edits the user record in the system |
| get() | Fetches a user |
| getAllByEmail() | Fetches a list of users |
| getByEmail() | Fetches a user |
| getByUsername() | Fetches a user |
| getOtp() | Returns the one-time password record if it exists |
| getOtpModes() | Return all One-time-password modes supported by the system |
| hashPassword() | Computes an HMAC sha-256 hash of the given password, then hashes that using the best hashing algorithm available on the system |
| login() | Attempts to authenticate the given user and initialize a session with that user's ID. |
| logout() | Logs the user out by terminating the session |
| queryByEmail() | Partially constructs the query fetching users by email |
| requiredOtpMode() | Fetches the one-time password mode required to authenticate this user |
| validateClientsExist() | Validates that at least one client is assigned to this user |
| validateLoginAttempts() | Validates whether the user has made too many failed attempts to login |
| validateOtp() | Validates the given OTP against the given user |
| validatePasswordEquals() | Validates the given password matches the one on record |
| validateTwoFactorKey() | Validates the user's 'two_factor_key' |
| validateTwoFactorMode() | Validates the user's 'two_factor_mode' field |
| validateUniqueUser() | Validates the given username is unique across all users, besides $user_id |
| validateUser() | Validate user information for add or edit |
| adjustInput() | Adjusts input for user creation/editing/validation |
| formatList() | Format a list of items with proper grammar (e.g., "a, b, and c") |
| getPasswordErrorMessage() | Get the appropriate password error message based on the password format |
| getRules() | Returns the rule set for adding/editing users |
| parsePasswordRule() | Parse a custom password regex rule and return a human-readable description |
Methods
__construct()
Initialize Users
public
__construct() : mixed
add()
Adds the user record to the system
public
add(array<string|int, mixed> $vars) : int
Parameters
- $vars : array<string|int, mixed>
-
An array of user info including:
- username The username for this user. Must be unique across all companies for this installation.
- new_password The password for this user
- confirm_password The password for this user
- recovery_email The email to which password reset emails should be sent
- two_factor_mode The two factor authentication mode 'none', 'motp', 'totp' (optional, default 'none')
- two_factor_key The two factor authentication key (optional, default null)
- two_factor_pin The two factor authentication pin (optional, default null)
Return values
int —The ID of the user created, void on error
addOtp()
Adds the one-time password record to the system so we can ensure it is not used again.
public
addOtp(int $user_id, string $otp) : mixed
Parameters
- $user_id : int
-
The ID of the user to record the one-time password for
- $otp : string
-
The one-time password to record
auth()
Checks to ensure that the user specified can be authenticated
public
auth(string $username, array<string|int, mixed> $vars[, string $type = 'any' ]) : bool
Parameters
- $username : string
-
The ID or username of the user to authenticate
- $vars : array<string|int, mixed>
-
an array of authentication info including:
- username The username of the user attempting to log in
- password The password of the user attempting to log in
- $type : string = 'any'
-
The type of user to authenticate:
- any Will check any type
- staff Check staff type only
- client Check client type only
- contact Check contact type only
Return values
bool —True if the user can be authenticated, false otherwise
checkPassword()
Verifies whether or not the given plain-text password produces the supplied hash.
public
checkPassword(string $password, string $stored_hash[, string $algorithm = null ]) : bool
Parameters
- $password : string
-
The password to validate
- $stored_hash : string
-
The hash to verify the password against
- $algorithm : string = null
-
The algorithm to use for validating the password
Return values
bool —True if the password is good, false otherwise
delete()
Permanently deletes a user record from the system. USE WITH EXTREME CAUTION
public
delete(int $user_id) : mixed
Parameters
- $user_id : int
-
The ID of the user to delete
edit()
Edits the user record in the system
public
edit(int $user_id, array<string|int, mixed> $vars[, bool $validate_pass = false ]) : mixed
Parameters
- $user_id : int
-
The ID of the user to edit
- $vars : array<string|int, mixed>
-
An array of user info including:
- username The username for this user (optional)
- current_password The current password for this user (optional, required if $validate_pass is true)
- new_password The new password for this user (optional)
- confirm_password The new password for this user (optional, required if 'new_password' is given)
- recovery_email The email to which password reset emails should be sent
- two_factor_mode The two factor authentication mode 'none', 'motp', 'totp' (optional)
- two_factor_key The two factor authentication key (optional)
- two_factor_pin The two factor authentication pin (optional)
- otp The one-time-password to validate, required if two_factor_mode is something other than 'none' and $validate_pass is set to true
- verify Whether or not the email should be verified, overrides the company and client group settings (Only applies to users who use their email address as a username)
- $validate_pass : bool = false
-
Whether or not to validate the current_password before updating this user (optional, default false). If set will also attempt to validate the one-time-password.
get()
Fetches a user
public
get(int $user_id) : mixed
Parameters
- $user_id : int
-
The user ID to fetch
Tags
Return values
mixed —An stdClass object representing the user, or false if it does not exist
getAllByEmail()
Fetches a list of users
public
getAllByEmail(string $email) : array<string|int, mixed>
Parameters
- $email : string
-
The username email address to fetch
Return values
array<string|int, mixed> —A list of stdClass objects representing users
getByEmail()
Fetches a user
public
getByEmail(string $email) : mixed
Parameters
- $email : string
-
The username email address to fetch
Tags
Return values
mixed —An stdClass object representing the user, or false if it does not exist
getByUsername()
Fetches a user
public
getByUsername(string $username) : mixed
Parameters
- $username : string
-
The username to fetch
Tags
Return values
mixed —An stdClass object representing the user, or false if it does not exist
getOtp()
Returns the one-time password record if it exists
public
getOtp(int $user_id, string $otp) : mixed
Parameters
- $user_id : int
-
The ID of the user to fetch on
- $otp : string
-
The one-time password to search for
Tags
getOtpModes()
Return all One-time-password modes supported by the system
public
getOtpModes() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of key/value pairs consisting of the OTP mode (the key) and it's friendly name (the value)
hashPassword()
Computes an HMAC sha-256 hash of the given password, then hashes that using the best hashing algorithm available on the system
public
hashPassword(string $password) : string
Parameters
- $password : string
-
The password to hash
Return values
string —The hashed password
login()
Attempts to authenticate the given user and initialize a session with that user's ID.
public
login(Session $session, array<string|int, mixed> $vars) : int
Parameters
- $session : Session
- $vars : array<string|int, mixed>
-
An array of login information including:
- username The username of the user attempting to log in
- password The password of the user attempting to log in
- remember_me If "true" will set a cookie to remember the user's session on a subsequent visit
- otp The one-time password required to authenticate this user (required only if enabled for this user)
- ip_address The IP address of the user attempting to log in (determined automatically if not given)
Return values
int —The ID of the user authenticated, false on failure
logout()
Logs the user out by terminating the session
public
logout(Session $session) : mixed
Parameters
- $session : Session
queryByEmail()
Partially constructs the query fetching users by email
public
queryByEmail(string $email) : Record
Parameters
- $email : string
-
The username email address to fetch
Tags
Return values
Record —The partially constructed query Record object
requiredOtpMode()
Fetches the one-time password mode required to authenticate this user
public
requiredOtpMode(mixed $user) : mixed
Parameters
- $user : mixed
Return values
mixed —A string containing the type of OTP mode, false if the user does not exist or no mode is set
validateClientsExist()
Validates that at least one client is assigned to this user
public
validateClientsExist(int $user_id) : bool
Parameters
- $user_id : int
-
The ID of the user
Return values
bool —True if at least one client is assigned to this user, false otherwise
validateLoginAttempts()
Validates whether the user has made too many failed attempts to login
public
validateLoginAttempts(string $username, string $ip_address) : bool
Parameters
- $username : string
-
The username
- $ip_address : string
-
The IP address from which the login took place
Return values
bool —False if there has been too many failed login attempts, true otherwise
validateOtp()
Validates the given OTP against the given user
public
validateOtp(string $otp, stdClass $user) : bool
Parameters
- $otp : string
-
The one-time password required to authenticate this user (required only if enabled for this user)
- $user : stdClass
-
The stdClass object representation of the user to validate the OTP against
Return values
bool —True if the OTP validates, false otherwise
validatePasswordEquals()
Validates the given password matches the one on record
public
validatePasswordEquals(string $password, int $user_id) : bool
Parameters
- $password : string
-
The encrypted password to check
- $user_id : int
-
The user ID of the user to check against
Return values
bool —True if the passwords are equivalent, false otherwise
validateTwoFactorKey()
Validates the user's 'two_factor_key'
public
validateTwoFactorKey(string $key, string $mode) : mixed
Parameters
- $key : string
-
The two factor key
- $mode : string
-
The two factor mode
Tags
validateTwoFactorMode()
Validates the user's 'two_factor_mode' field
public
validateTwoFactorMode(string $mode) : bool
Parameters
- $mode : string
-
The two factor mode to check
Return values
bool —True if validated, false otherwise
validateUniqueUser()
Validates the given username is unique across all users, besides $user_id
public
validateUniqueUser(string $username, int $user_id) : bool
Parameters
- $username : string
-
The username to be validated against the user ID
- $user_id : int
-
A user ID
Return values
bool —True if the username is unique for all users (besides this $user_id), false otherwise
validateUser()
Validate user information for add or edit
public
validateUser(array<string|int, mixed> $vars[, bool $edit = false ][, bool $validate_pass = false ]) : bool
Parameters
- $vars : array<string|int, mixed>
-
An array of user info including:
- user_id The ID of the user for validating edits (optional)
- username The username for this user (optional)
- current_password The current password for this user (optional, required if $validate_pass is true)
- new_password The new password for this user (optional)
- confirm_password The new password for this user (optional, required if 'new_password' is given)
- two_factor_mode The two factor authentication mode 'none', 'motp', 'totp' (optional)
- two_factor_key The two factor authentication key (optional)
- two_factor_pin The two factor authentication pin (optional)
- otp The one-time-password to validate, required if two_factor_mode is something other than 'none' and $validate_pass is set to true
- $edit : bool = false
-
Whether this data is being validated for an edit (optional, default false)
- $validate_pass : bool = false
-
Whether or not to validate the current_password before updating this user (optional, default false). If set will also attempt to validate the one-time-password.
Return values
bool —True if the user info is valid, false otherwise
adjustInput()
Adjusts input for user creation/editing/validation
private
adjustInput(array<string|int, mixed> $vars[, bool $edit = false ]) : array<string|int, mixed>
Parameters
- $vars : array<string|int, mixed>
-
An array of user info including:
- username The username for this user (optional)
- current_password The current password for this user (optional, required if $validate_pass is true)
- new_password The new password for this user (optional)
- confirm_password The new password for this user (optional, required if 'new_password' is given)
- two_factor_mode The two factor authentication mode 'none', 'motp', 'totp' (optional)
- two_factor_key The two factor authentication key (optional)
- two_factor_pin The two factor authentication pin (optional)
- otp The one-time-password to validate, required if two_factor_mode is something other than 'none' and $validate_pass is set to true
- $edit : bool = false
-
Whether this data is being adjusted for an update (optional, default false)
Return values
array<string|int, mixed> —The adjust input data
formatList()
Format a list of items with proper grammar (e.g., "a, b, and c")
private
formatList(array<string|int, mixed> $items) : string
Parameters
- $items : array<string|int, mixed>
-
The items to format
Return values
string —The formatted list
getPasswordErrorMessage()
Get the appropriate password error message based on the password format
private
getPasswordErrorMessage(string $password_format, string $password_length, string $password_rule) : string
Parameters
- $password_format : string
-
The password format (any, any_no_space, alpha_num, alpha, num, custom)
- $password_length : string
-
The minimum password length
- $password_rule : string
-
The custom regex rule (used when format is 'custom')
Return values
string —The error message
getRules()
Returns the rule set for adding/editing users
private
getRules(array<string|int, mixed> $vars[, bool $edit = false ]) : array<string|int, mixed>
Parameters
- $vars : array<string|int, mixed>
-
An array of fields
- $edit : bool = false
-
True to get the rules pertaining to editing a user
Return values
array<string|int, mixed> —An array of user rules
parsePasswordRule()
Parse a custom password regex rule and return a human-readable description
private
parsePasswordRule(string $regex) : string
Parameters
- $regex : string
-
The regex pattern to parse
Return values
string —A human-readable description of the password requirements