CoolCMS API

ApiClientManager extends Manager

in package

• Application

External Api clients: application key authentication and client management.

Tags

phpstan-import-type

ApiClientSnapshot from ApiClientService

ApiClientValues from ApiClientService

ApiClientRow from ApiClientService

ApiClientKeyRow from ApiClientService

extends

Table of Contents

Constants

EXPIRING_SOON_DAYS  : int = 7

A valid key expiring within this many days has the `expiring` state (highlighted in the admin).

KEY_LABEL_MAX_LENGTH  : int = 100

KEY_STATE_ACTIVE  : string = 'active'

KEY_STATE_EXPIRED  : string = 'expired'

KEY_STATE_EXPIRING  : string = 'expiring'

KEY_STATE_REVOKED  : string = 'revoked'

LAST_USED_INTERVAL  : int = 60

`last_used_at` is written at most once per this many seconds (per client).

LIMIT_FIELDS  : array<string|int, mixed> = ['limitPerSecond', 'limitPerMinute', 'userLimit...

LIMIT_MAX  : int = 1000000

MAX_VALID_KEYS  : int = 5

Maximum number of valid (not revoked, not expired) keys per application.

NAME_MAX_LENGTH  : int = 100

NOTES_MAX_LENGTH  : int = 255

DELETED_IDS_META  : string = '__deletedIds'

Reserved `$meta` key with the ids of the entities being deleted, captured before the first hook.

EXPIRES_AT_FORMATS  : array<string|int, mixed> = ['Y-m-d\TH:i', 'Y-m-d\TH:i:s', 'Y-m-d H:i', 'Y-...

Accepted expiry input formats: `datetime-local` input (with/without seconds) and the DB format.

Properties

$service  : Service<string|int, TEntity>

Manager service; subclasses narrow the type (`@property` in the Api/Admin/Front manager).

$appContext  : AppContext

$assetFormatRegistry  : AssetFormatRegistry|null

Format processor registry for file uploads, used by {@see \App\Core\Traits\Api\Models\Managers\AssetProcessingTrait}.

$cacheTagInvalidator  : CacheTagInvalidator|null

Post-commit invalidator of the wire-payload query cache (tag bump per entity class).

$internalCallContext  : InternalCallContext|null

Tells whether the call is an internal bridge call; the single source for reading uploaded items with `path` ({@see readUploadedItem()}).

$languageContext  : LanguageContext|null

$nonInvalidatingColumns  : array<string|int, string>

Columns whose update does not invalidate the cache: view counters (`registerEvent()` bumps the counter on every pageview). Without this every view would flush the query cache of the whole class; counters are therefore stale up to the TTL. Override per manager by redefining the property.

$paramsConfig  : Config|null

Neon parameters (`%params%`: server paths and directories), set by the decorator (`decorators.neon`) like `setAppContext()`.

$presenterContext  : PresenterContext

$settingContext  : SettingContext

$totalCount  : int|null

$useTransactionForDelete  : bool

$useTransactionForSave  : bool

$apiClientKeyConfig  : ApiClientKeyConfig

$apiClientService  : ApiClientService

$authenticatedHashes  : array<int, string>

$rejectedUploads  : array<int, array{name: string, reason: string}>

New uploaded items that the Api did not save during the `save()` that is running right now (type, dimensions, unreadable, …). Filled by {@see recordRejectedUpload()} and returned in `saveInfo.rejectedUploads`.

Methods

__construct()  : mixed

authenticateKey()  : ApiClientAuthentication

Authenticates the key from the `X-API-Key` header. The caller must answer every failure identically; the status is only for the auth log. `$now` is the request time (tests); expiry is compared with it, never with the time the record was cached.

createClient()  : Result

Creates a client and its first key. `$values`: `name` (required), `notes`, limits (`null`/empty = default), `roleIds` (missing = default roles), `keyLabel` (optional), `keyExpiresAt` (optional future `Y-m-d\TH:i`). On success `data` = client row + `key` (readable key, returned only here: show it once) + `keyId`.

delete()  : Result

Deletes the entity or entities by id. Optional hooks (opt-in via `method_exists`, like {@see SaveTrait}) allow cleanup of derived or denormalized state during the delete:

deleteAll()  : Result

deleteKey()  : Result

Deletes a key, only an expired or revoked one; a valid key must be revoked first (`VALIDATION_FAILED`, `data.field = keys`). On success `data` = client row.

find()  : T|null

findAll()  : T> : list>)

findBy()  : T|null

findDefaultLimits()  : array{limitPerSecond: int, limitPerMinute: int, userLimitPerMinute: int, ipLimitPerMinute: int}

Returns the default limits from `api.clientKey.limits` (form hint: empty = default).

findDefaultRoleIds()  : array<int, int>

Returns the default roles of a new client: unprivileged roles that apply automatically (guest, registered) or conditionally (owner, receiver). Privileged roles only when explicitly ticked.

findRelatedIds()  : array<int, int>|null

Returns the ids of target entities that already belong to the record `$parentId` through the relation collection `$property` (for example `('assetRels', 'asset')`, `('fileRels', 'file')`). Reads straight from the database, not through the Api read path (no `UoW::clear()` in the middle of save hooks).

findRoleOptions()  : array<int, array{id: int, code: string, name: string, implicit: string, conditional: bool, privileged: bool, default: bool, required: bool}>

Returns the roles that can be allowed for a client, with flags: `default` = prefill for a new client, `required` = the guest role every client always has ({@see withRequiredRoles()}).

findRow()  : array<string, mixed>|null

findRows()  : array<int, array<string, mixed>>

Returns the client overview for the admin including keys (never key digests).

getAppContext()  : AppContext

getDefaultSkipFields()  : array<string|int, string>

Returns keys that the generic `service->save()` must not copy onto the managed entity.

getEntityClass()  : TEntity>

Returns the root Doctrine entity class managed by this manager.

getExternalMetaAllowlist()  : array<string|int, string>

Returns the meta keys allowed through the external HTTP path ({@see \App\Core\Traits\Api\Presenters\SaveTrait::actionSave()}).

getExternalOwnerData()  : array<string, mixed>

Returns `data` keys that fill the owner from the server when an external save creates a record.

getExternalRemoteIpData()  : array<string, mixed>

Returns `data` keys that fill the caller's IP from the server when an external save creates a record; sibling of {@see getExternalOwnerData()}.

getExternalUpdateColumnsAllowlist()  : array<string|int, string>

Returns the columns the external HTTP path may change through {@see \App\Core\Traits\Api\Presenters\SaveTrait::actionUpdateColumns()}.

getGraphDataKeys()  : array<string|int, string>

Returns the keys an external client may send nested in `data`.

getLanguageContext()  : LanguageContext|null

getPresenterContext()  : PresenterContext

getServiceClass()  : class-string

Returns the fully qualified service class name, the identity for the per-service rollout allowlist of the wire-payload query cache ({@see \App\Core\Cache\Config::isServiceEnabled()}).

getSettingContext()  : SettingContext

getSettings()  : array<int, array<string, mixed>>

getTotalCount()  : int|null

initializeAllContexts()  : void

issueKey()  : Result

Issues another key; the other keys stay valid. `$expiresAt` = future `Y-m-d\TH:i`, or `null`/empty = never expires. A revoked application gets `INVALID_STATE`; above `MAX_VALID_KEYS` valid keys it gets `VALIDATION_FAILED` with `data.field = keys`. On success `data` = client row + `key` (readable key, only in this response) + `keyId`.

registerEvent()  : Result

revoke()  : Result

Permanently revokes a client (irreversible) together with all its not yet revoked keys.

revokeKey()  : Result

Permanently revokes one key (irreversible); the other keys stay valid. On success `data` = client row.

save()  : Result

setAppContext()  : $this

setAssetFormatRegistry()  : static

setCacheTagInvalidator()  : static

setEnabled()  : Result

Enables or disables a client. A revoked client cannot be enabled.

setInternalCallContext()  : static

setLanguageContext()  : $this

setParamsConfig()  : static

setPresenterContext()  : $this

setSettingContext()  : $this

touchLastUsed()  : void

Records the last use of the key and the application, at most once per `LAST_USED_INTERVAL`.

updateAllRelations()  : Result

updateClient()  : Result

Changes name, notes, limits and (when `roleIds` is in `$values`) the allowed roles. Name, notes and limits are replaced as a whole: a missing limit falls back to the default from `api.clientKey.limits`.

updateColumn()  : Result

updateColumns()  : Result

updateKey()  : Result

Changes the key label and expiry (future expiry, or `null`/empty = never expires; also later, typically for rotation). The key must belong to the client; a revoked key cannot be changed.

updateRelations()  : Result

beginRejectedUploads()  : array<int, array{name: string, reason: string}>

Starts a save ({@see save()}): the list of rejected items belongs to this save only; the outer one (a nested save of the same manager) is returned to the caller and restored after the save through {@see finishRejectedUploads()}.

bumpCacheTags()  : void

Bumps cache tags for the entity after commit: its class, the owned-cascade classes from metadata and the optional `additionalCacheTags()` of the manager.

bumpCacheTagsExplicit()  : void

Bumps the given classes explicitly (raw-DBAL paths with a cross-entity effect).

bumpCacheTagsForClass()  : void

Bumps cache tags by class name when there is no instance (bulk delete, `updateColumns()`, raw DBAL, tree operations).

classCacheTags()  : array<string|int, string>

Returns extra tags for a bump that has no entity, typically tree operations ({@see \App\Core\Traits\Api\Models\Managers\TreeTrait::treeTransaction()}) that rewrite `lft`/`rgt` on many rows.

finishRejectedUploads()  : void

Ends a save: whatever {@see recordRejectedUpload()} wrote during it is added to the data of a successful result as `saveInfo.rejectedUploads` (the Api presenter passes it on to the caller, the admin builds a warning from it). A rejected item does not fail the save; the accepted files stay.

getDeletedId()  : int|null

Returns the id `$entity` had before the delete, from the snapshot in `$meta` that {@see delete()} hands to every hook. Null for an entity the snapshot does not know (not loaded by this delete, or without a simple id).

getService()  : Service<string|int, TEntity>

Returns the service backing the manager traits.

readUploadedItem()  : string|null

Reads the content of an uploaded item (`{name, data}` base64 or `{name, path}` from the dropzone) through the single reader {@see UploadedItem}.

recordRejectedUpload()  : void

Records a new uploaded item that the save skipped ({@see UploadRejection} `REASON_*`).

buildKeyRow()  : array{id: int, keyPrefix: string, label: string|null, createdAt: string|null, expiresAt: string|null, revokedAt: string|null, lastUsedAt: string|null, state: string}

Builds the key row: `id`, `keyPrefix`, `label`, `createdAt`, `expiresAt`, `revokedAt`, `lastUsedAt` (`Y-m-d H:i:s` in the application time zone) and `state` (active, expiring, expired, revoked).

buildRow()  : array<string, mixed>

Builds the client row for the admin, without key digests; adds `state` (`enabled` / `disabled` / `revoked`), `roleIds` (allowed roles), `keys` (keys with state, {@see buildKeyRow()}) and `activeKeyCount` (valid keys: `active` + `expiring`).

bumpDeleteCacheTags()  : void

Post-commit bump after a delete. With entities it goes through {@see \App\Core\Base\BaseManager::bumpCacheTags()}, which also collects `additionalCacheTags()` (Comment → CommentThread); without them it falls back to bumping the manager class itself, the original behavior.

captureDeletedIds()  : WeakMap<object, int>

Keys the ids by the loaded entity objects, not by the input ids: an input id that loaded nothing must not shift the pairing. A weak map, so the snapshot never keeps an entity alive.

changeClient()  : Result

Shared state change flow: find the client, run the UPDATE (it carries the "not revoked" condition), evict the cache records of all its keys. 0 changed rows for an existing client means the client is revoked.

columnsInvalidateCache()  : bool

deleteBatch()  : Result

Bulk delete of a list of ids as one transaction. `Service::deleteAll()` flushes per entity; in autocommit the rows deleted before a database failure would stay deleted while the caller got either an escaped `EntityManagerClosed` or an "OK" with an error text. Here the service stops at the technical failure, this wrapper rolls the whole batch back and returns the failure Result with `deletedCount = 0` and `rolledBack = true`: nothing of the batch is durable and nothing is attempted over the closed EntityManager. A domain partial success (missing ids) keeps the existing contract and is committed.

findKey()  : ApiClientKeyRow|Result

Returns the client key by id, or `ITEM_NOT_FOUND` (unknown client, foreign or unknown key).

invalid()  : Result

isAssetPathAllowed()  : bool

Checks only entities composing {@see AssetPathTrait}; the trait is the allowlist of "relative file path" columns, other `assetPath`-like fields are untouched.

isDefaultRole()  : bool

isRequiredRole()  : bool

keyState()  : string

Returns the key state at `$now`: revoked, expired, expiring within `EXPIRING_SOON_DAYS` days, or active.

loadEntitiesForCacheTags()  : array<int, object>

Loads the entities being deleted only to find out their `additionalCacheTags()`. Fail-soft: what cannot be loaded is simply missing and the bump falls back to the class; it must never stop the delete.

normalizeKeyValues()  : DateTimeImmutable|null}|Result

Normalizes the key label and expiry input. Label: optional, at most `KEY_LABEL_MAX_LENGTH` characters. Expiry: `Y-m-d\TH:i` (also with seconds, or a space instead of `T`), in the application time zone, must be in the future; empty = never expires. Errors are `VALIDATION_FAILED` with `data.field` `keyLabel` / `keyExpiresAt`.

normalizeRoleIds()  : array<int, int>|null

normalizeValues()  : array{values: array{name: string, notes: string|null, limitPerSecond: int|null, limitPerMinute: int|null, userLimitPerMinute: int|null, ipLimitPerMinute: int|null}, roleIds: list|null}|Result

parseExpiresAt()  : DateTimeImmutable|null

Strict parser: exact format, no silent normalization of `2026-02-30` to `2026-03-02`.

rollbackBatch()  : void

saveWithHooks()  : Result

Runs the save itself: transaction, `beforeSave` / `afterSave` / `completedSave`, tree, cache.

tooManyKeys()  : Result

usesAssetPathTrait()  : bool

withRequiredRoles()  : array<int, int>

Returns the allowed roles plus the required guest role (`implicit = anonymous`).