CoolCMS API

RatingPresenter extends BasePresenter

in package

• Application

uses GetTrait, GetByTrait, GetAllTrait, DeleteTrait, SaveTrait, OwnershipCheckTrait

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.

$hydrator  : OrmEntityHydrator

$jwtPayload  : JwtPayload|null

$ratingManager  : RatingManager

$ratingVoteManager  : RatingVoteManager

$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

actionDelete()  : void

actionDeleteAll()  : void

actionGet()  : void

actionGetAll()  : void

actionGetBy()  : void

actionSave()  : void

actionSaveReply()  : void

External counterpart of {@see self::internalActionSaveReply()}.

actionUpdateColumns()  : void

collectWriteAudiences()  : array<string, Audience>

Returns the `insert`/`update` axis audience for every entity field with `#[FieldAccess]`; the key is the name without underscores, lowercase.

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).

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

Returns whether the caller may respond to the given review.

internalActionDelete()  : array<string, mixed>

internalActionDeleteAll()  : array<string, mixed>

internalActionGet()  : array<string, mixed>

internalActionGetAll()  : array<string, mixed>

internalActionGetBy()  : array<string, mixed>

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

Returns how this visitor voted on the displayed ratings (one batch for the whole page), so the UI can highlight the choice and not offer it again.

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

Reports an inappropriate review.

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

Wraps the generic `save` action and closes the back door to responses.

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

Saves the owner's response to a rating.

internalActionUpdateColumns()  : array<string, mixed>

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

Registers a vote on the usefulness of one rating ("was this review helpful?").

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.

applyExternalOwner()  : array<string, mixed>

On the external path when creating, sets the record owner from the caller JWT identity.

applyExternalRemoteIp()  : array<string, mixed>

On the external path when creating, sets the caller IP from the server ({@see \App\Core\Base\Api\Models\Managers\Manager::getExternalRemoteIpData()}).

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

columnsOutsideExternalAllowlist()  : array<int, string>

Returns the columns from `$values` that are not in `manager->getExternalUpdateColumnsAllowlist()`, exactly the ones {@see filterExternalUpdateColumns()} drops on the external path.

exemptPersonalDataForCapabilityHolder()  : void

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

filterExternalMeta()  : array<string, mixed>

Keeps in `$meta` only the keys from `manager->getExternalMetaAllowlist()`; the rest is dropped and logged so a lost external key is visible. The default allowlist is `[]`, so without a per-manager override the whole `$meta` is dropped (privileged flags such as `roleIds`, `groupIds`, `skipNotifications`, `rating.*`, `recalcTopedUntil` have no external way in).

filterExternalUpdateColumns()  : array<string, mixed>

Keeps in `$values` only the columns from `manager->getExternalUpdateColumnsAllowlist()` (default `[]` rejects external `updateColumns` entirely); the rest is dropped and logged.

filterReadPayload()  : array<string, mixed>

Read field tier: the last payload filter before the response is sent to the caller.

getOwnedEntityId()  : int|null

Returns the id of the edited record from `data` (save path), or null for an INSERT.

getOwnedParentId()  : int|null

Returns the parent id from `data`, e.g. `order` for a complaint or `advert` for a response to an advert.

getOwnedRequestId()  : int|null

Returns the record id from the request parameters (delete path, `?id=5`), or null.

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.

initializePresenterContext()  : void

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()}).

isOwner()  : bool

Role `owner`, internal path: the caller is the review author.

isOwnershipInsert()  : bool

Tells whether the request creates a record (no `id` in `data`).

isPublicAction()  : bool

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

isQueryCacheEnabled()  : bool

isReceiver()  : bool

Role `receiver`, internal path: the receiver of a rating is the owner of the rated profile.

isSameSiteRequest()  : bool

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

moveGraphKeysToMeta()  : array{0: array, 1: array}

Moves the keys from `manager->getGraphDataKeys()` from `$data` to `$meta`, so the existing afterSave/beforeSave manager sync traits read them unchanged (same mechanism as the internal `meta`, only from another source).

operation()  : T

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

ownedEntityLoader()  : callable(): Array

Returns a lazy entity loader for `ALLOW_IF_OWNER` (see {@see internalActionSave()}); from `$data` only the identifier is taken. Shared by the trait `internalActionSave()` and by presenters that override `internalActionSave()`.

ownedForUpdateColumns()  : Closure|null

Returns a lazy entity loader for `ALLOW_IF_OWNER` on `updateColumns`.

ownsByCapability()  : bool

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

readBodyParameter()  : string|null

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

refineSaveAction()  : "save"|"insert"|"update"

Refines the `save` action to `insert` or `update`.

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]`).

saveEntityData()  : array<string, mixed>

Saves the entity without a guard. Call only from `internalActionSave()` after `requireApiPermission()` (the trait and presenters that override `internalActionSave()` for post-save orchestration, e.g. a bell notification). `ApiPermissionCoverageTest` checks that every `internalAction*()` has a guard; this method is not `internalAction*` and the bridge never calls it.

sendInvalidRequestParameter()  : void

shouldProduceNotifications()  : bool

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

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

Removes from `$data` the keys listed in `manager->getDefaultSkipFields()` before hydration.

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

Removes from `$data` the keys marked with {@see \App\Core\Attributes\Hydration\ExternalAdminOnly} on the entity `$entityClass`.

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

Removes from `$data` the keys marked with {@see \App\Core\Attributes\Hydration\ExternalReadonly} on the entity `$entityClass`.

stripExternalUploadPaths()  : array<string, mixed>

Strips the `path` key from all nested `meta` items on the external boundary.

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

Removes from the `$data` root the fields whose `#[FieldAccess]` axis for the operation (`insert` when creating, `update` when editing) does not admit the caller audience.

verifyOwnership()  : bool

Ownership check for the `:Api:Base:Rating:save` key; the `owner` role is the review author.

verifyReceiver()  : bool

Role `receiver`, external path (key `:Api:Base:Rating:saveReply`): is the caller the owner of the rated profile?

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.

firstColumnWithoutPrivilegeFreeGrant()  : string|null

Second stage of `updateColumns`: attributes on columns.

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

Returns the request `data` as an array; an empty array means nothing to verify (the caller then typically returns false, fail-closed).

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.

logPrivilegeFreeUpdate()  : void

Writes the `API_COLATTR` line for the case where the guard denied but the attributes allowed the write.

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.

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

Normalizes the id: `'5'` to `5`; `['1','2']` to `[1, 2]`; `'abc'`, `''`, `[]`, `0` and `null` to `null`.

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.

probeCallerTierForSave()  : void

Measures the caller tier on the internal path for `save`; changes nothing.

probeCallerTierForUpdateColumns()  : void

Measures the caller tier on the internal path for `updateColumns`.

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

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.

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

Converts a {@see Result} to its array envelope.

updateColumnsDeniedPayload()  : ApiPermissionDeniedShape

Builds the `updateColumns` denial naming the column that caused it.

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