Documentation

UserManagementApiHandler
in package
implements ApiRoutableInterface uses ApiRoutableTrait

Admin-only CRUD over user accounts.

Routes:

  • GET /api/v1/admin/users - Paginated list plus statistics
  • GET /api/v1/admin/users/{id} - One user
  • POST /api/v1/admin/users - Create
  • PUT /api/v1/admin/users/{id} - Update
  • PUT /api/v1/admin/users/{id}/role - Promote or demote
  • PUT /api/v1/admin/users/{id}/status - Activate or deactivate
  • DELETE /api/v1/admin/users/{id} - Delete
Tags
since
3.4.0

Table of Contents

Interfaces

ApiRoutableInterface
Interface for API handlers that participate in route dispatch.

Properties

$createUser  : CreateUser
$deleteUser  : DeleteUser
$listUsers  : ListUsers
$toggleUserRole  : ToggleUserRole
$toggleUserStatus  : ToggleUserStatus
$updateUser  : UpdateUser
$userRepository  : UserRepositoryInterface

Methods

__construct()  : mixed
create()  : array{success: bool, id?: int, errors?: array}
Create a user.
delete()  : array{success: bool, error?: string}
Delete a user.
get()  : array<string, mixed>
Read one user.
list()  : array<string, mixed>
List users.
routeDelete()  : JsonResponse
Handle a DELETE request for this resource.
routeGet()  : JsonResponse
Handle a GET request for this resource.
routePost()  : JsonResponse
Handle a POST request for this resource.
routePut()  : JsonResponse
Handle a PUT request for this resource.
setRole()  : array{success: bool, error?: string}
Promote a user to admin or demote them.
setStatus()  : array{success: bool, error?: string}
Activate or deactivate a user.
update()  : array{success: bool, errors?: array}
Update a user.
frag()  : string
Extract a fragment from the fragments array.
currentAdminId()  : int
The admin performing the request.
denyIfNotAdmin()  : JsonResponse|null
Reject the request unless the caller is an admin.
denyIfNotUsersPath()  : JsonResponse|null
Reject a path under /admin that this handler does not serve.
formatUser()  : array<string, mixed>
Shape a user for the client.
guard()  : JsonResponse|null
Reject the request unless the caller is an admin and the path is ours.

Properties

Methods

__construct()

public __construct(ListUsers $listUsers, CreateUser $createUser, UpdateUser $updateUser, DeleteUser $deleteUser, ToggleUserStatus $toggleUserStatus, ToggleUserRole $toggleUserRole, UserRepositoryInterface $userRepository) : mixed
Parameters
$listUsers : ListUsers
$createUser : CreateUser
$updateUser : UpdateUser
$deleteUser : DeleteUser
$toggleUserStatus : ToggleUserStatus
$toggleUserRole : ToggleUserRole
$userRepository : UserRepositoryInterface

create()

Create a user.

public create(array<string, mixed> $data) : array{success: bool, id?: int, errors?: array}
Parameters
$data : array<string, mixed>

Payload

Return values
array{success: bool, id?: int, errors?: array}

delete()

Delete a user.

public delete(int $id) : array{success: bool, error?: string}
Parameters
$id : int

User ID

Return values
array{success: bool, error?: string}

get()

Read one user.

public get(int $id) : array<string, mixed>
Parameters
$id : int

User ID

Return values
array<string, mixed> —

The user, or an error

list()

List users.

public list(array<string, mixed> $params) : array<string, mixed>
Parameters
$params : array<string, mixed>

Query parameters

Return values
array<string, mixed> —

Users, paging and statistics

routeDelete()

Handle a DELETE request for this resource.

public routeDelete(array<int, string> $fragments, array<string, mixed> $params) : JsonResponse
Parameters
$fragments : array<int, string>

URL path fragments

$params : array<string, mixed>

Request body

Return values
JsonResponse

routeGet()

Handle a GET request for this resource.

public routeGet(array<int, string> $fragments, array<string, mixed> $params) : JsonResponse
Parameters
$fragments : array<int, string>

URL path fragments

$params : array<string, mixed>

Query parameters

Return values
JsonResponse

routePost()

Handle a POST request for this resource.

public routePost(array<int, string> $fragments, array<string, mixed> $params) : JsonResponse
Parameters
$fragments : array<int, string>

URL path fragments

$params : array<string, mixed>

Request body

Return values
JsonResponse

routePut()

Handle a PUT request for this resource.

public routePut(array<int, string> $fragments, array<string, mixed> $params) : JsonResponse
Parameters
$fragments : array<int, string>

URL path fragments

$params : array<string, mixed>

Request body

Return values
JsonResponse

setRole()

Promote a user to admin or demote them.

public setRole(int $id, array<string, mixed> $data) : array{success: bool, error?: string}
Parameters
$id : int

User ID

$data : array<string, mixed>

Payload carrying role

Return values
array{success: bool, error?: string}

setStatus()

Activate or deactivate a user.

public setStatus(int $id, array<string, mixed> $data) : array{success: bool, error?: string}
Parameters
$id : int

User ID

$data : array<string, mixed>

Payload carrying is_active

Return values
array{success: bool, error?: string}

update()

Update a user.

public update(int $id, array<string, mixed> $data) : array{success: bool, errors?: array}

An empty password means "leave it alone", matching the retired form.

Parameters
$id : int

User ID

$data : array<string, mixed>

Payload

Return values
array{success: bool, errors?: array}

frag()

Extract a fragment from the fragments array.

protected frag(array<int, string> $fragments, int $index) : string
Parameters
$fragments : array<int, string>

The URL path fragments

$index : int

The index to extract

Return values
string —

The fragment at the index, or empty string if not present

currentAdminId()

The admin performing the request.

private currentAdminId() : int

The use cases take this to stop an admin removing their own account or demoting themselves out of the last admin seat.

Return values
int

denyIfNotAdmin()

Reject the request unless the caller is an admin.

private denyIfNotAdmin() : JsonResponse|null

Mirrors AdminMiddleware, which guards the pages these routes replaced: the check is skipped when multi-user mode is off, because there are no roles to enforce and the single user is implicitly the administrator.

The API's own gate only checks authentication, so without this any logged-in user could create an account and grant it the admin role.

Return values
JsonResponse|null —

Error response, or null when allowed

denyIfNotUsersPath()

Reject a path under /admin that this handler does not serve.

private denyIfNotUsersPath(array<int, string> $fragments) : JsonResponse|null

The handler is registered on the admin resource, so it also receives anything else that might be added under it later.

Parameters
$fragments : array<int, string>

URL path fragments

Return values
JsonResponse|null —

Error response, or null when allowed

formatUser()

Shape a user for the client.

private formatUser(User $user) : array<string, mixed>

Deliberately omits the password hash and every verification token the entity carries.

Parameters
$user : User

User entity

Return values
array<string, mixed> —

Public user fields

guard()

Reject the request unless the caller is an admin and the path is ours.

private guard(array<int, string> $fragments) : JsonResponse|null
Parameters
$fragments : array<int, string>

URL path fragments

Return values
JsonResponse|null —

Error response, or null when allowed

On this page

Search results