CoolCMS API

WarehouseOrderSwapTrait

Api operation "swap the draw priority of two warehouses" in a single DB transaction.

It reads the current order of both warehouses, verifies them, writes both values and commits or rolls back, so the admin gets one Result. Two separate writes with a compensation would not survive a failing compensation or two concurrent moves.

The trait interface is split into three seams so that the contract ("a failure in the middle writes nothing") can be tested without a DB, DI or network (WarehouseOrderSwapApiOperationTest):

  • fetchWarehouseOrders() reads the current values inside the transaction,
  • storeWarehouseOrder() performs one write (may throw),
  • inWarehouseOrderTransaction() is the real transaction (implemented by the manager).

The $expected* check is an optimistic lock against races: the admin sends the order values it saw in the list; if they changed meanwhile, the operation writes nothing and returns INVALID_STATE. Without it two concurrent moves would end with a duplicate order.

Table of Contents

Methods

swapOrder()  : Result
Swaps `order` between two warehouses in one transaction.
fetchWarehouseOrders()  : array<int, int>
Returns the current `order` of the given warehouses (missing ids do not appear in the result).
inWarehouseOrderTransaction()  : Result
Wraps the operation in a transaction. The implementation must (a) roll back both a failed `Result` and an exception, and (b) not open its own transaction when one is already running.
storeWarehouseOrder()  : void
Writes one `order`; a failure is reported by an exception, which the transaction turns into a rollback.

Methods

swapOrder()

Swaps `order` between two warehouses in one transaction.

public swapOrder(int $firstId, int $secondId[, int|null $expectedFirstOrder = null ][, int|null $expectedSecondOrder = null ]) : Result
Parameters
$firstId : int
$secondId : int
$expectedFirstOrder : int|null = null

order the caller saw for $firstId (null skips the check)

$expectedSecondOrder : int|null = null

order the caller saw for $secondId (null skips the check)

Return values
Result

fetchWarehouseOrders()

Returns the current `order` of the given warehouses (missing ids do not appear in the result).

protected abstract fetchWarehouseOrders(array<int, int> $warehouseIds) : array<int, int>
Parameters
$warehouseIds : array<int, int>
Return values
array<int, int> —

id => order

inWarehouseOrderTransaction()

Wraps the operation in a transaction. The implementation must (a) roll back both a failed `Result` and an exception, and (b) not open its own transaction when one is already running.

protected abstract inWarehouseOrderTransaction(callable(): Result $work) : Result
Parameters
$work : callable(): Result
Return values
Result

storeWarehouseOrder()

Writes one `order`; a failure is reported by an exception, which the transaction turns into a rollback.

protected abstract storeWarehouseOrder(int $warehouseId, int $order) : void
Parameters
$warehouseId : int
$order : int
On this page

Search results