UserManager
in package
User Manager Model
Handles all user-related database operations including CRUD operations, password hashing and verification, email verification, role management, soft deletion, and user search/pagination functionality. This class provides a unified data access layer for the USERS table.
Tags
Table of Contents
Properties
- $pdo : PDO
- PDO database connection instance
Methods
- __construct() : mixed
- Constructor - Initialize the UserManager
- anonymizeUser() : bool
- Anonymize a user record by replacing all personal data with placeholders
- countActiveUsersByRole() : int
- Count active (non-deleted, non-blocked) users for a given role
- countDeletedUsers() : int
- Count soft-deleted users matching the given filters
- countUsers() : int
- Count active (non-deleted) users matching the given filters
- createUser() : int|false
- Create a new user without email verification
- createUserWithVerification() : array{user_id: int, token: string}|false
- Create a new user with an email verification token
- deleteUser() : bool
- Permanently delete a user record
- emailExists() : bool
- Check if an email address already exists in the database
- findUserByEmail() : array<string, mixed>|false
- Find a user by email address
- generateVerificationToken() : string
- Generate a cryptographically secure 64-character hexadecimal token
- getDeletedUsers() : array<int, array<string, mixed>>
- Retrieve a paginated list of soft-deleted users
- getExpiredDeletedUsers() : array<int, array<string, mixed>>
- Retrieve soft-deleted users whose grace period has expired
- getUserById() : array<string, mixed>|false
- Retrieve a single user by their primary key
- getUserRoleById() : string
- Retrieve the role of a user by their primary key
- getUsers() : array<int, array<string, mixed>>
- Retrieve a paginated list of active (non-deleted) users
- hashPassword() : string
- Hash a password using the default PHP hashing algorithm (bcrypt)
- isEmailVerified() : bool
- Check whether a user's email address has been verified
- resendVerificationToken() : string|false
- Generate and persist a new email verification token for a user
- restoreUser() : bool
- Restore a soft-deleted user account
- setBlockStatus() : bool
- Block or unblock a user account
- softDeleteUser() : bool
- Soft-delete a user account (30-day grace period)
- updateEmail() : bool
- Update a user's email address
- updateFirstName() : void
- Update a user's first name
- updateLastName() : void
- Update a user's last name
- updatePassword() : bool
- Update a user's password
- updateUser() : bool
- Update user profile information (excluding password)
- updateUserRole() : bool
- Update the role of a user
- updateUserStatus() : void
- Update a user's academic status
- verifyEmailToken() : array{success: bool, message?: string, user_id?: int}
- Verify an email verification token and activate the user account
- verifyPassword() : bool
- Verify a password against its hash
Properties
$pdo
PDO database connection instance
private
PDO
$pdo
Methods
__construct()
Constructor - Initialize the UserManager
public
__construct() : mixed
Retrieves the database connection from the Database singleton.
anonymizeUser()
Anonymize a user record by replacing all personal data with placeholders
public
anonymizeUser(int $user_id) : bool
Replaces email, first_name, last_name, password and verification token with non-identifying values. The row itself is preserved for referential and statistical integrity.
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
bool —True on success, false otherwise
countActiveUsersByRole()
Count active (non-deleted, non-blocked) users for a given role
public
countActiveUsersByRole(string $role) : int
Used to enforce the minimum-one-admin / minimum-one-super_admin rule before performing a destructive action (soft_delete, demote, block).
Parameters
- $role : string
-
The role to count ('admin' or 'super_admin')
Tags
Return values
int —Number of active users with that role
countDeletedUsers()
Count soft-deleted users matching the given filters
public
countDeletedUsers(string $role, string $search) : int
Parameters
- $role : string
-
Role filter: 'admin', 'user', 'super_admin', or 'all'
- $search : string
-
Partial string to search across name and email
Tags
Return values
int —Total number of matching soft-deleted users
countUsers()
Count active (non-deleted) users matching the given filters
public
countUsers(bool $showBlocked, string $role, string $search) : int
Mirrors the filtering logic of getUsers() without pagination.
Parameters
- $showBlocked : bool
-
When true, count only blocked users; otherwise only non-blocked users
- $role : string
-
Role filter: 'admin', 'user', 'super_admin', or 'all'
- $search : string
-
Partial string to search across name and email (empty = no filter)
Tags
Return values
int —Total number of matching users
createUser()
Create a new user without email verification
public
createUser(string $last_name, string $first_name, string $user_status, string $email, string $password) : int|false
Inserts a new user record with a hashed password. The password is automatically hashed before storage.
Parameters
- $last_name : string
-
User's last name
- $first_name : string
-
User's first name
- $user_status : string
-
User's academic status (BUT 1, BUT 2, BUT 3, Personnel Enseignant)
- $email : string
-
User's email address
- $password : string
-
User's password (plain text, will be hashed)
Tags
Return values
int|false —The new user ID on success, false otherwise
createUserWithVerification()
Create a new user with an email verification token
public
createUserWithVerification(string $last_name, string $first_name, string $user_status, string $email, string $password) : array{user_id: int, token: string}|false
Inserts a user row that includes a 64-character hex verification token and an expiry timestamp set 24 hours in the future.
Parameters
- $last_name : string
-
User's last name
- $first_name : string
-
User's first name
- $user_status : string
-
User's academic status
- $email : string
-
User's email address
- $password : string
-
User's password (plain text, will be hashed)
Tags
Return values
array{user_id: int, token: string}|false —Associative array with the new user_id and the raw verification token, or false on failure
deleteUser()
Permanently delete a user record
public
deleteUser(int $user_id) : bool
This operation cannot be undone. Use softDeleteUser() for a reversible approach that respects the 30-day grace period.
Parameters
- $user_id : int
-
The ID of the user to delete
Tags
Return values
bool —True if deletion was successful, false otherwise
emailExists()
Check if an email address already exists in the database
public
emailExists(string $email) : bool
Useful for registration validation to prevent duplicate accounts.
Parameters
- $email : string
-
The email address to check
Tags
Return values
bool —True if the email exists, false otherwise
findUserByEmail()
Find a user by email address
public
findUserByEmail(string $email) : array<string, mixed>|false
Searches for a user in the database using their email address. Returns all fields required for authentication and session setup.
Parameters
- $email : string
-
The email address to search for
Tags
Return values
array<string, mixed>|false —Array containing user data if found, false otherwise
generateVerificationToken()
Generate a cryptographically secure 64-character hexadecimal token
public
generateVerificationToken() : string
Used for email verification and password reset flows.
Return values
string —A 64-character lowercase hexadecimal string
getDeletedUsers()
Retrieve a paginated list of soft-deleted users
public
getDeletedUsers(int $limit, int $offset, string $role, string $search) : array<int, array<string, mixed>>
Supports optional filtering by role and full-text search.
Parameters
- $limit : int
-
Maximum number of rows to return
- $offset : int
-
Number of rows to skip
- $role : string
-
Role filter: 'admin', 'user', 'super_admin', or 'all'
- $search : string
-
Partial string to search across name and email
Tags
Return values
array<int, array<string, mixed>> —List of matching soft-deleted user rows
getExpiredDeletedUsers()
Retrieve soft-deleted users whose grace period has expired
public
getExpiredDeletedUsers(int $days) : array<int, array<string, mixed>>
Returns all user rows where deleted_at is older than the given number of days. Used by the nightly cron job to identify accounts to anonymize.
Parameters
- $days : int
-
Number of days after which a soft-deleted account is considered expired
Tags
Return values
array<int, array<string, mixed>> —List of expired user rows
getUserById()
Retrieve a single user by their primary key
public
getUserById(int $user_id) : array<string, mixed>|false
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
array<string, mixed>|false —User row if found, false otherwise
getUserRoleById()
Retrieve the role of a user by their primary key
public
getUserRoleById(int $user_id) : string
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
string —The user's role (e.g. 'user', 'admin', 'super_admin'), or empty string if not found
getUsers()
Retrieve a paginated list of active (non-deleted) users
public
getUsers(int $limit, int $offset, bool $showBlocked, string $role, string $search) : array<int, array<string, mixed>>
Supports optional filtering by blocked status, role, and a full-text search across last_name, first_name and email.
Parameters
- $limit : int
-
Maximum number of rows to return
- $offset : int
-
Number of rows to skip (pagination)
- $showBlocked : bool
-
When true, return only blocked users; otherwise only non-blocked users
- $role : string
-
Role filter: 'admin', 'user', 'super_admin', or 'all'
- $search : string
-
Partial string to search across name and email (empty = no filter)
Tags
Return values
array<int, array<string, mixed>> —List of matching user rows
hashPassword()
Hash a password using the default PHP hashing algorithm (bcrypt)
public
hashPassword(string $password) : string
Parameters
- $password : string
-
The plain text password to hash
Return values
string —The hashed password
isEmailVerified()
Check whether a user's email address has been verified
public
isEmailVerified(int $user_id) : bool
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
bool —True if the email is verified, false if not or user not found
resendVerificationToken()
Generate and persist a new email verification token for a user
public
resendVerificationToken(int $user_id) : string|false
Replaces any previously stored token and extends the expiry by 24 hours.
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
string|false —The new 64-character token on success, false on failure
restoreUser()
Restore a soft-deleted user account
public
restoreUser(int $user_id) : bool
Clears the deleted_at timestamp, making the account active again.
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
bool —True on success, false otherwise
setBlockStatus()
Block or unblock a user account
public
setBlockStatus(int $user_id, int $status) : bool
Parameters
- $user_id : int
-
The user's primary key
- $status : int
-
1 to block, 0 to unblock
Tags
Return values
bool —True on success, false otherwise
softDeleteUser()
Soft-delete a user account (30-day grace period)
public
softDeleteUser(int $user_id) : bool
Sets the deleted_at timestamp to the current time. The account can be restored within 30 days before the cron job anonymizes it permanently.
Parameters
- $user_id : int
-
The user's primary key
Tags
Return values
bool —True on success, false otherwise
updateEmail()
Update a user's email address
public
updateEmail(int $user_id, string $newEmail) : bool
Checks that the new email is not already in use before updating. Returns true when the email was changed, false when it is already taken.
Parameters
- $user_id : int
-
The ID of the user
- $newEmail : string
-
The new email address
Return values
bool —True if the email was updated, false if already in use
updateFirstName()
Update a user's first name
public
updateFirstName(int $user_id, string $newFirstName) : void
Parameters
- $user_id : int
-
The ID of the user
- $newFirstName : string
-
The new first name
Tags
updateLastName()
Update a user's last name
public
updateLastName(int $user_id, string $newLastName) : void
Parameters
- $user_id : int
-
The ID of the user
- $newLastName : string
-
The new last name
Tags
updatePassword()
Update a user's password
public
updatePassword(int $user_id, string $new_password) : bool
The new password is automatically hashed before storage.
Parameters
- $user_id : int
-
The ID of the user
- $new_password : string
-
The new password in plain text
Tags
Return values
bool —True if the update was successful, false otherwise
updateUser()
Update user profile information (excluding password)
public
updateUser(int $user_id, string $last_name, string $first_name, string $user_status, string $email) : bool
Parameters
- $user_id : int
-
The ID of the user to update
- $last_name : string
-
New last name
- $first_name : string
-
New first name
- $user_status : string
-
New academic status
- $email : string
-
New email address
Tags
Return values
bool —True if the update was successful, false otherwise
updateUserRole()
Update the role of a user
public
updateUserRole(int $user_id, string $role) : bool
Parameters
- $user_id : int
-
The user's primary key
- $role : string
-
The new role ('user', 'admin', 'super_admin')
Tags
Return values
bool —True on success, false otherwise
updateUserStatus()
Update a user's academic status
public
updateUserStatus(int $user_id, string $userStatus) : void
Parameters
- $user_id : int
-
The ID of the user
- $userStatus : string
-
The new academic status
Tags
verifyEmailToken()
Verify an email verification token and activate the user account
public
verifyEmailToken(string $token) : array{success: bool, message?: string, user_id?: int}
Looks up the user by token, then:
- Returns a failure result if the token is invalid or already verified.
- Deletes the user row and returns an 'expired' result if the token has passed its expiry date.
- Marks the account as verified and clears the token on success.
Parameters
- $token : string
-
The raw 64-character verification token
Tags
Return values
array{success: bool, message?: string, user_id?: int} —Result map
verifyPassword()
Verify a password against its hash
public
verifyPassword(string $password, string $hashedPassword) : bool
Compares a plain text password with its hashed version.
Parameters
- $password : string
-
The plain text password to verify
- $hashedPassword : string
-
The hashed password to compare against
Return values
bool —True if the password matches, false otherwise