UserController

Purpose and Scope

The UserController provides GraphQL mutations and queries for user account management, including creating, updating, and deleting user accounts, as well as password management operations. This controller implements the administrative and self-service user management functionality exposed through the GraphQL API.

For authentication operations (login, logout, 2FA), see AuthController. For user data model details and session management, see User Model and Sessions. For role and permission assignment, see RBAC System.

Sources: src/Controller/UserController.php1-176

---

Controller Overview

The UserController class is located at src/Controller/UserController.php and provides five main operations:

Operation	Type	Method	Permission	Description
List Users	Query	listUser	user.list	Query users with filtering (deprecated)
Add User	Mutation	addUser	user.add	Create a new user account
Update User	Mutation	updateUser	user.update	Update user profile fields
Update Password (Admin)	Mutation	updateUserPassword	user.changePassword	Change another user's password
Change Password (Self)	Mutation	changeUserPassword	(none)	Change own password
Delete User	Mutation	deleteUser	user.delete	Delete a user account

All operations are protected by authentication (#[Logged]) and/or specific permissions (#[Right]), with additional programmatic checks for administrator-only operations.

Sources: src/Controller/UserController.php22-175

---

Architecture and Dependencies

Diagram: UserController Architecture and Data Flow

The controller acts as a bridge between GraphQL operations and the underlying User model, enforcing authorization through both declarative annotations and programmatic checks.

Sources: src/Controller/UserController.php1-176 src/Input/User.php1-69 src/Model/User.php1-389

---

User Listing Query

The listUser query provides filtered user listing with role-based filtering. This query is deprecated - new code should use { app { users } } instead (see Root Query Type).

Implementation Details

The method at src/Controller/UserController.php33-44 implements the following logic:

1. Creates a base query with User::Query()->filters($filters)->sort($sort)
2. If the requesting user is not an Administrator, filters out all users with the Administrators role
3. Returns a Light\Db\Query object that the GraphQL engine can paginate

Administrator Filtering

Diagram: Administrator Filtering Logic in listUser

This ensures that non-administrators cannot see or enumerate administrator accounts through the listing API.

Sources: src/Controller/UserController.php33-44

---

User Creation (addUser)

The addUser mutation creates a new user account with role assignments. It requires the user.add permission.

GraphQL Mutation

Input Structure

The CreateUserInput type (defined in src/Input/User.php8-68) includes:

Field	Type	Required	Description
username	String	Yes	Unique username
password	String	Yes	Plain text password (will be hashed)
first_name	String	Yes	User's first name
last_name	String	No	User's last name
email	String	Yes	Email address
phone	String	No	Phone number
addr1, addr2, addr3	String	No	Address fields
birthdate	String	No	Date of birth
join_date	String	No	Account creation date (defaults to today)
expiry_date	String	No	Account expiration date
status	Int	No	Account status (defaults to 0)
language	String	No	Language preference (defaults to "en")
roles	[String]	Yes	Array of role names to assign

Creation Flow

Diagram: User Creation Sequence

Key Implementation Details

The implementation at src/Controller/UserController.php114-163 includes:

1. Default Values: Sets join_date to today, status to 0, and language to "en" if not provided
2. Password Validation: Uses System::isValidPassword() to enforce password policy (see src/Controller/UserController.php133-136)
3. Password Hashing: Uses password_hash() with PASSWORD_DEFAULT algorithm
4. Username Uniqueness: Checks for duplicate usernames before saving
5. Role Assignment Protection: Only administrators can assign the "Administrators" role (see src/Controller/UserController.php152-155)
6. Role Creation: Creates UserRole entries for each role in the input

Sources: src/Controller/UserController.php114-163 src/Input/User.php8-68

---

User Updates (updateUser)

The updateUser mutation modifies an existing user's profile fields. It requires the user.update permission and respects the canUpdate authorization check.

GraphQL Mutation

Update Restrictions

The UpdateUserInput type differs from CreateUserInput:

• Includes: username, join_date, expiry_date, status, and all profile fields
• Excludes: password (must use dedicated password mutation) and roles (explicitly removed)

Update Flow and Authorization

Diagram: User Update Authorization and Processing Flow

Authorization Logic

The method at src/Controller/UserController.php50-71 uses User::canUpdate() (defined at src/Model/User.php350-368) which implements these rules:

1. Self-Update: Users can always update their own profile
2. Administrator Protection: Only administrators can update administrator accounts
3. Administrator/Power User Privilege: Administrators and Power Users can update all non-administrator accounts

Excluded Fields

The implementation explicitly removes roles from the update data at src/Controller/UserController.php62 Role management requires separate operations through the RBAC system.

Sources: src/Controller/UserController.php50-71 src/Model/User.php350-368 src/Input/User.php9-69

---

Password Management

The controller provides two distinct password operations: administrative password changes and self-service password changes.

Password Change Operations Comparison

Operation	Method	Permission	Old Password Required	Target	Validation
Admin Change	updateUserPassword	user.changePassword	No	Any user in listUser	Policy check
Self Change	changeUserPassword	(logged in)	Yes	Self only	Policy check

Administrative Password Change (updateUserPassword)

Implementation at src/Controller/UserController.php74-89:

1. Uses listUser() to get the target user (respects administrator filtering)
2. Validates the new password against policy using System::isValidPassword()
3. Hashes the password with password_hash()
4. Sets password_dt to current timestamp
5. Saves the user record

Self-Service Password Change (changeUserPassword)

Implementation at src/Controller/UserController.php92-110:

1. Verifies the old password with password_verify()
2. Returns false if old password is incorrect
3. Validates the new password against policy
4. Hashes and saves the new password with timestamp

Diagram: Password Change Operations

Password Policy Validation

Both operations use System::isValidPassword() to enforce the password policy configured in the system. If validation fails, an exception is thrown with the message "Password is not valid to the password policy".

Sources: src/Controller/UserController.php74-110

---

User Deletion (deleteUser)

The deleteUser mutation removes a user account permanently. It requires the user.delete permission and respects the canDelete authorization check.

GraphQL Mutation

Deletion Authorization Rules

The method at src/Controller/UserController.php168-174 uses User::canDelete() (defined at src/Model/User.php315-335) which enforces:

1. Self-Deletion Prevention: Users cannot delete themselves
2. Administrator Protection: Only administrators can delete administrator accounts
3. Privilege Requirements: Administrators and Power Users can delete non-administrator accounts

Diagram: User Deletion Authorization Flow

Cascading Effects

When a user is deleted through obj.delete(), the Light\Model base class triggers automatic audit logging to EventLog (see Data Layer). Additionally, related records in UserRole may be affected based on foreign key constraints defined in the database schema.

Sources: src/Controller/UserController.php168-174 src/Model/User.php315-335

---

Authorization and Security Summary

The UserController implements a multi-layered security approach:

Layer 1: Declarative Annotations

Annotation	Usage	Effect
#[Logged]	All operations	Requires authenticated user via JWT
#[Right("user.list")]	listUser	Requires specific permission
#[Right("user.add")]	addUser	Requires specific permission
#[Right("user.update")]	updateUser	Requires specific permission
#[Right("user.changePassword")]	updateUserPassword	Requires specific permission
#[Right("user.delete")]	deleteUser	Requires specific permission

Layer 2: Programmatic Checks

Diagram: Security Check Layers in UserController

Layer 3: User Model Authorization

The User model provides centralized authorization logic:

• User::is(string $role) at src/Model/User.php337-340: Checks if user has a specific role
• User::canUpdate(User $by) at src/Model/User.php350-368: Determines if $by can update this user
• User::canDelete(User $by) at src/Model/User.php315-335: Determines if $by can delete this user

These methods are also exposed as GraphQL fields on the User type, allowing client-side UI to show/hide actions based on permissions.

Sources: src/Controller/UserController.php1-176 src/Model/User.php315-368

---

Input Type Definitions

The Light\Input\User class at src/Input/User.php defines three GraphQL input types using attribute-based configuration:

Input Type Variants

Input Type	Purpose	Unique Fields	Usage
CreateUserInput	User creation	password, roles	addUser mutation
UpdateUserInput	User updates	(excludes password, excludes roles)	updateUser mutation
UpdateMyInput	Self-updates	(excludes password, username, join_date, etc.)	User profile editing

Field Availability by Input Type

Diagram: Input Type Field Availability

The #[Field(for: "...")] annotation at src/Input/User.php13-68 controls which fields appear in each input type variant.

Sources: src/Input/User.php1-69

---

Integration with Other Systems

The UserController integrates with several other framework components:

System	Integration Point	Purpose
Auth Service	#[InjectUser] annotation	Provides current user context
RBAC	User::is(), role checking	Determines permissions and role membership
User Model	All operations	Data persistence and business logic
UserRole Model	addUser	Role assignment records
System Type	isValidPassword()	Password policy validation
EventLog	save(), delete() hooks	Automatic audit trail
Config Model	Via System Type	Password policy configuration

For details on authentication and session management, see Authentication Architecture. For role and permission management beyond user assignment, see Role Hierarchy and Permissions.

Sources: src/Controller/UserController.php1-176