CoolCMS API

ShipperTariffManager extends Manager
in package

Base class of Api managers whose traits delegate to a typed `Service<TEntity>`.

Tags
extends

Table of Contents

Constants

DELETED_IDS_META  : string = '__deletedIds'
Reserved `$meta` key with the ids of the entities being deleted, captured before the first hook.
FK_TARIFF  : mixed = 'cms_mod_eshop_shipper_tariffs_shipper_tariff_id'
TABLE_PAYMENT_PRICES  : mixed = 'cms_mod_eshop_payment_method_prices'
TABLE_PRICES  : mixed = 'cms_mod_eshop_shipper_tariff_prices'

Properties

$service  : Service<string|int, TEntity>
Manager service; subclasses narrow the type (`@property` in the Api/Admin/Front manager).
$appContext  : AppContext
$assetFormatRegistry  : AssetFormatRegistry|null
Format processor registry for file uploads, used by {@see \App\Core\Traits\Api\Models\Managers\AssetProcessingTrait}.
$cacheTagInvalidator  : CacheTagInvalidator|null
Post-commit invalidator of the wire-payload query cache (tag bump per entity class).
$internalCallContext  : InternalCallContext|null
Tells whether the call is an internal bridge call; the single source for reading uploaded items with `path` ({@see readUploadedItem()}).
$languageContext  : LanguageContext|null
$nonInvalidatingColumns  : array<string|int, string>
Columns whose update does not invalidate the cache: view counters (`registerEvent()` bumps the counter on every pageview). Without this every view would flush the query cache of the whole class; counters are therefore stale up to the TTL. Override per manager by redefining the property.
$paramsConfig  : Config|null
Neon parameters (`%params%`: server paths and directories), set by the decorator (`decorators.neon`) like `setAppContext()`.
$presenterContext  : PresenterContext
$settingContext  : SettingContext
$totalCount  : int|null
$useTransactionForDelete  : bool
$useTransactionForSave  : bool
$em  : EntityManagerInterface
$priceResolver  : ShippingPriceResolver
$rejectedUploads  : array<int, array{name: string, reason: string}>
New uploaded items that the Api did not save during the `save()` that is running right now (type, dimensions, unreadable, …). Filled by {@see recordRejectedUpload()} and returned in `saveInfo.rejectedUploads`.
$supplyKindManager  : SupplyKindManager
$unitOfWorkReset  : UnitOfWorkReset

Methods

__construct()  : mixed
branchWire()  : array{success: bool, code: string, id: ?int}
Builds the wire shape `{success, code, id}` of the `save-branch` response; the contract of the Api presenter stays unchanged ({@see saveBranch()}).
calculateTotalWeight()  : string
Returns the total order weight, the sum of weight times quantity; see {@see ShippingPriceResolver::calculateTotalWeight()}.
delete()  : Result
Deletes the entity or entities by id. Optional hooks (opt-in via `method_exists`, like {@see SaveTrait}) allow cleanup of derived or denormalized state during the delete:
deleteAll()  : Result
deleteBranch()  : array{success: bool, code: string}
Deletes one branch of the tariff (the same ownership guard as {@see saveBranch()}): `updateColumn()` full replace without the deleted branch.
find()  : T|null
findAll()  : T> : list>)
findBy()  : T|null
findRelatedIds()  : array<int, int>|null
Returns the ids of target entities that already belong to the record `$parentId` through the relation collection `$property` (for example `('assetRels', 'asset')`, `('fileRels', 'file')`). Reads straight from the database, not through the Api read path (no `UoW::clear()` in the middle of save hooks).
getAppContext()  : AppContext
getDefaultSkipFields()  : array<string|int, string>
Returns keys that the generic `service->save()` must not copy onto the managed entity.
getEntityClass()  : TEntity>
Returns the root Doctrine entity class managed by this manager.
getExternalMetaAllowlist()  : array<string|int, string>
Returns the meta keys allowed through the external HTTP path ({@see \App\Core\Traits\Api\Presenters\SaveTrait::actionSave()}).
getExternalOwnerData()  : array<string, mixed>
Returns `data` keys that fill the owner from the server when an external save creates a record.
getExternalRemoteIpData()  : array<string, mixed>
Returns `data` keys that fill the caller's IP from the server when an external save creates a record; sibling of {@see getExternalOwnerData()}.
getExternalUpdateColumnsAllowlist()  : array<string|int, string>
Returns the columns the external HTTP path may change through {@see \App\Core\Traits\Api\Presenters\SaveTrait::actionUpdateColumns()}.
getGraphDataKeys()  : array<string|int, string>
Returns the keys an external client may send nested in `data`.
getLanguageContext()  : LanguageContext|null
getPresenterContext()  : PresenterContext
getServiceClass()  : class-string
Returns the fully qualified service class name, the identity for the per-service rollout allowlist of the wire-payload query cache ({@see \App\Core\Cache\Config::isServiceEnabled()}).
getSettingContext()  : SettingContext
getSettings()  : array<int, array<string, mixed>>
getTotalCount()  : int|null
initializeAllContexts()  : void
registerEvent()  : Result
resolvePrice()  : ShippingPriceResult|null
Returns the currently valid shipping price of one tariff; see {@see resolvePrices()} for batches.
resolvePrices()  : array<int, ShippingPriceResult>
Resolves shipping prices for many tariffs with one SQL query, regardless of the tariff count.
save()  : Result
saveBranch()  : Result
Finds or creates and saves one branch of the tariff.
setAppContext()  : $this
setAssetFormatRegistry()  : static
setCacheTagInvalidator()  : static
setInternalCallContext()  : static
setLanguageContext()  : $this
setParamsConfig()  : static
setPresenterContext()  : $this
setSettingContext()  : $this
updateAllRelations()  : Result
updateColumn()  : Result
updateColumns()  : Result
updateRelations()  : Result
beforeSave()  : Result|null
Guards the history of price generations from changes.
beginRejectedUploads()  : array<int, array{name: string, reason: string}>
Starts a save ({@see save()}): the list of rejected items belongs to this save only; the outer one (a nested save of the same manager) is returned to the caller and restored after the save through {@see finishRejectedUploads()}.
bumpCacheTags()  : void
Bumps cache tags for the entity after commit: its class, the owned-cascade classes from metadata and the optional `additionalCacheTags()` of the manager.
bumpCacheTagsExplicit()  : void
Bumps the given classes explicitly (raw-DBAL paths with a cross-entity effect).
bumpCacheTagsForClass()  : void
Bumps cache tags by class name when there is no instance (bulk delete, `updateColumns()`, raw DBAL, tree operations).
classCacheTags()  : array<string|int, string>
Returns extra tags for a bump that has no entity, typically tree operations ({@see \App\Core\Traits\Api\Models\Managers\TreeTrait::treeTransaction()}) that rewrite `lft`/`rgt` on many rows.
finishRejectedUploads()  : void
Ends a save: whatever {@see recordRejectedUpload()} wrote during it is added to the data of a successful result as `saveInfo.rejectedUploads` (the Api presenter passes it on to the caller, the admin builds a warning from it). A rejected item does not fail the save; the accepted files stay.
getDeletedId()  : int|null
Returns the id `$entity` had before the delete, from the snapshot in `$meta` that {@see delete()} hands to every hook. Null for an entity the snapshot does not know (not loaded by this delete, or without a simple id).
getService()  : Service<string|int, TEntity>
Returns the service backing the manager traits.
readUploadedItem()  : string|null
Reads the content of an uploaded item (`{name, data}` base64 or `{name, path}` from the dropzone) through the single reader {@see UploadedItem}.
recordRejectedUpload()  : void
Records a new uploaded item that the save skipped ({@see UploadRejection} `REASON_*`).
branchDecimalOrNull()  : string|null
Converts mixed to a decimal string (6 decimal places, as `ShipperTariff::$latitude`) or null.
branchStrOrNull()  : string|null
Converts mixed to a trimmed string or null (empty is stored as `NULL`); branches input.
bumpDeleteCacheTags()  : void
Post-commit bump after a delete. With entities it goes through {@see \App\Core\Base\BaseManager::bumpCacheTags()}, which also collects `additionalCacheTags()` (Comment → CommentThread); without them it falls back to bumping the manager class itself, the original behavior.
captureDeletedIds()  : WeakMap<object, int>
Keys the ids by the loaded entity objects, not by the input ids: an input id that loaded nothing must not shift the pairing. A weak map, so the snapshot never keeps an entity alive.
columnsInvalidateCache()  : bool
dbString()  : string
Returns a scalar column of a DBAL row as a string; `NULL` becomes `''`.
decimal()  : string
Normalizes a decimal so that `1.5` and `1.500` give the same fingerprint (otherwise the guard would report a change where there is none). Empty input (a null column) stays empty, so `NULL` does not merge with `0.000`.
deleteBatch()  : Result
Bulk delete of a list of ids as one transaction. `Service::deleteAll()` flushes per entity; in autocommit the rows deleted before a database failure would stay deleted while the caller got either an escaped `EntityManagerClosed` or an "OK" with an error text. Here the service stops at the technical failure, this wrapper rolls the whole batch back and returns the failure Result with `deletedCount = 0` and `rolledBack = true`: nothing of the batch is durable and nothing is attempted over the closed EntityManager. A domain partial success (missing ids) keeps the existing contract and is committed.
entityId()  : int|null
Returns the association id without depending on a concrete leaf class (Api/Admin/Shared).
getMutableGenerationDates()  : array<int, string>
Returns the dates of the currently valid generations of both series (per table, the largest `date_from` not after now).
guardImmutablePaymentPrices()  : Result|null
Checks the payment matrix history: the same rules, its own generations (independent of shipping).
guardImmutablePrices()  : Result|null
Checks the weight price list history: DB rows with `date_from < $today` outside the editable dates (the currently valid generations, {@see getMutableGenerationDates}) must arrive in the graph unchanged.
guardOpenBands()  : Result|null
Requires every editable generation of the weight price list to have at most one open band (`weight_to = null`) per currency, and that band to start at the highest `weight_from`.
guardPickupMode()  : Result|null
Rejects a tariff that is both an external pickup (the carrier's own point picked in a widget) and a pickup at the shipper's branches: the two delivery modes exclude each other.
guardRowOwnership()  : Result|null
Requires every row with a filled `id` to belong to the edited tariff.
isAssetPathAllowed()  : bool
Checks only entities composing {@see AssetPathTrait}; the trait is the allowlist of "relative file path" columns, other `assetPath`-like fields are untouched.
loadEntitiesForCacheTags()  : array<int, object>
Loads the entities being deleted only to find out their `additionalCacheTags()`. Fail-soft: what cannot be loaded is simply missing and the bump falls back to the class; it must never stop the delete.
rejectImmutable()  : Result
Rejects a save and discards the half-built graph from the UnitOfWork.
rejectInvalid()  : Result
Rejects a save for an invalid tariff shape and discards the half-built graph from the UnitOfWork (same reason as {@see rejectImmutable()}).
rollbackBatch()  : void
saveWithHooks()  : Result
Runs the save itself: transaction, `beforeSave` / `afterSave` / `completedSave`, tree, cache.
usesAssetPathTrait()  : bool

Constants

DELETED_IDS_META

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

protected string DELETED_IDS_META = '__deletedIds'

Read it only through getDeletedId().

TABLE_PAYMENT_PRICES

private mixed TABLE_PAYMENT_PRICES = 'cms_mod_eshop_payment_method_prices'

Properties

$service

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

public Service<string|int, TEntity> $service

$assetFormatRegistry

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

protected AssetFormatRegistry|null $assetFormatRegistry = null

Set by a decorator (decorators.neon) like setParamsConfig(): more than ten managers process assets and each has its own constructor, so constructor injection would touch all of them.

$cacheTagInvalidator

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

protected CacheTagInvalidator|null $cacheTagInvalidator = null

Set by the decorator (decorators.neon) like setParamsConfig(). Nullable and fail-open: without wiring (or without Redis) a bump is a no-op.

$internalCallContext

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

protected InternalCallContext|null $internalCallContext = null

Only ApiBridge::internalCall() sets it, never the payload and not the RBAC guard, so the emergency apiRbac.internalMode: off cannot disable it. Set by a decorator like setAssetFormatRegistry(). Without it (direct manager call from cron or a test) the call counts as external.

$nonInvalidatingColumns

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

protected array<string|int, string> $nonInvalidatingColumns = ['views', 'viewsList', 'viewsDetail']

Covers all view counters across modules: views (Blog Article), viewsList (list impression of Advert/Message) and viewsDetail (detail view of Advert/Message, registerEvent() in the *DetailTraits). IMPORTANT: viewsDetail must stay in the list, otherwise every open of an advert/post detail would invalidate all lists of the class.

$paramsConfig

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

protected Config|null $paramsConfig = null

Write logic (asset directories) reads paths from here, not from getSettings() or the setting context, which may be filled by the client without server paths. The property cannot be named $config: it collides with the promoted $config in some managers.

$useTransactionForDelete

protected bool $useTransactionForDelete = true

$useTransactionForSave

protected bool $useTransactionForSave = true

$rejectedUploads

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

private array<int, array{name: string, reason: string}> $rejectedUploads = []

Methods

branchWire()

Builds the wire shape `{success, code, id}` of the `save-branch` response; the contract of the Api presenter stays unchanged ({@see saveBranch()}).

public static branchWire(Result $result) : array{success: bool, code: string, id: ?int}
Parameters
$result : Result
Return values
array{success: bool, code: string, id: ?int}

calculateTotalWeight()

Returns the total order weight, the sum of weight times quantity; see {@see ShippingPriceResolver::calculateTotalWeight()}.

public calculateTotalWeight(array<int, array{weight: string, quantity: int|string}> $items) : string
Parameters
$items : array<int, array{weight: string, quantity: int|string}>
Return values
string

delete()

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

public delete(int|array<string|int, mixed> $id[, array<string, mixed> $meta = [] ]) : Result
  • beforeDelete(array $entities, array $meta): ?Result runs before the delete (validation or capturing context while the rows exist). A failed Result means rollback and return. Its data flows into afterDelete under $meta['__beforeDelete'].
  • afterDelete(array $entities, Result $result, array $meta): ?Result runs after the delete, still in the transaction. It is only for recomputing derived state from the remaining rows (toped_until, member_until, county), idempotent and reversible. A failure rolls back the delete itself (atomicity). It is also the place for the mandatory delete of dependents through a foreign manager (comment, rating and message threads): an owner still managed in the unit of work references them, so they must go after its row, never before it in beforeDelete (collect their ids there). Additive or irreversible effects (credits, e-mails, invoices) do not belong here, only into completedDelete.
  • completedDelete(array $entities, Result $result, array $meta): void runs best effort after the commit, outside the transaction; an exception is only logged (the delete stays).
  • completedAssetCleanup(array $entities, Result $result, array $meta): void runs best effort after the commit and releases the Asset rows and files the deleted entity owned. The body is in AssetProcessingTrait; opt-in is ownedAssetIds(object $entity): array on the manager, without it the hook does not run.

IMPORTANT: the cleanup has its own name instead of completedDelete() because many Api managers define completedDelete() themselves and a class method overrides a trait method without a warning, so the cleanup would silently be missing in them.

IMPORTANT: a soft delete (deleted = 1) goes through save(), not here; assets must not be released there because the record can be restored.

$entities are the entities loaded before the delete (after the DELETE the row is gone, but the PHP object keeps the data, such as FKs for the recomputation).

IMPORTANT: the id is the exception. Doctrine nulls the id of a removed instance on flush(), so a hook must not rely on getId() once the delete ran (today only the read UoW::clear() in the service find() hands the preloaded entities over detached and keeps their id). Every hook therefore gets the ids captured before beforeDelete under the reserved key DELETED_IDS_META, keyed by the loaded entity object (an input id that loaded nothing has no entry); read it through getDeletedId(). The key is always set here, so a caller-supplied value never survives.

Without hooks it behaves exactly as before (no preloading, no transaction). NOTE: deleteAll() (bulk) and the tree deleteNode take another path and do not trigger these hooks.

Parameters
$id : int|array<string|int, mixed>
$meta : array<string, mixed> = []
Return values
Result

deleteAll()

public deleteAll([array<string|int, mixed> $filters = [] ]) : Result
Parameters
$filters : array<string|int, mixed> = []
Return values
Result

deleteBranch()

Deletes one branch of the tariff (the same ownership guard as {@see saveBranch()}): `updateColumn()` full replace without the deleted branch.

public deleteBranch(int $tariffId, int $branchId) : array{success: bool, code: string}
Parameters
$tariffId : int
$branchId : int
Return values
array{success: bool, code: string}

find()

public find(int $id[, string|array<string|int, mixed> $includes = [] ]) : T|null
Parameters
$id : int
$includes : string|array<string|int, mixed> = []
Return values
T|null

findAll()

public findAll([array<string|int, mixed>|null $includes = [] ][, array<string|int, mixed>|null $filters = [] ][, array<string|int, mixed>|null $orderBys = null ][, int|null $offset = null ][, int|null $limit = null ][, array<string|int, mixed>|null $columns = null ][, bool $computeTotalCount = false ]) : T> : list>)
Parameters
$includes : array<string|int, mixed>|null = []
$filters : array<string|int, mixed>|null = []
$orderBys : array<string|int, mixed>|null = null
$offset : int|null = null
$limit : int|null = null
$columns : array<string|int, mixed>|null = null
$computeTotalCount : bool = false
Return values
T> : list>) —

entities, or raw rows when $columns is set

findBy()

public findBy([array<string|int, mixed>|null $filters = [] ][, string|array<string|int, mixed> $includes = [] ]) : T|null
Parameters
$filters : array<string|int, mixed>|null = []
$includes : string|array<string|int, mixed> = []
Return values
T|null

findRelatedIds()

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

public findRelatedIds(int $parentId, string $property, string $targetAssociation) : array<int, int>|null
Parameters
$parentId : int
$property : string
$targetAssociation : string
Return values
array<int, int>|null —

null when it cannot be determined (collection mapping missing / database error)

getDefaultSkipFields()

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

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

The manager's own afterSave()/beforeSave() sync trait handles them through $meta, not through the object graph. Backed by an optional protected per-manager property. The write Api endpoint (SaveTrait::internalActionSave()) also uses this accessor to strip the same keys from $data before hydration, because defaultSkipFields alone does not protect hydration.

Return values
array<string|int, string>

getEntityClass()

Returns the root Doctrine entity class managed by this manager.

public getEntityClass() : TEntity>

The write Api endpoint (SaveTrait) takes it from here instead of the request, so a client cannot choose the instantiated PHP class.

Return values
TEntity>

getExternalMetaAllowlist()

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

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

The internal path (ApiBridge::internalCall() calling internalActionSave() directly, admin and front) is not limited by this allowlist and reads $meta unchanged. The default is an empty array, so external meta is dropped entirely; actionSave() is reachable through HTTP routing regardless of ApiBridge, hence the strip. Override per manager with the protected property $externalMetaAllowlist, analogous to self::getDefaultSkipFields().

Return values
array<string|int, string>

getExternalOwnerData()

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

public getExternalOwnerData(int $userId) : array<string, mixed>

The default [] means the domain has no owner or must not be created through external save (Order uses the dedicated checkout action, User registers another way). On INSERT there is nothing to own, so the owner cannot be verified, only determined: the owner field is #[ExternalReadonly] (the strip removes it from the payload) and SaveTrait::applyExternalOwner() then fills it from the JWT, so the client value never reaches hydration.

IMPORTANT: return the key that matches the column mapping, otherwise the owner is silently not written:

  • Watchdog/Comment/Rating/Message: scalar column, ['userId' => $userId];
  • Advert (Bazaar/Comcat): mapped column, ['insertUserId' => $userId];
  • Bazaar Response/AdvertFollower: the scalar userId has an #[ORM\AttributeOverride] with insertable: false, updatable: false in the Api leaf and the column belongs to the association $user, so ['user' => ['id' => $userId]]; Comcat Response has no $user association, so there it is ['userId' => $userId];
  • Complaint: the owner is the association $user, ['user' => ['id' => $userId]].

['id' => X] is a reference that hydrateForPersist() looks up in the DB (OrmEntityHydrator::isReference()). Called only on the external path and only on INSERT; on UPDATE it would make whoever saves a foreign record its owner.

Parameters
$userId : int

identity from the JWT (never from the request)

Return values
array<string, mixed>

getExternalRemoteIpData()

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

public getExternalRemoteIpData(string $ip) : array<string, mixed>

The IP field is #[ExternalReadonly], so the external strip removes it and the client cannot forge it. Without filling, an external insert would have no IP and the "anonymous by IP" deduplication and per-IP manager limits would silently stop working. SaveTrait::applyExternalRemoteIp() fills it from IRequest::getRemoteAddress(), never from the request. The default [] means the entity carries no IP; overrides return the entity field name (['insertIp' => $ip]).

Parameters
$ip : string
Return values
array<string, mixed>

getExternalUpdateColumnsAllowlist()

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

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

updateColumn on a to-many relation is DELETE-all plus INSERT, so without this filter an external POST with values={userRoles: [...]} would bypass the strip/guard of the save path (privilege escalation). The internal path (ApiBridge::internalCall() calling internalActionUpdateColumns() directly) is not limited. The default is an empty array, so external updateColumns is rejected entirely. Override with the protected property $externalUpdateColumnsAllowlist.

Return values
array<string|int, string>

getGraphDataKeys()

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

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

Before hydration the write Api endpoint (SaveTrait::internalActionSave()) moves them from $data to $meta, where the manager's own afterSave()/beforeSave() sync trait reads them (the same mechanism as internal meta). When the client also sends the same key explicitly in meta, meta wins (compatibility with admin, e.g. the categoryRels collision on Advert). Backed by an optional protected per-manager property, like self::getDefaultSkipFields().

IMPORTANT: promoting a key here does not make its content safe to write as received. When the key carries a sensitive field that the server otherwise dictates (typically a payment or approval flag), the manager must overwrite or verify it server-side on the external path in beforeSave()/afterSave() before its sync trait reads it; otherwise the client sets it itself (privilege escalation). The external path is recognized by $meta['__external'] === true, which only SaveTrait::actionSave() sets (never internalActionSave() alone), so internal calls never get the marker. Example: Bazaar Advert.categoryRels is persisted through the object graph (owned collection outside $graphDataKeys); a client could mark paid itself and get a paid advert without payment, so AdvertManager::beforeSave() overwrites it through CategoryRelsPaidSanitizationTrait::sanitizeExternalCategoryRelsPaid() before flush.

Return values
array<string|int, string>

getServiceClass()

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

public getServiceClass() : class-string

The cache is controlled at the Api presenter boundary through this identity.

Return values
class-string

getSettings()

public getSettings() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

getTotalCount()

public getTotalCount() : int|null
Return values
int|null

registerEvent()

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

entity used to translate the property into a column in the expression

$property : string
Return values
Result

resolvePrice()

Returns the currently valid shipping price of one tariff; see {@see resolvePrices()} for batches.

public resolvePrice(int $tariffId, int $currencyId, string $totalWeight[, string|null $cartTotal = null ][, DateTimeInterface|null $at = null ]) : ShippingPriceResult|null
Parameters
$tariffId : int
$currencyId : int
$totalWeight : string
$cartTotal : string|null = null
$at : DateTimeInterface|null = null
Return values
ShippingPriceResult|null

resolvePrices()

Resolves shipping prices for many tariffs with one SQL query, regardless of the tariff count.

public resolvePrices(array<string|int, int> $tariffIds, int $currencyId, string $totalWeight[, string|null $cartTotal = null ][, DateTimeInterface|null $at = null ]) : array<int, ShippingPriceResult>
Parameters
$tariffIds : array<string|int, int>
$currencyId : int
$totalWeight : string
$cartTotal : string|null = null
$at : DateTimeInterface|null = null
Return values
array<int, ShippingPriceResult> —

keyed by tariffId

save()

public save(TEntity $entity[, array<string, mixed> $meta = [] ][, array<int, string> $skipFields = [] ]) : Result
Parameters
$entity : TEntity
$meta : array<string, mixed> = []
$skipFields : array<int, string> = []
Return values
Result

saveBranch()

Finds or creates and saves one branch of the tariff.

public saveBranch(int $tariffId, int|null $branchId, array<string, mixed> $data) : Result

Unlike prices / paymentPrices (append-only time series, immutable guard above), branches have no history: plain CRUD. Like ProductSetManager::savePriceSnapshot(), updateColumn() is a full-collection replace through Mapper::updateColumns() (delete-all + insert), outside the generic save() / beforeSave(), so the immutable guard above never runs (it checks only prices / paymentPrices).

insertRelations() (mapper layer) inserts the id column from the entity 1:1, so an unchanged branch gets the same surrogate id back after delete-all + insert, and a new one (id === null) a fresh one (auto-assigned). The returned id can therefore be null even on success (insertRelations() does not write lastInsertId back to the object); the caller (Admin BranchTrait) always reloads the tariff (branches include) after success to get a fresh list with real ids.

Ownership guard: $branchId must belong to $tariffId. $tariff->getBranches() holds only the branches of the loaded tariff (includes: ['branches']), so a foreign or nonexistent id simply does not appear in it.

isManaged is never taken from $data: a new and an edited record are always true (the admin form does not send it; false is reserved for a future bulk sync of an external carrier network, e.g. Packeta pickup boxes).

IMPORTANT: returns a Result, which is always truthy: callers must check ->isSuccess(). Success carries data = ['id' => ?int]; a failure carries a ResultCode (ITEM_NOT_FOUND / VALIDATION_FAILED). The wire shape {success, code, id} (Admin BranchTrait, external clients) is built by branchWire() in the Api presenter.

Parameters
$tariffId : int
$branchId : int|null
$data : array<string, mixed>
Return values
Result

setParamsConfig()

public setParamsConfig(Config $paramsConfig) : static
Parameters
$paramsConfig : Config
Return values
static

updateAllRelations()

public updateAllRelations(int|array<string|int, mixed> $entityId, string $property, array<string, mixed> $values) : Result
Parameters
$entityId : int|array<string|int, mixed>

id, or a list of ids / composite-id arrays

$property : string
$values : array<string, mixed>

relation property name => value set on every row

Return values
Result

updateColumn()

public updateColumn(int|array<string|int, mixed> $entityId, string $property, mixed $value) : Result
Parameters
$entityId : int|array<string|int, mixed>

id, or a list of ids / composite-id arrays

$property : string
$value : mixed
Return values
Result

updateColumns()

public updateColumns(int|array<string|int, mixed> $entityId, array<string, mixed> $values) : Result
Parameters
$entityId : int|array<string|int, mixed>

id, or a list of ids / composite-id arrays

$values : array<string, mixed>

property name => new value

Return values
Result

updateRelations()

public updateRelations(int|array<string|int, mixed> $entityId, string $property, array<string|int, object> $relationEntities) : Result
Parameters
$entityId : int|array<string|int, mixed>

id, or a list of ids / composite-id arrays

$property : string
$relationEntities : array<string|int, object>

relation entities with updated values

Return values
Result

beforeSave()

Guards the history of price generations from changes.

protected beforeSave(bool $isInsert, ShipperTariff &$entity[, array<string, mixed> &$meta = [] ]) : Result|null

Both series of a tariff (ShipperTariffPrice = weight band price list, PaymentMethodPrice = payment surcharge matrix) are append-only time series. A generation is the set of rows with the same date_from. Editable are generations from today's midnight on and the currently valid generation of each series (the largest date_from <= NOW()), which is live configuration. Superseded history stays locked: generations already replaced by a newer one priced past periods and must stay bit-for-bit identical.

The editable dates are the union over both series: editing the valid price list may also write the matrix at its own date (and vice versa), which is how a migrated split series is aligned to one date by the first save. NOTE: with diverged series, rows of one series at the date of the other series are editable even if superseded on their own series; the form shows that card as fully editable (its keep/reuse split uses the same union), so the guard and the UI agree. The admin form cannot recreate a diverged state (save writes both series under one date); only direct API calls can.

IMPORTANT: this must live here, not only in the form. The form renders the history disabled and posts it back unchanged, but both collections are owned (orphanRemoval: true): anything not sent in the object graph is silently deleted. A missing includes, a hand-built API request or a future non-admin caller would wipe the history without a message. A disabled input is UX, not a check.

The comparison runs against the DB, not the in-memory state: for every DB row with date_from before today's midnight outside the editable dates, a row with the same surrogate id and an identical value fingerprint must be present in the posted graph. A missing row is an attempted delete, a different fingerprint an attempted overwrite, a new row (id === null) with a historical date_from outside the editable dates an attempt to insert a record into the past. All end in Result::failure.

Before the history guards the tariff shape is checked the same way as in the admin form: guardPickupMode() and guardOpenBands() (also on insert).

Parameters
$isInsert : bool
$entity : ShipperTariff
$meta : array<string, mixed> = []
Return values
Result|null

beginRejectedUploads()

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

protected beginRejectedUploads() : array<int, array{name: string, reason: string}>
Return values
array<int, array{name: string, reason: string}> —

the outer save's list

bumpCacheTags()

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

protected bumpCacheTags(object $entity) : void

Fail-open (the invalidator swallows exceptions). Called from the manager Save/Delete/Tree traits after the commit.

Parameters
$entity : object

bumpCacheTagsExplicit()

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

protected bumpCacheTagsExplicit(array<string|int, string> $classes) : void
Parameters
$classes : array<string|int, string>

bumpCacheTagsForClass()

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

protected bumpCacheTagsForClass(class-string $rootClass[, array<string|int, string> $extraTags = [] ]) : void

Bumps the root class and its owned-cascade classes.

Parameters
$rootClass : class-string
$extraTags : array<string|int, string> = []

classCacheTags()

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

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

IMPORTANT: additionalCacheTags(object) receives an entity, so a class-level bump cannot use it; without this hook a delete would lose the cross-entity tag (Comment to CommentThread). A manager whose cross-entity tag does not depend on a particular entity returns it here.

NOTE: unlike additionalCacheTags(), this hook is declared (with an empty default) instead of being an opt-in through method_exists(); method_exists() is always true in a manager that has the method, which phpstan reports as alreadyNarrowedType.

Return values
array<string|int, string>

finishRejectedUploads()

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

protected finishRejectedUploads(Result|null $result, array<int, array{name: string, reason: string}> $outer) : void
Parameters
$result : Result|null
$outer : array<int, array{name: string, reason: string}>

list from beginRejectedUploads()

getDeletedId()

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

protected getDeletedId(array<string, mixed> $meta, object $entity) : int|null
Parameters
$meta : array<string, mixed>
$entity : object
Return values
int|null

getService()

Returns the service backing the manager traits.

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

readUploadedItem()

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

protected readUploadedItem(array<string|int, mixed> $item[, bool $strictBase64 = true ][, int|null $maxBytes = null ]) : string|null

Call it right before processing and release the result before the next item, so that files never meet in memory. A path is accepted only during an internal bridge call ($internalCallContext) and only inside the dropzone root. A rejected path is logged to the auth channel and null is returned; callers treat it like unreadable data (skip the item or refuse the save).

Parameters
$item : array<string|int, mixed>
$strictBase64 : bool = true

false for callers that decode loosely (base64_decode($x))

$maxBytes : int|null = null

size limit; for path it is checked before reading

Return values
string|null

recordRejectedUpload()

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

protected recordRejectedUpload(mixed $name, string $reason) : void

Called by the places that drop an item (processOrderedAssets(), advert attachments, product set gallery).

Parameters
$name : mixed
$reason : string

branchDecimalOrNull()

Converts mixed to a decimal string (6 decimal places, as `ShipperTariff::$latitude`) or null.

private branchDecimalOrNull(mixed $value) : string|null
Parameters
$value : mixed
Return values
string|null

branchStrOrNull()

Converts mixed to a trimmed string or null (empty is stored as `NULL`); branches input.

private branchStrOrNull(mixed $value) : string|null
Parameters
$value : mixed
Return values
string|null

bumpDeleteCacheTags()

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

private bumpDeleteCacheTags(array<int, object> $entities) : void
Parameters
$entities : array<int, object>

captureDeletedIds()

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

private captureDeletedIds(array<int, object> $entities) : WeakMap<object, int>
Parameters
$entities : array<int, object>
Return values
WeakMap<object, int>

columnsInvalidateCache()

private columnsInvalidateCache(array<int, string> $columns) : bool
Parameters
$columns : array<int, string>
Return values
bool

dbString()

Returns a scalar column of a DBAL row as a string; `NULL` becomes `''`.

private dbString(mixed $row, string $column) : string
Parameters
$row : mixed
$column : string
Return values
string

decimal()

Normalizes a decimal so that `1.5` and `1.500` give the same fingerprint (otherwise the guard would report a change where there is none). Empty input (a null column) stays empty, so `NULL` does not merge with `0.000`.

private decimal(string $value) : string
Parameters
$value : string
Return values
string

deleteBatch()

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

private deleteBatch(array<int, int|string|array<string|int, mixed>> $ids) : Result

Transaction ownership: the wrapper only opens its own level; inside a caller's transaction a rollback here marks the caller's transaction rollback-only, so its final commit rolls the whole scope back (TransactionManager counter contract, the same as the hooked delete() path).

Parameters
$ids : array<int, int|string|array<string|int, mixed>>
Return values
Result

entityId()

Returns the association id without depending on a concrete leaf class (Api/Admin/Shared).

private entityId(mixed $entity) : int|null
Parameters
$entity : mixed
Return values
int|null

getMutableGenerationDates()

Returns the dates of the currently valid generations of both series (per table, the largest `date_from` not after now).

private getMutableGenerationDates(int $tariffId) : array<int, string>

Read from the DB before the hydrated write (beforeSave()), so it reflects the state before this transaction.

Parameters
$tariffId : int
Return values
array<int, string>

guardImmutablePaymentPrices()

Checks the payment matrix history: the same rules, its own generations (independent of shipping).

private guardImmutablePaymentPrices(ShipperTariff $entity, int $tariffId, string $today, array<int, string> $mutableDates) : Result|null
Parameters
$entity : ShipperTariff
$tariffId : int
$today : string
$mutableDates : array<int, string>
Return values
Result|null

guardImmutablePrices()

Checks the weight price list history: DB rows with `date_from < $today` outside the editable dates (the currently valid generations, {@see getMutableGenerationDates}) must arrive in the graph unchanged.

private guardImmutablePrices(ShipperTariff $entity, int $tariffId, string $today, array<int, string> $mutableDates) : Result|null
Parameters
$entity : ShipperTariff
$tariffId : int
$today : string
$mutableDates : array<int, string>
Return values
Result|null

guardOpenBands()

Requires every editable generation of the weight price list to have at most one open band (`weight_to = null`) per currency, and that band to start at the highest `weight_from`.

private guardOpenBands(ShipperTariff $entity, string $today, array<int, string>|null $mutableDates) : Result|null

ShippingPriceResolver picks the newest generation and the cheapest matching row, so a second open band, or an open band below a closed one, would price heavy parcels by the wrong row. The admin form validates the same rule per generation; this guard covers direct Api calls and imports.

Locked history (before today's midnight and outside $mutableDates) is skipped: the immutable guard keeps it bit-for-bit, so an old violation must not block every later save. $mutableDates === null (insert) checks all generations.

Parameters
$entity : ShipperTariff
$today : string
$mutableDates : array<int, string>|null
Return values
Result|null

guardPickupMode()

Rejects a tariff that is both an external pickup (the carrier's own point picked in a widget) and a pickup at the shipper's branches: the two delivery modes exclude each other.

private guardPickupMode(ShipperTariff $entity) : Result|null

The admin form reports it as a field error; this guard covers direct Api calls and imports.

Parameters
$entity : ShipperTariff
Return values
Result|null

guardRowOwnership()

Requires every row with a filled `id` to belong to the edited tariff.

private guardRowOwnership(ShipperTariff $entity, int $tariffId) : Result|null

The immutable guards check only the history of this tariff: a posted row with a foreign id and a future date would pass unnoticed and the hydrator would overwrite its FK on flush, "stealing" a row of another tariff (it vanishes from there and is overwritten by the graph data). The admin form never builds such a graph; the threat is direct API calls, which is why the guard exists.

Parameters
$entity : ShipperTariff
$tariffId : int
Return values
Result|null

isAssetPathAllowed()

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

private isAssetPathAllowed(BaseEntity $entity) : bool
Parameters
$entity : BaseEntity
Return values
bool

loadEntitiesForCacheTags()

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

private loadEntitiesForCacheTags(int|array<string|int, mixed> $id) : array<int, object>
Parameters
$id : int|array<string|int, mixed>
Return values
array<int, object>

rejectImmutable()

Rejects a save and discards the half-built graph from the UnitOfWork.

private rejectImmutable(string $message) : Result

IMPORTANT: hydration into managed entities happens before beforeSave(). A rejected save rolls back the transaction, but the overwritten prices / paymentPrices collection with scheduled orphanRemoval stays in the UoW; any later flush in the same request would commit it and delete the history although the caller got an error. Same as reject() in ProductSetManager.

Parameters
$message : string
Return values
Result

rejectInvalid()

Rejects a save for an invalid tariff shape and discards the half-built graph from the UnitOfWork (same reason as {@see rejectImmutable()}).

private rejectInvalid(string $message) : Result
Parameters
$message : string
Return values
Result

saveWithHooks()

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

private saveWithHooks(TEntity $entity, array<string, mixed> $meta, array<int, string> $skipFields) : Result
Parameters
$entity : TEntity
$meta : array<string, mixed>
$skipFields : array<int, string>
Return values
Result

usesAssetPathTrait()

private static usesAssetPathTrait(string $class) : bool
Parameters
$class : string
Return values
bool
On this page

Search results