CoolCMS API

AdvertPresenter extends BasePresenter
in package

Application

uses CrudTrait, PublicAdvertReadFilterTrait, OwnershipCheckTrait, RegisterEventTrait, SearchTrait

FinalYes

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=`.
ENTITY_CLASS : string = 'App\UI\Api\Comcat\Models\Entities\Advert'
SEARCH_DEFAULT_LIMIT : mixed = 20: Fallback page size when the caller sends no `limit`.

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
$advertConfirmationManager : AdvertConfirmationManager
$advertManager : AdvertManager
$advertPasswordResetManager : AdvertPasswordResetManager
$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.
$esSearcher : EsSearcher
$hydrator : OrmEntityHydrator
$jwtPayload : JwtPayload|null
$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
actionExtendExpiration() : void
actionRegisterEvent() : void
actionResetPassword() : never: Public setting of a new advert password from a one-time link.
actionSendPasswordReset() : never: Public request for a new-password link of an advert placed without an account.
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).
internalActionConfirmByKey() : array<string, mixed>: Confirms a company profile by the key from the `CC_ADVERT_ACTIVATION_REQUEST` e-mail (link `?do=confirm&key=…`).
internalActionExtendExpiration() : array<string, mixed>
internalActionRedeemManageKey() : array<string, mixed>: Redeems the "Manage advert" link from the `CC_ADVERT_INSERT` e-mail (`edit?id=…&manageKey=…`).
internalActionRegisterEvent() : array<string, mixed>
internalActionResetPassword() : array<string, mixed>
internalActionSearch() : array<string|int, mixed>: Endpoint `api/{module}/{entity}/search` (internal bridge to `internalActionSearch`).
internalActionSendPasswordReset() : array<string, mixed>
isPersonalDataPolicyExempt() : bool: Returns whether the response of the action skips the personal data policy; the default is no action.
registerEvent() : Result
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>
getEsSearcher() : EsSearcher
getEsSourceKey() : string
getFulltextFallbackFields() : array<int, string>: Returns the fields of the MySQL fulltext fallback used when Elasticsearch is unavailable.
getFulltextTranslationsPath() : string|null: Returns the path to translations when the fallback fields live in them (`translations`); fulltext is then limited to the request language ({@see TranslationScopeFilters}). `null` means the source is not translated (advert, message). A presenter of a translated source overrides it.
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.
inactiveFilterDependentClasses() : array<string, string>
inactiveFilterEntityClass() : string
inactiveFilterHiddenFields() : array<int, string>
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()}).
isLiveRecord() : bool
isOwner() : bool: Decides whether the user owns the advert; internal path, custom classification.
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: 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).
ownedForUpdateColumns() : Closure|null: Returns a lazy loader of the advert for `updateColumns`; mirrors Bazaar, see {@see \App\UI\Api\Bazaar\Presenters\AdvertPresenter::ownedForUpdateColumns()}.
ownsByCapability() : bool: Tells whether the caller holds a capability for this very advert (scope, id, expiration and password fingerprint from the database).
publicReadIsAdvert() : bool
readBodyParameter() : string|null: Returns a value from the request body: `application/x-www-form-urlencoded` or `multipart` (POST fields) and `application/json`.
registerEventProperties() : array<int, string>: Returns the counters a caller may increment. Positive allowlist: anything else ends as `INVALID_VALUE`, not as a write.
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: Checks ownership for the `:Api:Comcat:Advert:save` and `:Api:Comcat:Advert:delete` keys.
verifyReceiver() : bool: Default `receiver` check: is the caller the receiver of this record (who it was sent to, not who created it)? Fail-closed.
apiClientContext() : ApiClientContext|null
apiPermissionTokenHint() : string: Returns the first 12 characters of the Bearer token, in the same shape as `API_RBAC ... token=` from the external gate. On the internal path the `Authorization` header is usually empty, giving `-`.
buildApiPermissionKey() : string: Builds the key such as `:Api:Eshop:Order:updateColumns` from `getName()` + `getAction()`, never from the URL: Nette `Route::$styles['action']` applies `path2action`, so the URL `update-columns` is `updateColumns` inside the presenter, and the optional `<loc>` route segment is not part of the key.
extractBearerToken() : string|null
fieldAudience() : FieldAudienceContext|null: Returns the audience context, or `null` when the presenter did not get it through DI.
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.
highlightsForItems() : array<int, array<string, string>>: Narrows the ES snippet map to ids that are really in the extracted list.
initializeCurrency() : void
initializeLanguage() : void
isInternalTransport() : bool: Returns true when `Presenter::run()` did not run, i.e. the call is on the internal (bridge) path.
itemId() : int|null: Returns the id of an extracted item. `extractAll` emits an item as a reference `['id' => <scalar|[field => value]>]` (see `OrmEntityHydrator::scalarizedIdentifierValues`): a single-column identity arrives wrapped in an array, a composite identity as several pairs (unsupported, `null`).
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.
orderItemsByIds() : array<int, mixed>: Reorders extracted items into the order ES returned the ids (i.e. by score).
permissionDeniedPayload() : ApiPermissionDeniedShape: Returns the denial shape, identical to what the external gate sends ({@see RbacCheckTrait::checkApiPermission()}), but returned instead of `sendJson()` because the internal path has nowhere to send an HTTP status.
rbacTokenHint() : string: Returns the first 12 characters of the Bearer token, in the same shape as `JWT_GUARD ... token=`.
refuseClientKey() : void: Sends one response for a missing, unknown, disabled, revoked and expired key, so the caller cannot tell which key exists. The reason, client id and key id (`cms_system_api_client_keys`, not the key itself) go only to the log; the key or any part of it never does.
refuseClientLimit() : void: Sends 429 with `Retry-After`. Only the first refusal in the window goes to the auth log, so a flood does not flood the log too.
reportJwtAuthFailure() : void
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.
resolveSearchLanguageId() : int|null: Returns the language id for the request alias; an unknown alias gives `null` (no restriction).

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.

ENTITY_CLASS


    private
        string
    ENTITY_CLASS
    = 'App\UI\Api\Comcat\Models\Entities\Advert'

SEARCH_DEFAULT_LIMIT

Fallback page size when the caller sends no `limit`.


    private
        mixed
    SEARCH_DEFAULT_LIMIT
    = 20

$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]

$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

$advertConfirmationManager read-only


        private
            AdvertConfirmationManager
    $advertConfirmationManager

$advertManager read-only


        private
            AdvertManager
    $advertManager

$advertPasswordResetManager read-only


        private
            AdvertPasswordResetManager
    $advertPasswordResetManager

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

$esSearcher read-only


        private
            EsSearcher
    $esSearcher

$hydrator read-only


        private
            OrmEntityHydrator
    $hydrator

$jwtPayload


        private
            JwtPayload|null
    $jwtPayload
     = null

$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

__construct()


    public
                    __construct(AdvertManager $advertManager, OrmEntityHydrator $hydrator, EsSearcher $esSearcher, AdvertPasswordResetManager $advertPasswordResetManager, AdvertConfirmationManager $advertConfirmationManager) : mixed

Parameters

$advertManager : AdvertManager
$hydrator : OrmEntityHydrator
$esSearcher : EsSearcher
$advertPasswordResetManager : AdvertPasswordResetManager
$advertConfirmationManager : AdvertConfirmationManager

actionExtendExpiration()


    public
                    actionExtendExpiration() : void

actionRegisterEvent()


    public
                    actionRegisterEvent(array<string|int, int> $ids, string $property) : void

Parameters

$ids : array<string|int, int>
$property : string

actionResetPassword()

Public setting of a new advert password from a one-time link.


    public
                    actionResetPassword(int $advertId, string $key, string $password) : never

An invalid, expired or used key (and an unknown advert) returns USER_PASSWORD_RESET_KEY_INVALID, a short password INVALID_LENGTH. The key :Api:Comcat:Advert:resetPassword has guest = 1.

Parameters

$advertId : int
$key : string
$password : string

#[PublicAction]

Return values

never

actionSendPasswordReset()

Public request for a new-password link of an advert placed without an account.


    public
                    actionSendPasswordReset(int $advertId, string $email) : never

Takes the advert id and the e-mail the visitor entered; the link is sent only when the e-mail matches the advert. The response is always success (also on mismatch, rate limit or delivery failure), because the advert e-mail is often visible on the detail and the action must not reveal whether a guess matched. The per-advert and per-IP limit is held by AdvertPasswordResetManager::sendPasswordReset().

The key :Api:Comcat:Advert:sendPasswordReset has guest = 1.

Parameters

$advertId : int
$email : string

#[PublicAction]

Return values

never

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

internalActionConfirmByKey()

Confirms a company profile by the key from the `CC_ADVERT_ACTIVATION_REQUEST` e-mail (link `?do=confirm&key=…`).


    public
                    internalActionConfirmByKey(int $advertId, string $key) : array<string, mixed>

The link is also opened by a guest poster, so security rests on the key (256 bits, only a digest stored), not on login. An unknown, deleted or banned advert, a wrong key and an exhausted limit all return the single code ADVERT_CONFIRMATION_KEY_INVALID; the logic and limit live in AdvertConfirmByKeyTrait.

Internal bridge only (no action*()); the key :Api:Comcat:Advert:confirmByKey has guest = 1.

Parameters

$advertId : int
$key : string

Return values

array<string, mixed>

internalActionExtendExpiration()


    public
                    internalActionExtendExpiration(int|null $advertId) : array<string, mixed>

Parameters

$advertId : int|null

Return values

array<string, mixed>

internalActionRedeemManageKey()

Redeems the "Manage advert" link from the `CC_ADVERT_INSERT` e-mail (`edit?id=…&manageKey=…`).


    public
                    internalActionRedeemManageKey(int $advertId, string $key) : array<string, mixed>

OK means the key matches an advert without an account, its current password, and is still valid (7 days); the front end then opens an edit session as after entering the password. Anything else returns USER_PASSWORD_RESET_KEY_INVALID. The logic lives in ManageKeyTrait.

Internal bridge only (no action*()); the key :Api:Comcat:Advert:redeemManageKey has guest = 1.

Parameters

$advertId : int
$key : string

Return values

array<string, mixed>

internalActionRegisterEvent()


    public
                    internalActionRegisterEvent(array<string|int, int> $ids, string $property) : array<string, mixed>

Parameters

$ids : array<string|int, int>
$property : string

Return values

array<string, mixed> —

Result envelope (success, message, data, code)

internalActionResetPassword()


    public
                    internalActionResetPassword(int $advertId, string $key, string $password) : array<string, mixed>

Parameters

$advertId : int
$key : string
$password : string

Return values

array<string, mixed>

internalActionSearch()

Endpoint `api/{module}/{entity}/search` (internal bridge to `internalActionSearch`).


    public
                    internalActionSearch([string $search = '' ][, string|null $languageAlias = null ][, array<int, Filter|array<string, mixed>> $filters = [] ][, array<string, mixed>|null $orderBys = null ][, int|null $offset = null ][, int|null $limit = null ][, string|array<int, string> $includes = [] ]) : array<string|int, mixed>

Parameters

$search : string = '': user query (empty or shorter than 2 characters: ES is not called at all)
$languageAlias : string|null = null: language alias (cs); the index is per language, an unknown alias falls back
$filters : array<int, Filter|array<string, mixed>> = []: visibility/context filters (ready objects or arrays for FilterBuilder)
$orderBys : array<string, mixed>|null = null: manual user order; null means relevance orders
$offset : int|null = null
$limit : int|null = null
$includes : string|array<int, string> = []

Return values

array<string|int, mixed> —

{items, totalCount, _references, fromEs, highlights} from extractAll, or the guard DENY envelope ({success: false, ...})

internalActionSendPasswordReset()


    public
                    internalActionSendPasswordReset(int $advertId, string $email) : array<string, mixed>

Parameters

$advertId : int
$email : string

Return values

array<string, mixed>

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

registerEvent()


    public
                    registerEvent(array<string|int, int> $ids, class-string $entityClass, string $property) : Result

Parameters

$ids : array<string|int, int>
$entityClass : class-string
$property : string

Return values

Result

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


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

Parameters

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

Return values

array<string, mixed>

getEsSearcher()


    protected
                    getEsSearcher() : EsSearcher

Return values

EsSearcher

getEsSourceKey()


    protected
                    getEsSourceKey() : string

Return values

string

getFulltextFallbackFields()

Returns the fields of the MySQL fulltext fallback used when Elasticsearch is unavailable.


    protected
                    getFulltextFallbackFields() : array<int, string>

Company profile texts are not columns but EAV rows (AdvertParameterRel.value), so the search runs over the same fields as the front end ParameterTrait::prepareAdvertSearchFilter().

Return values

array<int, string>

getFulltextTranslationsPath()

Returns the path to translations when the fallback fields live in them (`translations`); fulltext is then limited to the request language ({@see TranslationScopeFilters}). `null` means the source is not translated (advert, message). A presenter of a translated source overrides it.


    protected
                    getFulltextTranslationsPath() : string|null

Return values

string|null

getOwnedEntityId()

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


    protected
                    getOwnedEntityId() : int|null

See OwnershipPayload::entityId(), which tolerates data[ID]/data[_id]/'5'.

Return values

int|null

getOwnedParentId()

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


    protected
                    getOwnedParentId(string $property) : int|null

See OwnershipPayload::parentId().

Parameters

$property : string: name of the to-one property on the entity (camelCase, e.g. order)

Return values

int|null

getOwnedRequestId()

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


    protected
                    getOwnedRequestId() : int|null

NOTE: the router passes parameters as strings ('5'), hence the normalization. id can also be an array (bulk delete, DeleteTrait::internalActionDelete() takes int|array); then it returns null because "owner of one record" makes no sense there and the fail-closed deny is the right answer.

Return values

int|null

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

inactiveFilterDependentClasses()


    protected
                    inactiveFilterDependentClasses() : array<string, string>

Return values

array<string, string>

inactiveFilterEntityClass()


    protected
                    inactiveFilterEntityClass() : string

Return values

string

inactiveFilterHiddenFields()


    protected
                    inactiveFilterHiddenFields() : array<int, string>

Return values

array<int, string>

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

isLiveRecord()


    protected
                    isLiveRecord(array<string|int, mixed> $row) : bool

Parameters

$row : array<string|int, mixed>

Return values

bool

isOwner()

Decides whether the user owns the advert; internal path, custom classification.


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

Mirrors Bazaar, see AdvertPresenter::isOwner().

Advert has no getUserId(), the owner is held by insertUserId; the generic fallback would return false and lock the owner out of their own advert. The user association maps the same column insert_user_id (both carry #[ExternalReadonly], so they cannot diverge); the scalar is authoritative because the rest of the ownership stack reads it and getUser() is lazy.

A second rule grants ownership to the holder of a valid capability for this very advert (see Bazaar for the password-change invalidation). IMPORTANT: the scope is comcat.advert.edit, not the Bazaar one; otherwise a capability for Bazaar advert id 5 would authorize company id 5.

Parameters

$entity : object|null
$userId : int
$data : array<string|int, mixed> = []: write payload; on INSERT the only source of identifiers (parent), ownership is never read from it

Return values

bool

isOwnershipInsert()

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


    protected
                    isOwnershipInsert() : bool

Ownership is then verified through the parent's ownership or through a server-set owner.

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

ownedForUpdateColumns()

Returns a lazy loader of the advert for `updateColumns`; mirrors Bazaar, see {@see \App\UI\Api\Bazaar\Presenters\AdvertPresenter::ownedForUpdateColumns()}.


    protected
                    ownedForUpdateColumns(array<string|int, mixed>|int $ids) : Closure|null

Parameters

$ids : array<string|int, mixed>|int

Return values

Closure|null

ownsByCapability()

Tells whether the caller holds a capability for this very advert (scope, id, expiration and password fingerprint from the database).


    protected
                    ownsByCapability(object $entity) : bool

Shared by self::isOwner() and the personal-data mask exemption (BasePresenter::exemptPersonalDataForCapabilityHolder()).

Parameters

$entity : object

Return values

bool

publicReadIsAdvert()


    protected
                    publicReadIsAdvert() : bool

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

registerEventProperties()

Returns the counters a caller may increment. Positive allowlist: anything else ends as `INVALID_VALUE`, not as a write.


    protected
                    registerEventProperties() : array<int, string>

Return values

array<int, string>

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

Checks ownership for the `:Api:Comcat:Advert:save` and `:Api:Comcat:Advert:delete` keys.


    protected
                    verifyOwnership(int $userId) : bool

save INSERT: allowed; insertUserId is set by the server (AdvertManager::getExternalOwnerData()) and the client value is stripped (#[ExternalReadonly] on the scalar and on the $user association mapping the same column).
save UPDATE / delete: the advert must belong to the requester by insertUserId from the database.

IMPORTANT: a password-protected advert (guest poster, insertUserId is null) belongs to nobody, so the external API denies it. The front end edits it through the internal path by a session hash, which this gate does not see.

Parameters

$userId : int

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

extractBearerToken()


    private
                    extractBearerToken() : string|null

Return values

string|null

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

getOwnershipPayload()

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


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

NOTE: on the external HTTP path parameters are filled from the query string; the Nette router does not parse the POST body, so a JSON body is not seen here.

Return values

array<string|int, mixed>

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

highlightsForItems()

Narrows the ES snippet map to ids that are really in the extracted list.


    private
            static        highlightsForItems(array<int, array<string, string>> $highlights, array<int, mixed> $items) : array<int, array<string, string>>

IMPORTANT: ES highlights all its hits, but visibility is held by the database: a stale document of a deactivated article drops out of items, yet its title and perex would stay in the response without this filter, i.e. text of an entity the caller must not see. The condition is "the item is in the list", not "the id is in ES".

Parameters

$highlights : array<int, array<string, string>>
$items : array<int, mixed>

Return values

array<int, array<string, string>>

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

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

itemId()

Returns the id of an extracted item. `extractAll` emits an item as a reference `['id' => <scalar|[field => value]>]` (see `OrmEntityHydrator::scalarizedIdentifierValues`): a single-column identity arrives wrapped in an array, a composite identity as several pairs (unsupported, `null`).


    private
            static        itemId(mixed $item) : int|null

Parameters

$item : mixed

Return values

int|null

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

orderItemsByIds()

Reorders extracted items into the order ES returned the ids (i.e. by score).


    private
            static        orderItemsByIds(array<int, mixed> $items, array<int, int> $ids) : array<int, mixed>

The hydration phase 2 does not keep order (hydrateByIdentifiers orders as the database returns). The semantics match sortResultsByIdentifiers() (repository), only over an already extracted payload, so it needs no entity metadata. An item whose id is not in the ES order (composite PK, unexpected shape) keeps its relative order after the known ones and never vanishes.

Parameters

$items : array<int, mixed>
$ids : array<int, int>

Return values

array<int, mixed>

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

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

resolveSearchLanguageId()

Returns the language id for the request alias; an unknown alias gives `null` (no restriction).


    private
                    resolveSearchLanguageId(string|null $languageAlias) : int|null

Parameters

$languageAlias : string|null

Return values

int|null

AdvertPresenter extends BasePresenter in package Application uses CrudTrait, PublicAdvertReadFilterTrait, OwnershipCheckTrait, RegisterEventTrait, SearchTrait

Table of Contents

Constants

Properties

Methods

Constants

CALLER_TIER_PRIVILEGED

CALLER_TIER_USER

SESSION_NAMESPACE

CALLER_BACKTRACE_LIMIT

CALLER_SKIPPED_PATHS

ENTITY_CLASS

SEARCH_DEFAULT_LIMIT

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

$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

$advertConfirmationManager read-only

$advertManager read-only

$advertPasswordResetManager read-only

AdvertPresenter extends BasePresenter
in package

Application

uses CrudTrait, PublicAdvertReadFilterTrait, OwnershipCheckTrait, RegisterEventTrait, SearchTrait