Roles

$envless->roles->listAll()

Collect every role in the workspace into one array

php
/** @return list<RoleResource> */
public function listAll(
    ?int $limit = null,
    ?int $offset = null,
    ?string $search = null,
    ?string $sortBy = null,
    int|float|null $timeout = null,
): array

Walks every page and returns the flattened array. Because a workspace is capped at 25 custom roles, this is a single request in practice and is the convenient way to build a name to id map before inviting members.

The trap is limit:: it sets the page size used while walking, not a cap on how many roles come back. Asking for a limit of 5 still returns every role, in more round trips. System roles lead the array, so do not rely on index position to find a custom role.

Example

php
use Envless\Envless;

$envless = new Envless();

$roles = $envless->roles->listAll();

foreach ($roles as $role) {
    if ($role['systemKey'] === 'viewer') {
        echo $role['id'], PHP_EOL;
    }
}

Parameters

ParameterTypeRequiredDescription
$limitintNoPage size used while walking, clamped to 100.
$offsetintNoRow to start the walk from.
$searchstringNoCase insensitive substring match against role name and description.
$sortBystringNoOrder within each group: name (the default) is A to Z, updated and created are newest first. System roles always come first.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. Overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list<RoleResource> holding every role in the workspace, system roles first.

Reads the roles collection. list returns one page as an Envless\Result\Page with items and pagination, listAll collects every page into an array, and iterate returns a Generator that yields one item at a time, fetching the next page only when the loop gets there.

Worth knowing

  • Page size defaults to the API maximum of 100 and is clamped there, so a larger limit buys nothing.
  • Match system roles on systemKey, which is owner, admin or viewer, rather than on name, since names are display text.

Required scopes

roles:read

Underlying endpoint

GET /roles

Request and response schema, every error code, and a live playground.

In TypeScript

envless.roles.listAll()

The same method in @goenvless/sdk, with the same request, retries and errors.