Users (Benutzer)

Read-only API wrapper for the Billomat users resource at /users.

Access

$billomat->users

Justpilot\Billomat\Api\UsersApi, created lazily on first access to $billomat->users.

Endpoints

Method	HTTP	Path
list()	GET	/users
listPage()	GET	/users (page with metadata)
iterateAll()	GET	/users (lazy over all pages)
get($id)	GET	/users/{id}
getOrFail($id)	GET	/users/{id}
getMyself()	GET	/users/myself

The avatar endpoint (GET /users/{id}/avatar) is not implemented in the SDK; call it via $billomat->getHttpClient() if needed.

Custom field definitions for users are available as the sub-resource $billomat->users->properties (PropertiesApi with UserProperty); see properties.md.

Methods

list(UserFilter|array $filters = []): list<User>

Lists users, optionally filtered.

public function list(UserFilter|array $filters = []): array

Use the typed filter UserFilter; a plain array with Billomat parameters still works. Filters supported according to the Billomat docs:

Filter	UserFilter field	Meaning
email	email	E-mail address (case-insensitive)
first_name	firstName	First name
last_name	lastName	Last name

Plus orderBy, page, perPage and extra for further query parameters.

use Justpilot\Billomat\Api\UserFilter;

$users = $billomat->users->list(new UserFilter(email: '@example.com'));

foreach ($users as $user) {
    echo $user->id . ': ' . $user->email . PHP_EOL;
}

Exceptions: AuthenticationException, HttpException.

listPage(UserFilter|array $filters = []): Page<User>

Like list(), but also returns page/per_page/total from the response envelope as PageInfo in $page->info.

$page = $billomat->users->listPage(new UserFilter(perPage: 25));

echo $page->info->total, ' users (page ', $page->info->page, '/', $page->info->totalPages(), ')';

iterateAll(UserFilter|array $filters = [], int $pageSize = 100): Generator<int, User>

Lazy iteration over all pages.

foreach ($billomat->users->iterateAll() as $user) {
    // ...
}

get(int $id): ?User

Fetches a user by ID. Returns null on 404.

$user = $billomat->users->get(123);

Exceptions: AuthenticationException, HttpException.

getOrFail(int $id): User

Like get(), but throws NotFoundException instead of returning null.

getMyself(): ?User

Returns the currently authenticated user (GET /users/myself).

$me = $billomat->users->getMyself();
echo $me?->email;

Pitfalls

• No write access via the API. Billomat documents only read endpoints for /users (list, single, avatar, myself); there is no official POST/PUT/DELETE /users. User management — creating users, changing roles, passwords, deleting — happens only in the Billomat web UI. The SDK therefore deliberately has no create/update/delete for users. (Custom field definitions under $billomat->users->properties are writable.)
• Rights are a map of AccessLevel. $user->rights['invoices'] ?? null is READ, UPDATE, DELETE or null (no access). Levels include the lower ones, so check with allows(): ($user->rights['invoices'] ?? null)?->allows(AccessLevel::UPDATE) ?? false. Values the SDK doesn't know are dropped.
• role_id is a read-only reference. A user's role is in User::$roleId; the role definitions come from settings-roles.md. Assigning a role to a user happens in the UI.

Read model: User

final readonly class Justpilot\Billomat\Model\User

Property	Type	Mapping
id	int	id
email	?string	email
firstName	?string	first_name
lastName	?string	last_name
salutation	?string	salutation
roleId	?int	role_id
created, updated	?\DateTimeImmutable	created, updated
customfield	?string	Free extra field, see Custom meta attributes
locale	?string	locale
timezone	?string	timezone
isAccountOwner	?bool	Account owner
rights	array<string, AccessLevel>	rights: access level per area (articles, banking, …); areas without access are left out
extra	array<string,mixed>	Fields the SDK doesn't map yet, raw (see Read models)

User::fromArray($data) hydrates from the Billomat wire format; User::toArray() writes it back (snake_case).