CoolCMS API

CategoryPresenter extends BasePresenter

in package

• Application

uses CrudTrait, PublicAdvertReadFilterTrait, TreeTrait, CategorySuggestTrait

Table of Contents

Constants

CALLER_TIER_PRIVILEGED  : string = 'privileged'

Caller tier: `privileged` means the grant for this key came from a role with `privileged = 1`; `user` means anything else (`guest`, `registrated`, `owner`) and is also the fail-closed default of all error branches.

CALLER_TIER_USER  : string = 'user'

SESSION_NAMESPACE  : mixed = 'api'

CALLER_BACKTRACE_LIMIT  : int = 14

Depth of `debug_backtrace()` when looking for `caller=` (a limit, not the whole stack).

CALLER_SKIPPED_PATHS  : array<string|int, mixed> = [ // The Api layer itself. 'app/Core/Traits/Api...

Path prefixes (relative to the project root) skipped when looking for `caller=`.

Properties

$accessTokenValidator  : AccessTokenValidator

The rule "signature + expiry + `jti` deny-list" has a single implementation ({@see AccessTokenValidator}), shared by this guard and the admin/front `checkAuthentication()`.

$allowedMethods  : array<string|int, mixed>

$apiClientContext  : ApiClientContext

IMPORTANT: access only through {@see self::apiClientContext()}. A presenter built outside DI (unit tests) lacks it, and reading an uninitialized typed property throws `Error`.

$apiClientKeyConfig  : ApiClientKeyConfig

$apiClientManager  : ApiClientManager

$apiClientRateLimiter  : ApiClientRateLimiter

$apiRbacConfig  : ApiRbacConfig

$authLogManager  : AuthLogManager

$corsConfig  : CorsConfig

$currencyContext  : CurrencyContext

$currencyManager  : CurrencyManager

$fieldAudienceContext  : FieldAudienceContext

Audience of the caller for the emit filter ({@see \App\Core\Attributes\Hydration\FieldAccess}).

$jtiDenyList  : JtiDenyList

$jwtGuardConfig  : JwtGuardConfig

$jwtManager  : JwtManager

$lang  : int|string|null

$languageContext  : LanguageContext

$languageManager  : LanguageManager

$localizationContext  : LocalizationContext

$localizationManager  : LocalizationManager

$localizationPaymentRegionManager  : PaymentRegionManager

NOTE: deliberately named differently; presenters often have `$paymentRegionManager` in the constructor (property collision).

$operationScope  : OperationScope

Boundary of one Api operation (see {@see self::operation()}).

$pageManager  : PageManager

$permissionResolver  : PermissionResolver

$personalDataPolicy  : PersonalDataPolicy

Personal data policy applied to the output (see {@see self::sendJson()}).

$presenterContext  : PresenterContext

$queryCache  : QueryCache

$queryPathPolicy  : QueryPathPolicy

Policy for field paths in filters and ordering (see {@see self::rejectForbiddenQueryPaths()}).

$securityConfig  : SecurityConfig

$settingContext  : SettingContext

$settingManager  : SettingManager

$debugMode  : bool

$manager  : Manager|null

$productionMode  : bool

$anonymousDenyReported  : array<string, true>

$callerTierReported  : array<string, true>

Dedup of `API_COLTIER` lines within one request. The key is `kind|rbac key|tier|userId|field|caller`, so only a literally identical line is dropped; a different caller, tier or field set is logged separately.

$categoryManager  : CategoryManager

$hydrator  : OrmEntityHydrator

$jwtPayload  : JwtPayload|null

$rateLimit  : RateLimit

$rateLimitConfig  : RateLimitConfig

$rbacDecision  : PermissionDecision|null

Decision after the ownership check; the one that allows or denies.

$rbacEnforced  : bool

True only when the gate actually rejected the request (`enforce` + deny).

$rbacKey  : string|null

Key of the last evaluation, e.g. `:Api:Eshop:Order:save`.

$rbacRawDecision  : PermissionDecision|null

Resolver decision before the ownership check (input of the field tier).

Methods

__construct()  : mixed

actionDeleteNode()  : void

actionInsertTreeNode()  : void

actionMoveDown()  : void

actionMoveSubtree()  : void

actionMoveSubtreeTo()  : void

actionMoveUp()  : void

getApiClient()  : ApiClientIdentity|null

Returns the client whose key came with this request; `null` means no key (web or admin through the bridge, a `#[NoClientKey]` exception, or `required: false` without a key).

getCurrencyContext()  : CurrencyContext

getJwtPayload()  : JwtPayload|null

getLanguageContext()  : LanguageContext

getPersonalDataCapabilityRows()  : array<string, array<int, int>>

Returns the records whose personal data the caller receives in full thanks to a capability (advert password).

internalActionDeleteNode()  : array<string, mixed>

internalActionInsertTreeNode()  : array<string, mixed>

internalActionMoveDown()  : array<string, mixed>

internalActionMoveSubtree()  : array<string, mixed>

internalActionMoveSubtreeTo()  : array<string, mixed>

`$expectation` is {@see TreeMoveExpectation::toArray()} (`oldParentId`, `prevId`, `nextId`); null moves without verifying the state (forms, older clients). The parameter name must match the bridge payload key (named args).

internalActionMoveUp()  : array<string, mixed>

internalActionSuggest()  : array{items: list>, limited: bool}|ApiPermissionDeniedShape

isPersonalDataPolicyExempt()  : bool

Returns whether the response of the action skips the personal data policy; the default is no action.

sendJson()  : void

Sends the JSON response after personal data of other users passed through {@see PersonalDataPolicy}.

setApiCallSource()  : void

Sets the call source; only {@see \App\Core\Bridge\ApiBridge::internalCall()} calls it (same pattern as `setQueryCacheEnabled()`).

setAuthenticatedPayload()  : void

Pre-populate the authenticated payload from a trusted caller (ApiBridge internal mode). Internal calls skip startup() and therefore the Bearer middleware — this setter is how ApiBridge propagates the calling Front user's identity into the Api presenter so internalAction* methods can see it via getJwtPayload().

setConfigParameters()  : void

setQueryCacheEnabled()  : void

Sets the query cache flag; only {@see \App\Core\Bridge\ApiBridge::internalCall()} calls it, before `internalAction*()` (same pattern as `setAuthenticatedPayload()`).

startup()  : void

applyCors()  : void

Applies the CORS headers and short-circuits a preflight (OPTIONS) with a 204 response.

checkApiPermission()  : void

Gate entry point; call in `startup()` right after `checkJwtAuth()`.

checkClientCallerLimit()  : void

Step 4 of an external request: limit of one caller under the key. A logged-in caller is counted by `userId` from the JWT (never from the request), an anonymous one by address.

checkClientKey()  : void

Step 2 of an external request, see the trait docblock. A rejection ends in `sendJson()` (`AbortException`); otherwise the client is set in the request context.

checkJwtAuth()  : void

exemptPersonalDataForCapabilityHolder()  : void

IMPORTANT: exempts the capability holder's own record from personal data masking.

filterReadPayload()  : array<string, mixed>

getRbacDecision()  : PermissionDecision|null

Decision after the ownership check (null when the gate did not run, i.e. mode `off`).

getRbacKey()  : string|null

getRbacRawDecision()  : PermissionDecision|null

Resolver decision before the ownership check; input of the field tier.

getRequestParameters()  : array<string, mixed>

Returns the parameters of the current request.

getSessionKey()  : string

Returns a session key string, e.g. 'front.auth.step1'.

getSessionSection()  : SessionSection

Returns a Nette\SessionSection instance using a dynamically built session key.

inactiveFilterDependentClasses()  : array<string, string>

inactiveFilterEntityClass()  : string

inactiveFilterHiddenFields()  : array<int, string>

initializePresenterContext()  : void

internalActionReorderChildren()  : array<string, mixed>

Reorders the direct children of a parent (`reorder-children`, internal bridge only); see {@see \App\Core\Traits\Api\Models\Managers\TreeTrait::reorderChildren()}.

isCallerTierProbeActive()  : bool

Returns whether the `API_COLTIER` measuring probe is active. All three conditions are needed:

isClientKeyExempt()  : bool

Returns whether the current action is exempt from the key (`#[NoClientKey]` on its `action*()` method). An unknown action is not exempt (fail-closed, like {@see JwtAuthTrait::isPublicAction()}).

isLiveRecord()  : bool

isOwner()  : bool

Default ownership check, fail-closed: without {@see OwnerAwareInterface} on the entity it is always `false`. Presenters with their own semantics (`Bazaar/Comcat Advert` have `getInsertUserId()`; `Base\Rating` has the owner of the rated object, not the author) override it. The generic `getUserId()` fallback with the `> 0` edge lives in `OwnershipCheckTrait`.

isPublicAction()  : bool

Tells whether the current action carries `#[PublicAction]`.

isQueryCacheEnabled()  : bool

isReceiver()  : bool

Default check of the `receiver` role: "is the caller the recipient of this record?" (whom it was sent to, not who created it). Fail-closed: without {@see ReceiverAwareInterface} on the entity it is always `false`. {@see self::requireApiPermission()} calls it only when the resolver returned a conditional `receiver` grant (without an unconditional one). Each domain defines its recipient itself (Response: privileged role, advert owner, password capability or a valid `read_key`).

isSameSiteRequest()  : bool

Tells whether the request comes from the own site (Nette SameSite cookie); protects GET actions with a side effect.

operation()  : T

Runs the body of one `internalAction*()` method as one operation (one Api call = one action).

ownsByCapability()  : bool

Returns whether the caller is the owner of the record by a capability in the JWT (not by identity).

publicReadIsAdvert()  : bool

readBodyParameter()  : string|null

Returns a value from the request body: `application/x-www-form-urlencoded` or `multipart` (POST fields) and `application/json`.

rejectForbiddenQueryPaths()  : array<string|int, mixed>|null

IMPORTANT: rejects filters, ordering and `columns` that reach fields the caller would not get in the output.

reportCallerTierGap()  : void

Writes one machine-parsable `API_COLTIER` line to the `auth` channel. The format follows `API_RBAC ...` from {@see logApiPermissionDecision()}, so both parse with one report:

requireApiPermission()  : ApiPermissionDeniedShape|null

Guards one Api action. Returns `null` to continue, or an array to return immediately.

requireManager()  : Manager

Returns the manager for the shared CRUD/tree actions.

resolveApiPresenterName()  : string

Maps `App\UI\Api\Eshop\Presenters\OrderPresenter` to `Api:Eshop:Order`.

resolveCallerFrame()  : string

Returns e.g. `app/UI/Front/Eshop/Presenters/ProductPresenter.php:88`: the first stack frame outside {@see self::CALLER_SKIPPED_PATHS}, i.e. the first place that really asked for the data.

resolveCallerTier()  : string

Returns the caller tier for this presenter and action: `privileged` or `user`.

resolveExternalFieldTier()  : string

Resolves the field tier of the caller (`#[ExternalAdminOnly]`).

sendInvalidRequestParameter()  : void

shouldProduceNotifications()  : bool

Returns whether notifications in the bell should be created for this operation.

suggestCategories()  : array<string|int, mixed>

{@see CategorySuggestTrait::internalActionSuggest()}

verifyOwnership()  : bool

Default `owner` check: is the caller the owner of this record? Fail-closed.

verifyReceiver()  : bool

Default `receiver` check: is the caller the receiver of this record (who it was sent to, not who created it)? Fail-closed.

apiClientContext()  : ApiClientContext|null

apiPermissionTokenHint()  : string

Returns the first 12 characters of the Bearer token, in the same shape as `API_RBAC ... token=` from the external gate. On the internal path the `Authorization` header is usually empty, giving `-`.

buildApiPermissionKey()  : string

Builds the key such as `:Api:Eshop:Order:updateColumns` from `getName()` + `getAction()`, never from the URL: Nette `Route::$styles['action']` applies `path2action`, so the URL `update-columns` is `updateColumns` inside the presenter, and the optional `<loc>` route segment is not part of the key.

extractBearerToken()  : string|null

fieldAudience()  : FieldAudienceContext|null

Returns the audience context, or `null` when the presenter did not get it through DI.

getOwnershipRecordId()  : int|null

Returns the id of the decided record, taken only from the request identifiers: the `id` parameter (get/delete) or `data.id` (save UPDATE). Returns `null` when both are given and differ (ambiguous), when `id` is an array (bulk delete) and for an INSERT.

initializeCurrency()  : void

initializeLanguage()  : void

isInternalTransport()  : bool

Returns true when `Presenter::run()` did not run, i.e. the call is on the internal (bridge) path.

loadLocalization()  : Localization|null

localizationCurrencyKey()  : string|null

Returns the currency key of the localization's payment region.

logApiPermissionDecision()  : void

Writes the `API_RBAC` line to the `auth` channel. The format is identical to {@see RbacCheckTrait::logRbacDecision()} (so both parse with one report), extended with: - `path=internal|external`: tells the two modes apart in one log; - `caller=File.php:123`: makes the report a list of pages instead of a list of keys; - `key_exists=yes|no`: see below.

logRbacDecision()  : void

Writes one machine-parsable line to the `auth` channel, in a format that follows `JWT_GUARD ...` from {@see JwtAuthTrait::reportJwtAuthFailure()} so that a report can be built from the log.

permissionDeniedPayload()  : ApiPermissionDeniedShape

Returns the denial shape, identical to what the external gate sends ({@see RbacCheckTrait::checkApiPermission()}), but returned instead of `sendJson()` because the internal path has nowhere to send an HTTP status.

rbacTokenHint()  : string

Returns the first 12 characters of the Bearer token, in the same shape as `JWT_GUARD ... token=`.

refuseClientKey()  : void

Sends one response for a missing, unknown, disabled, revoked and expired key, so the caller cannot tell which key exists. The reason, client id and key id (`cms_system_api_client_keys`, not the key itself) go only to the log; the key or any part of it never does.

refuseClientLimit()  : void

Sends 429 with `Retry-After`. Only the first refusal in the window goes to the auth log, so a flood does not flood the log too.

reportJwtAuthFailure()  : void

requireTreeManager()  : TreeManagerInterface

Returns the tree manager; a presenter without one has no tree actions.

resolveGuardMode()  : string

Returns the mode for the transport. Never throws: a missing configuration service means the guard is inert (the pre-guard behavior), not deny.

resolveTreeRequestAfterId()  : int|null

Resolves the sibling to insert after: missing, `null`, `''` or `0` means first position.

resolveTreeRequestConfig()  : array<string|int, mixed>|null

resolveTreeRequestExpectation()  : array<string|int, mixed>|false|null

resolveTreeRequestId()  : int|null

Resolves the node id of an external tree mutation. Only a canonical positive id passes; otherwise HTTP 400 is sent and `null` returned. `(int) ['999']` is `1`, so without the check `id[]=...` would move or delete node 1 (with its subtree).

resolveTreeRequestParentId()  : int|false|null

Resolves the new parent: missing, `null` or `''` means root (`null`), `0` is kept as the zero sentinel, otherwise a canonical positive id. `false` means rejected (HTTP 400 already sent); without it `newParentId[]=5` would fall back to `null`, i.e. a move to the root.

resultToArray()  : array<string, mixed>

API_COLTIER path=internal kind=save key=:Api:Bazaar:Advert:save tier=user \
  userId=11 would_strip=insertUserId,user caller=app/UI/Front/.../EditTrait.php:88