CoolCMS API

OrderManager extends Manager

in package

• Application

uses BlacklistGuardTrait, OrderBuildTrait, OrderCronTrait

Order manager: owns the order model and its calculation.

Tags

phpstan-import-type

TOrderGraph from OrderCalculator

extends

Table of Contents

Constants

DEFAULT_UNPAID_CANCEL_AFTER_DAYS  : int = 30

Fallback of {@see UNPAID_CANCEL_SETTING_KEY} when the row is missing or not a positive number (user decision 18. 10.: 30 days).

UNPAID_CANCEL_SETTING_KEY  : string = 'order.unpaid.cancelAfterDays'

Setting (module {@see UNPAID_CANCEL_SETTING_MODULE}, e-shop) with the days after creation an order may stay awaiting payment before the cron cancels it. Edited in Eshop › Settings › Orders.

DELETED_IDS_META  : string = '__deletedIds'

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

BUILD_STOCK_SOURCE_MODULE  : int = 4

`cms_system_modules` id of the eshop, the reservation source in the Store journal.

BUILD_STOCK_SOURCE_TYPE  : string = 'order'

EXPIRE_DEFAULT_BATCH  : int = 50

EXPIRE_QUEUE  : string = 'eshop.order.expire'

EXPIRED_STATUS_KEY  : string = 'EXPIRED'

INVOICE_DEFAULT_BATCH  : int = 20

INVOICE_QUEUE  : string = 'eshop.order.invoice'

ORDERS_TABLE  : string = 'cms_mod_eshop_orders'

STATUSES_TABLE  : string = 'cms_mod_eshop_order_statuses'

UNPAID_CANCEL_DEFAULT_BATCH  : int = 50

UNPAID_CANCEL_QUEUE  : string = 'eshop.order.cancel-unpaid'

UNPAID_CANCEL_SETTING_MODULE  : int = 4

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

$blacklistManager  : BlacklistManager|null

$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 written by `OrderStockManager` through {@see updateColumns()}.

$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

$calculator  : OrderCalculator

$cronFailureManager  : CronFailureManager

$currencyManager  : CurrencyManager

$customerManager  : OrderCustomerManager

$em  : EntityManagerInterface

$invoiceGenerator  : OrderInvoiceGenerator

$languageManager  : LanguageManager

$localizationManager  : LocalizationManager

$numberGenerator  : OrderNumberGenerator

$orderPayloadHelper  : OrderPayloadHelper

$orderStatusManager  : OrderStatusManager

$orderTaxManager  : OrderTaxManager

$orderTransitionManager  : OrderTransitionManager

$paymentRegionManager  : PaymentRegionManager

$paymentRegionService  : OrderPaymentRegionService

$pickupPointApplier  : OrderPickupPointApplier

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

$snapshotBuilder  : OrderSnapshotBuilder

$stockItemManager  : StockItemManager

$stockManager  : OrderStockManager

$stockReservationManager  : StockReservationManager

$unitOfWorkReset  : UnitOfWorkReset

$userGroupManager  : UserGroupManager

$userTypeManager  : UserTypeManager

$voucherManager  : VoucherManager

Methods

__construct()  : mixed

cancelUnpaid()  : array{processed: int, cancelled: int, skipped: int, errors: list}

Cancels orders that stayed awaiting payment (card/gateway or bank transfer) for {@see unpaidCancelAfterDays()} days since creation (cron `/cron/eshop/order/cancel-unpaid`).

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

expireUnpaid()  : array{processed: int, expired: int, skipped: int, errors: list}

Expires unpaid orders periodically (cron `/cron/eshop/order/expire`).

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

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

Builds, recalculates and optionally saves an order from the trusted rows of the admin edit form.

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

getItemPrefillData()  : array{success: bool, message?: string, errorCode?: string, code?: ?string, name?: string, unit?: ?string, vat?: string, price?: string}

Returns prefill data for the order item picker (`api/eshop/order/item-prefill`).

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

isOwnedBy()  : bool

Returns whether order `$orderId` belongs to user `$userId`; the single definition of order ownership.

ownershipMatches()  : bool

Pure, stateless ownership match, testable without a DB.

registerEvent()  : Result

runInvoiceCatchup()  : array{processed: int, generated: int, permanent: int, skipped: int, errors: list}

Issues invoices for orders catch-up style (cron `/cron/eshop/order/invoice`).

save()  : Result

setAppContext()  : $this

setAssetFormatRegistry()  : static

setCacheTagInvalidator()  : static

setInternalCallContext()  : static

setLanguageContext()  : $this

setParamsConfig()  : static

setPresenterContext()  : $this

setSettingContext()  : $this

unpaidCancelAfterDays()  : int

Days an order may stay awaiting payment before {@see cancelUnpaid()} cancels it: the setting {@see UNPAID_CANCEL_SETTING_KEY}, else {@see DEFAULT_UNPAID_CANCEL_AFTER_DAYS}.

updateAllRelations()  : Result

updateColumn()  : Result

updateColumns()  : Result

updateRelations()  : Result

updateStatusForPayment()  : Result

Fills the payment region of orders paired with a payment; called by the gateway callback {@see EshopPaymentHook::handlePayment()} (`callback_key = ESHOP_ORDER`).

beforeDelete()  : Result|null

Snapshots what `completedDelete()` needs per order while the rows exist: the voucher FKs (before the `ON DELETE CASCADE` of `cms_mod_eshop_order_voucher_rel`), `is_cancelled` and `stock_state`. It runs post-commit, where a lazy load would find nothing and the removed entity has no id.

beforeSave()  : Result|null

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.

completedDelete()  : void

Releases stock and decrements vouchers per deleted order, only from the values captured before the delete: the id from the `DeleteTrait` snapshot (Doctrine nulls the id of the removed instance) and the `beforeDelete()` state. The Store `SourceRef` survives the order delete (Store has no FK to the e-shop), so the release by id still works.

completedSave()  : void

Post-commit stock handling (best-effort, see the class docblock). `$meta['skipReserve']` skips reserve and rereserve completely; `$meta['allowPartial']` (bool) overrides the default resolution in {@see OrderStockManager}.

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

applyStockResult()  : void

A stock operation failure must never fail an already committed save or delete; it only logs a warning and appends it to `Result::data['stockWarnings']` (the order is valid unreserved, `stock_state` says so).

blacklistRefusal()  : Result|null

buildFailureArray()  : array{success: false, errorCode: string, message: string}

buildNumOrZero()  : numeric-string

Converts a DBAL/bcmath scalar (mixed) to a numeric-string, guarded (like `OrderCalculator::norm()`).

buildRef()  : T

Returns a managed reference without a DB query (like {@see \App\UI\Api\Eshop\Models\Services\OrderSnapshotBuilder::ref()}).

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.

cancelDueUnpaidOrderIds()  : array<int, int>

Returns orders awaiting payment created before the cutoff, oldest first (read only; the fresh load is done by `apply()`). Parked orders arrive as an id list.

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.

checkStrictStockGate()  : array{success: false, errorCode: string, message: string}|null

Strict stock gate: called on `persist=true` before `OrderManager::save()`, only when `!$allowPartial`.

columnsInvalidateCache()  : bool

currentUnitsSnapshot()  : array<int, int>

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.

dueInvoiceOrders()  : array<int, TOrderGraph>

Returns orders of the given status that have no handled invoice for it yet (`invoiced_status` is null or differs from the status), like {@see \App\UI\Api\Invoicer\Models\Managers\InvoiceManager} `duePayments()`.

expireDueOrderIds()  : array<int, int>

Returns unpaid orders past `reservation_expires_at` whose current status allows cancelling (`allow_cancelling=1`), via raw SQL (read only; the fresh load is done by `apply()`).

fetchUnitsSnapshot()  : array<int, int>

fetchVoucherIdsBefore()  : array<int, int>

Returns ids of live vouchers applied to the order according to the DB, not the in-memory entity. The update branch of `beforeSave()` diffs against it, and `beforeDelete()` needs it before the cascade delete of `cms_mod_eshop_order_voucher_rel`.

findExpiredStatus()  : TOrderStatusGraph|null

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.

loadPreviousCustomerLink()  : array{0: ?int, 1: ?string, 2: ?int}

Reads the previous customer link state before the Doctrine entity is loaded.

logInvoiceWarning()  : void

Fail-soft log plus `Result::data['invoiceWarnings']` (same as `stockWarnings`).

orderIdsForPayment()  : array<int, int>

Returns ids of orders paired with the payment. The authoritative source is the join table `cms_mod_eshop_order_payments`, not the denormalized `Order.payment` (only the last paired payment); one payment may theoretically cover several orders.

orderVoucherIds()  : array<int, int>

Returns unique ids of live vouchers (the FK really exists) in the in-memory collection `$entity->getVouchers()`. A snapshot without a live voucher is skipped because there is no counter to adjust.

ownActiveReservations()  : array<int, string>

Returns the sum of this order's active (`status=1`) reservations per stock item.

regenerateOrderDocument()  : void

Refreshes the order document, see {@see OrderInvoiceGenerator::regenerateOrderDocument()}.

resolveAllowPartial()  : bool

Resolves `allowPartial`: the payload override (bool, only when explicitly `true`/`false`), otherwise `4/order.partial.adminAllowed`.

resolveBuyerType()  : int

Computes `buyerType` (0 = natural person, 1 = company) server-side; it is not a form field.

resolveCustomerLink()  : array{0: ?int, 1: ?int}

Resolves the card-file customer and contact for the order being built.

resolveDefaultPaymentRegionId()  : int

Resolves the VAT payment region for a new snapshot: setting `4/invoicer.paymentRegionId`, then `7/invoice.default.paymentRegionId` (no prefix), then the localization default ({@see PaymentRegionManager::getDefaultPaymentRegionId()}).

rollbackBatch()  : void

saveWithHooks()  : Result

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

statusesRequiringInvoice()  : array<int, OrderStatus>

Returns active statuses with `createInvoice=1` (the batch is a budget across them, like {@see \App\UI\Api\Invoicer\Models\Managers\InvoiceManager} `rulesByStatus()`).

touchOrderCollectionsForInvoice()  : void

Forces hydration of all order collections that {@see OrderInvoiceGenerator::appendLines()} reads, before any `find()`/`findAll()` inside the generator.

usesAssetPathTrait()  : bool