CoolCMS API

OrderPresenter extends BasePresenter
in package

Application

uses CrudTrait, NotificationProducerTrait

FinalYes

Order endpoints on top of the generic {@see CrudTrait} (grid/edit load through the admin bridge) plus orchestration actions the admin cannot do itself (catalog prices, VAT, stock split and the status machine live only in the Api):

internalActionBuild() (api/eshop/order/build): the only entry point for the admin edit form (AJAX recalculation preview and the final save, told apart by the persist flag). Raw inputs (setId and quantity, tariffId, voucher codes, gift ids) become a snapshot, see OrderSnapshotBuilder, then OrderManager::save().
internalActionTransition() (api/eshop/order/transition): thin bridge to OrderTransitionManager::apply(), the only entry point for status changes.

IMPORTANT: this presenter must not use OwnershipCheckTrait. No owner-conditional grant exists for save (orders are changed only by staff) and delete never had one, so verifyOwnership()/isOwner() would be unreachable; OwnershipFallbackCoverageTest guards this. Customer paths to an order are checkout, myOrders, setBuyers and repeatItems, which verify ownership in the managers.

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).
$notificationManager : NotificationManager
$notificationTypeManager : NotificationTypeManager
$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.
$checkoutManager : OrderCheckoutManager
$creditNoteManager : OrderCreditNoteManager
$hydrator : OrmEntityHydrator
$jwtPayload : JwtPayload|null
$orderManager : OrderManager
$paymentMethodManager : PaymentMethodManager
$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).
$transitionManager : OrderTransitionManager

Methods

__construct() : mixed
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).
internalActionBuild() : array{success: bool, message?: string, errorCode?: string, id?: int|null, order?: array, warnings?: list}|ApiPermissionDeniedShape: Admin edit form: thin bridge to {@see OrderManager::getBuildData()}, which builds, recalculates and optionally saves the order from the trusted form lines (the payload is described in the docblock of that method).
internalActionCheckout() : array{success: bool, errorCode?: string, message?: string, id?: int, orderNumber?: string, statusKey?: string, paymentId?: ?int, requiresGateway?: bool, order?: array, options?: array, totalWeight?: string, warnings?: list, shortItems?: list}|ApiPermissionDeniedShape: The only entry point of the front checkout (`api/eshop/order/checkout`). Deliberately not an extension of {@see internalActionBuild()}: the admin path is trusted (prices come from the form), the checkout is untrusted (prices come only from the catalog through the resolver).
internalActionCreditNote() : array{success: bool, errorCode?: string, message?: string, invoiceId?: int|null, invoiceNumber?: string|null, final?: bool}|ApiPermissionDeniedShape: Issues a partial credit note. Thin bridge to {@see OrderCreditNoteManager::issuePartial()}, which holds the per-order lock and the cap; no logic of its own here.
internalActionCreditNotePreview() : array<string|int, mixed>: Base for the admin partial credit note form: lines of the source invoice with the remainder. Read only (no lock); the authoritative cap check happens in {@see internalActionCreditNote()}.
internalActionItemPrefill() : array{success: bool, message?: string, errorCode?: string, code?: ?string, name?: string, unit?: ?string, vat?: string, price?: string}|ApiPermissionDeniedShape: Picker prefill: thin bridge to {@see OrderManager::getItemPrefillData()}.
internalActionMyOrders() : array{success: bool, orders: list>, total: int}|ApiPermissionDeniedShape: "My orders" list, thin bridge to {@see OrderCheckoutManager::listForUser()}. `$userId` is a server-authoritative parameter of the front presenter (from `$this->getUser()->getId()` after the login check); this action authenticates nobody itself and relies on the calling page being `logged=1` (see the front `MyOrderListPresenter`).
internalActionRepeatItems() : array{success: bool, errorCode?: string, message?: string, items?: list, skippedCount?: int}|ApiPermissionDeniedShape: Base for "repeat order", thin bridge to {@see OrderCheckoutManager::repeatItems()}.
internalActionSetBuyers() : array{success: bool, userIds: list}|ApiPermissionDeniedShape: Tells whether a user bought a set, thin bridge to {@see OrderCheckoutManager::buyersOfSet()}.
internalActionSummary() : array{success: bool, errorCode?: string, message?: string, order?: array}|ApiPermissionDeniedShape: Data for the checkout return page (`api/eshop/order/summary`). The state is read only from the order and its paired payment, never from gateway GET parameters.
internalActionTransition() : array{success: bool, message?: string, errorCode?: string, noop?: bool, warnings?: list, invoiceId?: int|null, stockDocumentId?: int|null}|ApiPermissionDeniedShape: Thin bridge to {@see OrderTransitionManager::apply()}. The status form is the only admin entry point and may call only this (no status logic of its own in the presenter or the form).
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>: Read field tier: the last payload filter before the response is sent to the caller.
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: 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).
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.
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.
createdIdForNotification() : int|null: Id of a newly created record from the `internalActionSave()` response, or `null` when nothing should be notified: update (`$data` had the id), failure, or a call from the admin.
extractBearerToken() : string|null
failureArray() : array{success: false, errorCode: string, message: string}
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
internalActionPaymentMethods() : array{success: bool, items?: list}|ApiPermissionDeniedShape: Front footer (`PaymentMethodListComponent`, `api/eshop/order/payment-methods`): names of the available payment methods (no prices, no entity), thin bridge to {@see PaymentMethodManager::listAvailableForLanguage()}.
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.
produceNotification() : void
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.

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


    protected
        string
    CALLER_TIER_PRIVILEGED
    = 'privileged'

The values are the same strings as $meta['__externalTier'] on the external path (RbacCheckTrait::resolveExternalFieldTier()); it is the same concept from the same core (PermissionResolver::isGrantedByPrivilegedRole()), detected on the other transport. No second decision path exists.

The constants are protected, not private: SaveTrait is flattened into concrete presenters (descendants of Api\BasePresenter), while this trait sits on Api\BasePresenter, so a private constant of the ancestor would be unreachable.

CALLER_TIER_USER


    protected
        string
    CALLER_TIER_USER
    = 'user'

SESSION_NAMESPACE


    protected
        mixed
    SESSION_NAMESPACE
    = 'api'

CALLER_BACKTRACE_LIMIT

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


    private
        int
    CALLER_BACKTRACE_LIMIT
    = 14

12 plus the two frames operation() adds (the call and its body closure).

CALLER_SKIPPED_PATHS

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


    private
        array<string|int, mixed>
    CALLER_SKIPPED_PATHS
    = [
    // The Api layer itself.
    'app/Core/Traits/Api/',
    'app/UI/Api/',
    // `operation()` calls the body closure of every `internalAction*()`; without this entry
    // every `caller=` would be that one line (degenerate by construction, not by measurement).
    'app/Core/Base/Api/BasePresenter.php',
    // Forwarding plumbing, see the docblock above.
    'app/Core/Bridge/',
    'app/Core/Base/Front/Models/',
    'app/Core/Base/Admin/Models/',
]

The Api layer itself is skipped because it is "who called the guard", not "who wanted the data". The bridge and generic front/admin model classes are skipped too: with only the Api prefixes caller= was app/Core/Bridge/ApiBridge.php for nearly every line, because internalCall() calls internalAction* by reflection. A report with a single file is useless. The extra prefixes are pure forwarding plumbing, identical for every internal call:

app/Core/Bridge/: the transport itself;
app/Core/Base/{Front,Admin}/Models/: generic ApiRepository, ApiMapper, ApiService and SingleQuery shared by most front and admin repositories.

The first non-skipped frame is then the first module file (concrete repository, init trait, presenter, component), the one that really asked for the data.

NOTE: before adding another prefix, measure the caller= breakdown in log mode and show that the field is degenerate without it.

$accessTokenValidator

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


        public
            AccessTokenValidator
    $accessTokenValidator

#[Inject]

$allowedMethods


        public
            array<string|int, mixed>
    $allowedMethods
     = ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS']

$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`.


        public
            ApiClientContext
    $apiClientContext

Attributes

#[Inject]

$apiClientKeyConfig


        public
            ApiClientKeyConfig
    $apiClientKeyConfig

#[Inject]

$apiClientManager


        public
            ApiClientManager
    $apiClientManager

#[Inject]

$apiClientRateLimiter


        public
            ApiClientRateLimiter
    $apiClientRateLimiter

#[Inject]

$apiRbacConfig


        public
            ApiRbacConfig
    $apiRbacConfig

#[Inject]

$authLogManager


        public
            AuthLogManager
    $authLogManager

#[Inject]

$corsConfig


        public
            CorsConfig
    $corsConfig

#[Inject]

$currencyContext


        public
            CurrencyContext
    $currencyContext

Attributes

#[Inject]

$currencyManager


        public
            CurrencyManager
    $currencyManager

#[Inject]

$fieldAudienceContext

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


        public
            FieldAudienceContext
    $fieldAudienceContext

Filled by the guard from the decision it has just made, never from the request.

IMPORTANT: access it only through self::fieldAudience(). An uninitialized typed property throws Error on first access, which lands in the fail-closed catch-all of ApiPermissionGuardTrait::requireApiPermission(); a presenter built outside DI would then be denied everything because of a field filter unrelated to authorization.

NOTE: the type cannot be nullable, InjectExtension rejects it; hence the non-nullable property with an isset() getter.

Attributes

#[Inject]

$jtiDenyList


        public
            JtiDenyList
    $jtiDenyList

#[Inject]

$jwtGuardConfig


        public
            JwtGuardConfig
    $jwtGuardConfig

#[Inject]

$jwtManager


        public
            JwtManager
    $jwtManager

#[Inject]

$lang


        public
            int|string|null
    $lang
     = NULL

$languageContext


        public
            LanguageContext
    $languageContext

Attributes

#[Inject]

$languageManager


        public
            LanguageManager
    $languageManager

#[Inject]

$localizationContext


        public
            LocalizationContext
    $localizationContext

Attributes

#[Inject]

$localizationManager


        public
            LocalizationManager
    $localizationManager

#[Inject]

$localizationPaymentRegionManager

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


        public
            PaymentRegionManager
    $localizationPaymentRegionManager

#[Inject]

$notificationManager


        public
            NotificationManager
    $notificationManager

#[Inject]

$notificationTypeManager


        public
            NotificationTypeManager
    $notificationTypeManager

#[Inject]

$operationScope

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


        public
            OperationScope
    $operationScope

#[Inject]

$pageManager


        public
            PageManager
    $pageManager

#[Inject]

$permissionResolver


        public
            PermissionResolver
    $permissionResolver

#[Inject]

$personalDataPolicy

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


        public
            PersonalDataPolicy
    $personalDataPolicy

#[Inject]

$presenterContext


        public
            PresenterContext
    $presenterContext

Attributes

#[Inject]

$queryCache


        public
            QueryCache
    $queryCache

#[Inject]

$queryPathPolicy

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


        public
            QueryPathPolicy
    $queryPathPolicy

#[Inject]

$securityConfig


        public
            SecurityConfig
    $securityConfig

#[Inject]

$settingContext


        public
            SettingContext
    $settingContext

Attributes

#[Inject]

$settingManager


        public
            SettingManager
    $settingManager

#[Inject]

$debugMode


        protected
            bool
    $debugMode
     = false

$manager read-only


        protected
            Manager|null
    $manager
     = null

$productionMode


        protected
            bool
    $productionMode
     = false

$anonymousDenyReported


        private
        static    array<string, true>
    $anonymousDenyReported
     = []

keys of denied guest reads already logged in this request

$callerTierReported


        private
        static    array<string, true>
    $callerTierReported
     = []

IMPORTANT: it is static, not an instance property: ApiBridge::internalCall() creates a new presenter instance for every call, so an instance property would deduplicate nothing. Only one class uses this trait (BasePresenter), so the storage is one per request. With internalMode: off nothing is ever written to it.

$checkoutManager read-only


        private
            OrderCheckoutManager
    $checkoutManager

$creditNoteManager read-only


        private
            OrderCreditNoteManager
    $creditNoteManager

$hydrator read-only


        private
            OrmEntityHydrator
    $hydrator

$jwtPayload


        private
            JwtPayload|null
    $jwtPayload
     = null

$orderManager read-only


        private
            OrderManager
    $orderManager

$paymentMethodManager read-only


        private
            PaymentMethodManager
    $paymentMethodManager

$rbacDecision

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


        private
            PermissionDecision|null
    $rbacDecision
     = null

$rbacEnforced

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


        private
            bool
    $rbacEnforced
     = false

$rbacKey

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


        private
            string|null
    $rbacKey
     = null

$rbacRawDecision

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


        private
            PermissionDecision|null
    $rbacRawDecision
     = null

$transitionManager read-only


        private
            OrderTransitionManager
    $transitionManager

__construct()


    public
                    __construct(OrderManager $orderManager, OrmEntityHydrator $hydrator, OrderTransitionManager $transitionManager, OrderCheckoutManager $checkoutManager, OrderCreditNoteManager $creditNoteManager, PaymentMethodManager $paymentMethodManager) : mixed

Parameters

$orderManager : OrderManager
$hydrator : OrmEntityHydrator
$transitionManager : OrderTransitionManager
$checkoutManager : OrderCheckoutManager
$creditNoteManager : OrderCreditNoteManager
$paymentMethodManager : PaymentMethodManager

getApiClient()

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


    public
                    getApiClient() : ApiClientIdentity|null

Return values

ApiClientIdentity|null

getCurrencyContext()


    public
                    getCurrencyContext() : CurrencyContext

Return values

CurrencyContext

getJwtPayload()


    public
                    getJwtPayload() : JwtPayload|null

Return values

JwtPayload|null

getLanguageContext()


    public
                    getLanguageContext() : LanguageContext

Return values

LanguageContext

getPersonalDataCapabilityRows()

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


    public
                    getPersonalDataCapabilityRows(string $action) : array<string, array<int, int>>

The shape is [entity class => [id]] for PersonalDataPolicy::apply(). Only get returns rows; other actions (lists, getBy) return none. Filled by self::exemptPersonalDataForCapabilityHolder().

Parameters

$action : string

Return values

array<string, array<int, int>>

internalActionBuild()

Admin edit form: thin bridge to {@see OrderManager::getBuildData()}, which builds, recalculates and optionally saves the order from the trusted form lines (the payload is described in the docblock of that method).


    public
                    internalActionBuild(array<string, mixed> $payload) : array{success: bool, message?: string, errorCode?: string, id?: int|null, order?: array, warnings?: list}|ApiPermissionDeniedShape

Parameters

$payload : array<string, mixed>

Return values

array{success: bool, message?: string, errorCode?: string, id?: int|null, order?: array, warnings?: list}|ApiPermissionDeniedShape

internalActionCheckout()

The only entry point of the front checkout (`api/eshop/order/checkout`). Deliberately not an extension of {@see internalActionBuild()}: the admin path is trusted (prices come from the form), the checkout is untrusted (prices come only from the catalog through the resolver).


    public
                    internalActionCheckout(array<string, mixed> $payload) : array{success: bool, errorCode?: string, message?: string, id?: int, orderNumber?: string, statusKey?: string, paymentId?: ?int, requiresGateway?: bool, order?: array, options?: array, totalWeight?: string, warnings?: list, shortItems?: list}|ApiPermissionDeniedShape

Do not add front-specific behavior to internalActionBuild().

payload (everything else is server-authoritative: seller, prices, rates, discounts, status):

lines (list<array{setId:int, quantity:int}>): the only item data from the client,
tariffId / branchId (?int): shipping and the optional pickup point of the seller's own branch,
pickupPoint (?array<string, mixed>): the raw object exactly as issued by the carrier widget (the front end passes it on unchanged). It belongs only to the tariff from tariffId: the server ignores it unless that tariff has external_pickup = 1, and without it place() rejects such a tariff (errorCode: 'pickupPointRequired'). Sanitization is done by the carrier driver chosen by Shipper::$scriptName (CarrierRegistry), never by the front end. IMPORTANT: pickupPointManual (manually entered place) is an admin-only path (order/build); the checkout never reads it from the payload, otherwise a customer could inject a custom pickup point outside the carrier widget.
paymentMethodId (?int),
voucherCodes (list),
customer (array): firstname/lastname/email/phone/street/city/postcode plus countryCode (ISO 2; drives the VAT treatment, the country text is derived from it via the code list) and companyName/regNo/vatId (only with isCompany),
isCompany / isVatPayer (bool): the server derives userTypeId and buyerType from them,
useDelivery (bool) + delivery (array): delivery address (including countryCode, which decides the place of supply for goods),
userId (?int), currencyId / languageId (?int), note (?string), ip (?string),
persist (bool, default false): false = preview and shipping/payment offer without a single write; true = binding submit (strict reservation, payment, status transition).

Parameters

$payload : array<string, mixed>

Return values

array{success: bool, errorCode?: string, message?: string, id?: int, orderNumber?: string, statusKey?: string, paymentId?: ?int, requiresGateway?: bool, order?: array, options?: array, totalWeight?: string, warnings?: list, shortItems?: list}|ApiPermissionDeniedShape

internalActionCreditNote()

Issues a partial credit note. Thin bridge to {@see OrderCreditNoteManager::issuePartial()}, which holds the per-order lock and the cap; no logic of its own here.


    public
                    internalActionCreditNote(int $id[, array<string, array<int, int>> $lines = [] ]) : array{success: bool, errorCode?: string, message?: string, invoiceId?: int|null, invoiceNumber?: string|null, final?: bool}|ApiPermissionDeniedShape

Parameters

$id : int
$lines : array<string, array<int, int>> = []: collection => (line id of the source invoice => pieces)

Return values

array{success: bool, errorCode?: string, message?: string, invoiceId?: int|null, invoiceNumber?: string|null, final?: bool}|ApiPermissionDeniedShape

internalActionCreditNotePreview()

Base for the admin partial credit note form: lines of the source invoice with the remainder. Read only (no lock); the authoritative cap check happens in {@see internalActionCreditNote()}.


    public
                    internalActionCreditNotePreview(int $id[, int|null $complaintId = null ]) : array<string|int, mixed>

Parameters

$id : int
$complaintId : int|null = null

Return values

array<string|int, mixed>

internalActionItemPrefill()

Picker prefill: thin bridge to {@see OrderManager::getItemPrefillData()}.


    public
                    internalActionItemPrefill(int $setId, int $quantity, int $currencyId, int $languageId[, int|null $paymentRegionId = null ]) : array{success: bool, message?: string, errorCode?: string, code?: ?string, name?: string, unit?: ?string, vat?: string, price?: string}|ApiPermissionDeniedShape

Parameters

$setId : int
$quantity : int
$currencyId : int
$languageId : int
$paymentRegionId : int|null = null

Return values

array{success: bool, message?: string, errorCode?: string, code?: ?string, name?: string, unit?: ?string, vat?: string, price?: string}|ApiPermissionDeniedShape

internalActionMyOrders()

"My orders" list, thin bridge to {@see OrderCheckoutManager::listForUser()}. `$userId` is a server-authoritative parameter of the front presenter (from `$this->getUser()->getId()` after the login check); this action authenticates nobody itself and relies on the calling page being `logged=1` (see the front `MyOrderListPresenter`).


    public
                    internalActionMyOrders(int $userId[, int $limit = 20 ][, int $offset = 0 ]) : array{success: bool, orders: list>, total: int}|ApiPermissionDeniedShape

Parameters

$userId : int
$limit : int = 20
$offset : int = 0

Return values

array{success: bool, orders: list>, total: int}|ApiPermissionDeniedShape

internalActionRepeatItems()

Base for "repeat order", thin bridge to {@see OrderCheckoutManager::repeatItems()}.


    public
                    internalActionRepeatItems(int $orderId, int $userId) : array{success: bool, errorCode?: string, message?: string, items?: list, skippedCount?: int}|ApiPermissionDeniedShape

Parameters

$orderId : int
$userId : int

Return values

array{success: bool, errorCode?: string, message?: string, items?: list, skippedCount?: int}|ApiPermissionDeniedShape

internalActionSetBuyers()

Tells whether a user bought a set, thin bridge to {@see OrderCheckoutManager::buyersOfSet()}.


    public
                    internalActionSetBuyers(int $setId[, string $userIds = '' ]) : array{success: bool, userIds: list}|ApiPermissionDeniedShape

Serves the "verified purchase" badge on reviews and the permission to write a review.

$userIds is a comma-separated list (the bridge sends scalars, not arrays, same as :Api:System:User:publicProfiles). Only a subset of the input ids is returned, i.e. a bought/not bought flag for users whose reviews are already visible on the page; no order data, no personal data.

IMPORTANT: internal (bridge-only) action, it must not get an action*()/render*() counterpart; otherwise it would become reachable over HTTP.

Parameters

$setId : int
$userIds : string = ''

Return values

array{success: bool, userIds: list}|ApiPermissionDeniedShape

internalActionSummary()

Data for the checkout return page (`api/eshop/order/summary`). The state is read only from the order and its paired payment, never from gateway GET parameters.


    public
                    internalActionSummary(int $id[, int|null $userId = null ]) : array{success: bool, errorCode?: string, message?: string, order?: array}|ApiPermissionDeniedShape

Parameters

$id : int
$userId : int|null = null

Return values

array{success: bool, errorCode?: string, message?: string, order?: array}|ApiPermissionDeniedShape

internalActionTransition()

Thin bridge to {@see OrderTransitionManager::apply()}. The status form is the only admin entry point and may call only this (no status logic of its own in the presenter or the form).


    public
                    internalActionTransition(int $id, int $statusId[, array<string, mixed> $opts = [] ]) : array{success: bool, message?: string, errorCode?: string, noop?: bool, warnings?: list, invoiceId?: int|null, stockDocumentId?: int|null}|ApiPermissionDeniedShape

Parameters

$id : int
$statusId : int
$opts : array<string, mixed> = []

Return values

array{success: bool, message?: string, errorCode?: string, noop?: bool, warnings?: list, invoiceId?: int|null, stockDocumentId?: int|null}|ApiPermissionDeniedShape

isPersonalDataPolicyExempt()

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


    public
                    isPersonalDataPolicyExempt(string $action) : bool

Only a presenter that returns exclusively the caller's own data and has no identity in the audience context at response time may override it. Typically login: it returns the account just verified, but the JWT is only being created, so without the exemption users would get their own e-mail masked.

Parameters

$action : string

Return values

bool

sendJson()

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


    public
                    sendJson(mixed $data) : void

The policy runs right before sending, after the query cache, where the caller is known. The internal path is handled the same way in ApiBridge.

Parameters

$data : mixed

setApiCallSource()

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


    public
                    setApiCallSource(string|null $source) : void

Parameters

$source : string|null

setAuthenticatedPayload()

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


    public
                    setAuthenticatedPayload(JwtPayload|null $payload) : void

Parameters

$payload : JwtPayload|null

setConfigParameters()


    public
                    setConfigParameters([bool $debugMode = false ][, bool $productionMode = false ]) : void

Parameters

$debugMode : bool = false
$productionMode : bool = false

setQueryCacheEnabled()

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


    public
                    setQueryCacheEnabled(bool $enabled) : void

A presenter is created anew for every internal call (PresenterFactoryCallback calls createService(), not getService()), so the value has nowhere to carry over; the bridge still sets it on every call and resets it to the default in finally.

Parameters

$enabled : bool

startup()


    public
                    startup() : void

applyCors()

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


    protected
                    applyCors() : void

IMPORTANT: it must be called in startup() before checkJwtAuth(); a preflight sends no Authorization, so it would otherwise end with 401.

checkApiPermission()

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


    protected
                    checkApiPermission() : void

checkClientCallerLimit()

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.


    protected
                    checkClientCallerLimit() : void

checkClientKey()

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.


    protected
                    checkClientKey() : void

checkJwtAuth()


    protected
                    checkJwtAuth() : void

exemptPersonalDataForCapabilityHolder()

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


    protected
                    exemptPersonalDataForCapabilityHolder(int|null $id) : void

An anonymous editor holding the advert password (capability) is an owner for isOwner(), but PersonalDataPolicy recognizes an owner only by identity (userId). Without this exemption the anonymous editor would get a masked e-mail (and masked e-mails in parameter texts) in the edit form, and saving would fail validation or write the mask back.

Called from internalActionGet() after the guard. Without a capability in the token it costs no queries; with one it costs a single find(). The caller is an owner only for the response of this get, only when the capability matches this record (scope, id, expiry, password fingerprint from the DB) and only for the rows of that record (advert and its parameters). The user from includes, reactions or another advert in the same response stay masked.

The query cache is unaffected: it stores the hydrator output before the policy, and both the mask and the exemption apply only to the outgoing copy (see PersonalDataPolicy).

Parameters

$id : int|null

filterReadPayload()

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


    protected
                    filterReadPayload(array<string, mixed> $payload, string $action) : array<string, mixed>

The default is identity. There is no blanket read tier (#[ExternalReadonly] and #[ExternalAdminOnly] strip only writes); this hook gives a presenter a place to implement one when its data requires it. Overridden by UserPresenter (the owner grant on :Api:System:User:get would otherwise let an owner read their own password, salt and activationKey over external HTTP) and by CustomAssetPresenter and PageSectionPresenter (an unprivileged caller gets active records only, see InactiveRecordsReadFilterTrait).

IMPORTANT: it runs after the cache (QueryCache), because the result depends on the caller, not on the query. Filtering inside the cache would freeze the payload shape of the first caller for everyone else.

It is called from get (GetTrait), getBy (GetByTrait), getAll (GetAllTrait) and search (SearchTrait), each with its action name. Because the default is identity, only presenters that override the hook are affected.

Parameters

$payload : array<string, mixed>
$action : string

Return values

array<string, mixed>

getRbacDecision()

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


    protected
                    getRbacDecision() : PermissionDecision|null

Return values

PermissionDecision|null

getRbacKey()


    protected
                    getRbacKey() : string|null

Return values

string|null

getRbacRawDecision()

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


    protected
                    getRbacRawDecision() : PermissionDecision|null

Return values

PermissionDecision|null

getRequestParameters()

Returns the parameters of the current request.


    protected
                    getRequestParameters() : array<string, mixed>

The request is always set during action*(); the helper only turns the nullable getRequest() into an always-array.

Return values

array<string, mixed>

getSessionKey()

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


    protected
                    getSessionKey([string|null $namespace = null ][, string|null $subsection = null ], string ...$extra) : string

Parameters

$namespace : string|null = null: Base namespace (module prefix). Uses SESSION_NAMESPACE if null.
$subsection : string|null = null: Subsection under the namespace. Uses SESSION_SUBSECTION constant if null.
$extra : string: Additional parts to append (e.g. 'step1', 'wizard', etc.).

Return values

string

getSessionSection()

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


    protected
                    getSessionSection([string|null $namespace = null ][, string|null $subsection = null ], string ...$extra) : SessionSection

Parameters

$namespace : string|null = null
$subsection : string|null = null
$extra : string

Return values

SessionSection

initializePresenterContext()


    protected
                    initializePresenterContext() : void

isCallerTierProbeActive()

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


    protected
                    isCallerTierProbeActive() : bool

apiRbacConfig exists (a presenter outside DI leaves the probe inert, like the guard);
internalMode is not off: then it is false after two comparisons, so no DB queries, no log lines and no debug_backtrace(), exactly like the guard (requireApiPermission());
the call is on the internal (bridge) path; the external path has its own tier mechanism ($meta['__externalTier']).

The order is deliberate: cheapest first, isInternalTransport() is not called in off.

Return values

bool

isClientKeyExempt()

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


    protected
                    isClientKeyExempt() : bool

Return values

bool

isOwner()

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


    protected
                    isOwner(object $entity, int $userId[, array<string|int, mixed> $data = [] ]) : bool

IMPORTANT: never change this to return true; it would open every endpoint with one line.

Parameters

$entity : object: entity loaded by the $owned closure from the DB by the id from the method parameter, never built from request data
$userId : int: ID from the JWT payload, never from a internalAction* parameter
$data : array<string|int, mixed> = []: write payload; on INSERT the only source of identifiers (parent); ownership is never read from it

Return values

bool

isPublicAction()

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


    protected
                    isPublicAction() : bool

IMPORTANT: the visibility is protected (not private) because RbacCheckTrait uses it too: the RBAC gate must evaluate #[PublicAction] exactly like the JWT guard, otherwise the two layers diverge. Single source of truth.

An empty action returns false (fail-closed): "action not recognized" must not mean "public", otherwise a presenter without an action* method would pass without authentication and authorization. On the external HTTP path the action is never empty because ApiRouteFactory defaults the route to 'action' => 'show'; the empty case occurs only in-process or if someone removes that default, and then it ends in 401 (guard) / 403 (gate) instead of a bypass.

Return values

bool

isQueryCacheEnabled()


    protected
                    isQueryCacheEnabled() : bool

Return values

bool

isReceiver()

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


    protected
                    isReceiver(object|null $entity, int|null $userId[, array<string|int, mixed> $data = [] ]) : bool

Unlike self::isOwner(), $userId may be null: the recipient can also be an anonymous editor with a capability or the holder of a key from an e-mail link.

IMPORTANT: never change this to return true; it would let anyone read records addressed to others.

Parameters

$entity : object|null: entity loaded by the $owned closure from the DB by the id from the method parameter, never from request data; null means nothing to judge
$userId : int|null: ID from the JWT payload, null means no identity
$data : array<string|int, mixed> = []: explicit parameters of the internal call supplied by the calling action (e.g. ['readKey' => ...] for markReadByKey); never present on the external path

Return values

bool

isSameSiteRequest()

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


    protected
                    isSameSiteRequest() : bool

getHttpRequest() returns the IRequest interface, while isSameSite() exists only on Nette\Http\Request.

Return values

bool

operation()

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


    protected
                    operation(string $method, callable(): T $body) : T

Every internalAction*() consists of return $this->operation(__FUNCTION__, function () { ... });; both transports call it (HTTP from action*(), ApiBridge by reflection), so this is the single place where an operation begins and ends. The presenter only reports the transport and the outcome; what a store does about it is up to the participants of OperationScope.

Observation off (the default): only the body runs. On: an operation started inside another one only joins it. The outcome comes from the returned envelope: success=true succeeded, success=false rejected (failed for a technical ResultCode), anything else unknown. An exception is recorded as failed and rethrown unchanged; the result is never changed. The only exception of its own is OperationContractViolationException after a body that did not throw (scoped mode, outside production by default): the result is then dropped.

Parameters

$method : string
$body : callable(): T

Return values

ownsByCapability()

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


    protected
                    ownsByCapability(object $entity) : bool

Default false; overridden by a presenter whose records can be edited with a password (Bazaar/Comcat advert). The decision is made on the entity loaded from the DB, never on request data.

Parameters

$entity : object

Return values

bool

readBodyParameter()

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


    protected
                    readBodyParameter(string $name) : string|null

Use it for secret inputs (passwords, reset and activation keys, tokens) that must not end up in the URL: the query string is written to web server and proxy access logs and to the client history. Nette takes action*() parameters only from the URL, so these actions have no parameters in the signature and read them here.

Returns null when the value is missing from the body or is not a scalar.

Parameters

$name : string

Return values

string|null

rejectForbiddenQueryPaths()

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


    protected
                    rejectForbiddenQueryPaths(array<string|int, mixed> $filters[, array<string|int, mixed>|null $orderBys = null ][, array<string|int, mixed>|null $columns = null ]) : array<string|int, mixed>|null

Fields hidden by FieldAccess read or PersonalData must not be usable in a query, otherwise the presence of a record in the response is an oracle (blind extraction of a password hash through filters[...][field]=user.password with like). The rule is held by QueryPathPolicy.

Call it in internalAction*() right after the guard (so the audience is set) and before the first query; it is the single place for getAll, getBy, search, deleteAll, myList, myOne and the advert lists. Same contract as the guard: null means continue, an array is the response to return. On the external path it sets HTTP 400 (see RequestShapeGuardTrait); nothing is silently ignored.

Parameters

$filters : array<string|int, mixed>
$orderBys : array<string|int, mixed>|null = null
$columns : array<string|int, mixed>|null = null

Return values

array<string|int, mixed>|null

reportCallerTierGap()

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:


    protected
                    reportCallerTierGap(string $kind, string $action, string $tier, string $label, array<int, string> $fields) : void

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

NOTE: the line filters and changes nothing; it only says what a future enforcement would take. An empty set is logged too (would_*=-) as proof that the probe ran there and nothing would break.

Parameters

$kind : string: save or updateColumns
$action : string: camelCase literal of the action (to build the RBAC key)
$tier : string
$label : string: field name in the log: would_strip or would_drop
$fields : array<int, string>

requireApiPermission()

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


    protected
                    requireApiPermission(string $action[, Closure|null $owned = null ][, array<string|int, mixed> $ownedData = [] ]) : ApiPermissionDeniedShape|null

Parameters

$action : string: camelCase literal of the action (getAll, updateColumns, moveSubtreeTo); never getAction() and never kebab-case from the URL
$owned : Closure|null = null: lazy entity loader for ALLOW_IF_OWNER; called only when the resolver returns a conditional grant, so an admin delete does not pay a DB query for a check that never runs; null means fail-closed DENY
$ownedData : array<string|int, mixed> = []: write payload passed to self::isOwner() for the insert branch ($entity === null), where it is the only source of the parent identifier; empty for all other actions

Return values

ApiPermissionDeniedShape|null —

exact shape of permissionDeniedPayload() instead of a generic array<string, mixed>; guarded methods with their own precise @return array{...} union this type into theirs

requireManager()

Returns the manager for the shared CRUD/tree actions.


    protected
                    requireManager() : Manager

Presenters without a manager (login, payment callbacks) do not have these actions. If one is reached anyway, it throws LogicException naming the presenter instead of an unhelpful "call on null".

Return values

Manager

resolveApiPresenterName()

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


    protected
            static        resolveApiPresenterName(class-string $class) : string

Inverse of the mapping in config/common.neon (Api: [App\UI, Api\*, Presenters\*Presenter]); ApiPermissionCoverageTest verifies it against the live Nette\Application\PresenterFactory.

IMPORTANT: the module is deliberately only one segment. The Nette mapping Api\*\ behaves oddly for multi-level names (Api:A:B:C maps to App\UI\Api\A\Api\B\Presenters\CPresenter), so "smart" extra segments would silently build a key that does not exist in the DB. Fail-closed: an unknown class shape throws and ends as DENY, no guessing.

Parameters

$class : class-string

Return values

string

resolveCallerFrame()

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.


    protected
            static        resolveCallerFrame() : string

The path is relative to the project root, not a basename: two ProductPresenter.php in two modules would otherwise merge into one report line.

Return values

string

resolveCallerTier()

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


    protected
                    resolveCallerTier(string $action) : string

Decided solely by PermissionResolver::isGrantedByPrivilegedRole(), the same method the external path uses (RbacCheckTrait::resolveExternalFieldTier()), so there is one decision core. Only the key source differs: the external path uses $this->rbacKey; the internal path uses static::class plus the literal $action, because on the bridge getName() is null and getAction() is '', which would build the key '::'.

Cost: isGrantedByPrivilegedRole() reuses grantingRoleCodes(), which runs from the same per-request branchCache as decide() in the guard, so it is an isset(). The only extra query per request is privilegedRoleCodes(), also request-cached. No own cache is added on purpose: a second cache is a second place to forget invalidation.

Fail-closed to user (the stricter tier): a missing resolver (presenter outside DI) and any exception.

Parameters

$action : string: camelCase literal of the action, the same one requireApiPermission() gets

Return values

string

resolveExternalFieldTier()

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


    protected
                    resolveExternalFieldTier() : string

Returns 'privileged' only when the grant for this request ($this->rbacKey, computed only in checkApiPermission(), never again from the request) comes from a role with privileged = 1 (the flag decides, never the role name). Called by SaveTrait::actionSave(), the same place that sets $meta['__external'].

Fail-closed to 'user':

$rbacKey === null: the gate is off or the key could not be built; without a decision nobody can be declared privileged.
A caller without a token (guest, even with an application key) cannot hold a privileged role.
A client whose application key does not allow a privileged role: the resolver drops it from the caller roles (role ceiling), so the tier falls to 'user'.

In log mode the tier works the same as in enforce: it is an independent second layer of field protection, not part of the URL/action gate (same as #[ExternalReadonly]).

Return values

string

sendInvalidRequestParameter()


    protected
                    sendInvalidRequestParameter(string $name) : void

Parameters

$name : string

shouldProduceNotifications()

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


    protected
                    shouldProduceNotifications() : bool

Admin does not create them; an unknown source does, as a safety net.

Return values

bool

verifyOwnership()

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


    protected
                    verifyOwnership(int $userId) : bool

Same base as self::verifyReceiver(): takes the record id from the request (id for get/delete, data.id for save), loads the record from the database via $this->manager->find() and passes only an entity implementing OwnerAwareInterface whose getOwnerUserId() is positive and equals $userId. Returns false without an id (an INSERT, i.e. save without data.id, has no owner; presenters handle it in their own canUserWrite), without a manager, without a record, without the interface, or with an owner of null/0 (anonymous record).

Concrete Api presenters override it and delegate to their Api manager (OwnershipCheckTrait); this base applies only to a presenter that does not.

IMPORTANT: never change this to return true, it would open every CRUD presenter at once.

Parameters

$userId : int: ID from the JWT payload, never from the request

Return values

bool

verifyReceiver()

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


    protected
                    verifyReceiver(int|null $userId) : bool

External path: reads only the request identifiers (id) and decides against the database. The identity comes from the JWT; $userId = null is legitimate (anonymous editor with a capability). read_key is never taken from outside; that branch exists only on the internal path (ApiPermissionGuardTrait::isReceiver()).

A concrete presenter may extend it (each domain defines its own receiver).

IMPORTANT: never change this to true.

Parameters

$userId : int|null: ID from the JWT payload, null means no identity

Return values

bool

apiClientContext()


    private
                    apiClientContext() : ApiClientContext|null

Return values

ApiClientContext|null

apiPermissionTokenHint()

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


    private
                    apiPermissionTokenHint() : string

Return values

string

buildApiPermissionKey()

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.


    private
                    buildApiPermissionKey() : string

Return values

string

createdIdForNotification()

Id of a newly created record from the `internalActionSave()` response, or `null` when nothing should be notified: update (`$data` had the id), failure, or a call from the admin.


    private
                    createdIdForNotification(array<string, mixed> $data, array<string, mixed> $response) : int|null

Parameters

$data : array<string, mixed>: payload before saving
$response : array<string, mixed>: response of internalActionSave()

Return values

int|null

extractBearerToken()


    private
                    extractBearerToken() : string|null

Return values

string|null

failureArray()


    private
                    failureArray(Result $result) : array{success: false, errorCode: string, message: string}

Parameters

$result : Result

Return values

array{success: false, errorCode: string, message: string}

fieldAudience()

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


    private
                    fieldAudience() : FieldAudienceContext|null

The audience is only a supplement and must never be able to decide access.

Return values

FieldAudienceContext|null

getOwnershipRecordId()

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.


    private
                    getOwnershipRecordId() : int|null

Return values

int|null

initializeCurrency()


    private
                    initializeCurrency(int|string|null $defaultCurr) : void

Parameters

$defaultCurr : int|string|null

initializeLanguage()


    private
                    initializeLanguage(int|string|null $defaultLang) : void

Parameters

$defaultLang : int|string|null

internalActionPaymentMethods()

Front footer (`PaymentMethodListComponent`, `api/eshop/order/payment-methods`): names of the available payment methods (no prices, no entity), thin bridge to {@see PaymentMethodManager::listAvailableForLanguage()}.


    private
                    internalActionPaymentMethods(int $languageId) : array{success: bool, items?: list}|ApiPermissionDeniedShape

IMPORTANT: internal (bridge-only) action, private, with no action*()/render*() counterpart (same convention as internalActionSetBuyers()); otherwise it would become reachable over HTTP. It reuses the RBAC key checkout (:Api:Eshop:Order:checkout) instead of seeding a new row for this one footer widget; guests are already allowed to preview the checkout, so it suits a plain method list too. ApiPermissionCoverageTest allows exactly this reuse for non-public methods.

Parameters

$languageId : int

Return values

array{success: bool, items?: list}|ApiPermissionDeniedShape

isInternalTransport()

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


    private
                    isInternalTransport() : bool

IMPORTANT: do not write it as $this->getRequest() === null. In this nette/application version Presenter::$request is private ?Request $request = null and the final public function getRequest(): Application\Request throws InvalidStateException('Request is not set, presenter is not running.') when no request is set, because its return type is not nullable. A naive null comparison would throw on the internal path.

The catch is narrow (only InvalidStateException) and stands outside the catch-all of the guard; otherwise "no request" would mean DENY instead of "I am internal". The transport is decided by framework state, not by a value from the wire.

Return values

bool

loadLocalization()


    private
                    loadLocalization() : Localization|null

Return values

Localization|null

localizationCurrencyKey()

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


    private
                    localizationCurrencyKey(object $localization) : string|null

A localization has no currency of its own. Null means a localization without a region or a region without a currency; callers fall back to eur.

Parameters

$localization : object

Return values

string|null

logApiPermissionDecision()

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.


    private
                    logApiPermissionDecision(string $mode, bool $internal, string $key, string $presenter, string $action, int|null $userId, PermissionDecision $raw, PermissionDecision $effective, bool $denied) : void

mode= is always the mode of this path (internalMode internally, mode externally), otherwise the report would claim something other than what was just evaluated.

IMPORTANT: key_exists=no separates two cases that decision=DENY merges: "the key exists in the policy and the caller has no right to it" and "the key is not in cms_system_user_role_privileges at all" (a typo in the literal, a forgotten seed). A method that reuses a foreign literal gets ALLOW from decide(), but not for its own policy. It is computed by PermissionResolver::hasKey(), the same probe SaveTrait::refineSaveAction() uses. Radar for this class of mistake: grep 'API_RBAC.*key_exists=no' auth.log.

NOTE: it is not free as in SaveTrait. hasKey() reads the anonymous branch of branchCache (rowsForKey(null, ...)), while decide() reads the caller with their $userId; only anonymous callers share the cache. For a logged-in caller it is one small indexed query, paid only when the line is actually written (log always, enforce only on DENY), the same cost as caller=.

caller= (i.e. debug_backtrace()) is computed only when the line is written, otherwise it would be a needless cost on every request. DEBUG_BACKTRACE_IGNORE_ARGS is required: a backtrace with arguments would put huge objects into the log.

Parameters

$mode : string
$internal : bool
$key : string
$presenter : string
$action : string
$userId : int|null
$raw : PermissionDecision
$effective : PermissionDecision
$denied : bool

logRbacDecision()

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.


    private
                    logRbacDecision(string $key, int|null $userId, PermissionDecision $raw, PermissionDecision $effective) : void

key_exists= has the same field and meaning as ApiPermissionGuardTrait::logApiPermissionDecision(): it distinguishes "key exists, role denies" from "key is missing in cms_system_user_role_privileges". It is computed via PermissionResolver::hasKey() only when a line is actually written.

Parameters

$key : string
$userId : int|null
$raw : PermissionDecision
$effective : PermissionDecision

permissionDeniedPayload()

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.


    private
            static        permissionDeniedPayload() : ApiPermissionDeniedShape

Return values

ApiPermissionDeniedShape

produceNotification()


    private
                    produceNotification(string $typeKey, int $itemId, string $text) : void

Parameters

$typeKey : string
$itemId : int
$text : string

rbacTokenHint()

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


    private
                    rbacTokenHint() : string

Read from the header directly so the trait does not depend on private methods of JwtAuthTrait.

Return values

string

refuseClientKey()

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.


    private
                    refuseClientKey(ApiClientKeyStatus $status, int|null $clientId[, int|null $keyId = null ]) : void

Parameters

$status : ApiClientKeyStatus
$clientId : int|null
$keyId : int|null = null

refuseClientLimit()

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.


    private
                    refuseClientLimit(ApiClientIdentity $client, ApiClientLimitResult $limit) : void

Parameters

$client : ApiClientIdentity
$limit : ApiClientLimitResult

reportJwtAuthFailure()


    private
                    reportJwtAuthFailure(string $reason, string|null $token) : void

Parameters

$reason : string
$token : string|null

resolveGuardMode()

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


    private
                    resolveGuardMode(bool $internal) : string

$apiRbacConfig can be missing only in a presenter built outside DI (new XPresenter() in a harness), where no RBAC is evaluated anyway. isset() on an uninitialized typed property returns false without throwing.

Parameters

$internal : bool

Return values

string

OrderPresenter extends BasePresenter in package Application uses CrudTrait, NotificationProducerTrait

Table of Contents

Constants

Properties

Methods

Constants

CALLER_TIER_PRIVILEGED

CALLER_TIER_USER

SESSION_NAMESPACE

CALLER_BACKTRACE_LIMIT

CALLER_SKIPPED_PATHS

Properties

$accessTokenValidator

Attributes

$allowedMethods

$apiClientContext

Attributes

$apiClientKeyConfig

Attributes

$apiClientManager

Attributes

$apiClientRateLimiter

Attributes

$apiRbacConfig

Attributes

$authLogManager

Attributes

$corsConfig

Attributes

$currencyContext

Attributes

$currencyManager

Attributes

$fieldAudienceContext

Attributes

$jtiDenyList

Attributes

$jwtGuardConfig

Attributes

$jwtManager

Attributes

$lang

$languageContext

Attributes

$languageManager

Attributes

$localizationContext

Attributes

$localizationManager

Attributes

$localizationPaymentRegionManager

Attributes

$notificationManager

Attributes

$notificationTypeManager

Attributes

$operationScope

Attributes

$pageManager

Attributes

$permissionResolver

Attributes

$personalDataPolicy

Attributes

$presenterContext

Attributes

$queryCache

Attributes

$queryPathPolicy

Attributes

$securityConfig

Attributes

$settingContext

Attributes

$settingManager

Attributes

$debugMode

$manager read-only

$productionMode

$anonymousDenyReported

OrderPresenter extends BasePresenter
in package

Application

uses CrudTrait, NotificationProducerTrait