CoolCMS API

WorkListManager extends Manager

in package

• Application

uses SourceLockTransactionTrait

Manages work lists (jobs) and invoices selected work sheets of a job as one invoice.

Tags

extends

Table of Contents

Constants

CUSTOMER_MISSING_MESSAGE  : string = 'Zakázka nemá klienta — vyfakturovat ji nelze....

Message of the gate "no invoicing without a customer"; shared with {@see CompanyInvoiceGenerator}.

WORK_LISTS_TABLE  : string = 'cms_mod_company_work_lists'

Own module table; raw DBAL is allowed only on it.

DELETED_IDS_META  : string = '__deletedIds'

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

FOLLOW_UP_NAME_FORMAT  : string = 'Pracovní list %d'

Default name of the follow-up sheet; `%d` is the sequence number within the job.

INVOICE_ITEMS_TABLE  : string = 'cms_mod_invoicer_invoice_items'

Invoice lines; read-only probe of the item count during recovery (no writes across the module boundary).

INVOICES_TABLE  : string = 'cms_mod_invoicer_invoices'

IMPORTANT: foreign table (Invoicer), used only as an existence probe of an invoice in {@see invoiceRowExists()}: a read-only `select invoice_id`, never a write, never reading invoice content (that belongs to `InvoiceManager::find()`). Doctrine cannot answer this: after a rollback inside `InvoiceManager::save()` the identity map still holds the invoice entity, so `find()` would report a nonexistent row as existing, and the answer decides between a safe revert and a second invoice.

LOCK_MAX_ATTEMPTS  : int = 3

LOCK_SCALE  : int = 3

LOCK_TIMEOUT  : int = 10

Seconds to wait for the job advisory lock. Longer than for reservations (5 s): the PDF is generated under the lock, so a concurrent click on issuing an invoice should wait, not fail.

NAME_MAX_LENGTH  : int = 255

`name` is `varchar(255)`; a longer name would be truncated by MySQL.

WORK_SHEETS_TABLE  : string = 'cms_mod_company_work_sheets'

Same table as {@see WorkSheetManager::WORK_SHEETS_TABLE}; invoicing writes into the sheets.

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

$defaultSkipFields  : array<string|int, string>

$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

$companyManager  : CompanyManager

$em  : EntityManagerInterface

$invoiceGenerator  : CompanyInvoiceGenerator

$invoiceManager  : InvoiceManager

$invoicerCustomerManager  : CustomerManager

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

$workItemManagerFactory  : WorkItemManagerFactory

$workSheetManager  : WorkSheetManager

Methods

__construct()  : mixed

archive()  : Result

Archives the job: `open -> archived`. The end of the job, not an invoicing action.

customerMissingRefusal()  : Result|null

Gate "a job without a customer is not invoiced": saving does not require a customer, invoicing does. Pure function over the job row (`fetchListRow()`), testable without a DB. `null` = pass.

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

Read-only guard for `deleteAll()`, which bypasses hooks yet is reachable over HTTP.

deleteRefusal()  : Result|null

Returns the reason to refuse deleting a non-archived job based on its non-deleted sheets (pure function, no DB). Invoiced sheets take precedence: deleting sheets does not resolve them, the only way is archiving. `null` = deletion allowed.

find()  : T|null

findAll()  : T> : list>)

findBy()  : T|null

findForUser()  : WorkList>, totalCount: int, itemCounts: array}

Returns the logged-in client's jobs (open and archived), newest first, with work item counts.

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

invoiceSheets()  : Result

Issues one invoice from the selected work sheets of one job.

isOwnedBy()  : bool

Returns whether the job belongs to the user (a boolean, not the entity).

lockName()  : string

Single source of truth for the name of the job advisory lock.

previewInvoiceSheets()  : Result

Summarizes the selected sheets before invoicing, exactly what the modal shows: items, hours, what goes on the invoice and how many items are skipped.

registerEvent()  : Result

save()  : Result

setAppContext()  : $this

setAssetFormatRegistry()  : static

setCacheTagInvalidator()  : static

setInternalCallContext()  : static

setLanguageContext()  : $this

setParamsConfig()  : static

setPresenterContext()  : $this

setSettingContext()  : $this

unarchive()  : Result

Returns the job from the archive: `archived -> open`.

updateAllRelations()  : Result

updateColumn()  : Result

updateColumns()  : Result

Read-only guard for `updateColumns()` as well. Without it the guard in `beforeSave()` would be decoration: `updateColumns` skips save hooks, and external Api `updateColumns` calls and inline changes from the admin grid come this way (same approach as {@see CompanyManager::updateColumns()}, which enforces exclusivity of `presented`).

updateRelations()  : Result

acquireSourceLock()  : bool

Calls `GET_LOCK(name, timeout)` and returns true only on a definite 1 (0 = timed out or busy, null = error). `$timeout` is in seconds; 0 is non-blocking (try-lock, used by the expirer).

beforeDelete()  : Result|null

Read-only guard for deletion, plus: a job with non-deleted sheets is not deleted.

beforeSave()  : Result|null

Write guard of the job: nothing may be written into an archived one.

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.

connection()  : Connection

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.

lockLogChannel()  : string

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

releaseSourceLock()  : void

Releases the advisory lock.

runInSourceTransaction()  : T

Runs a closure in one raw-DBAL transaction with a deadlock retry (`SQLSTATE` 40001 / errno 1213).

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.

classifyStatesAmong()  : WorkListState>, 1: array}

Splits the raw states of the given jobs (one query, not N) into two maps `id => ...`: locked and unknown. The guard must see the current state, not what the identity map holds.

closingInvoiceIdOf()  : int|null

Invoice common to all `closing` sheets of the selection, or `null` (no `closing` sheet, no link, or more than one link).

closingRowsOf()  : array<int, array<string, mixed>>

Rows of the selection in state `closing` (recovery).

columnsInvalidateCache()  : bool

createFollowUpSheet()  : array{sheetId: ?int, error: ?string}

Step 10: follow-up empty sheet.

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.

deleteGuard()  : Result|null

Shared body of the delete guard (`beforeDelete()` and `deleteAll()`).

failure()  : Result

fetchListRow()  : array<string, mixed>|null

Authoritative job row (raw DBAL, see class docblock).

fetchSheetRows()  : array<int, array<string, mixed>>

Authoritative rows of the selected sheets in one query, as a map `sheetId => row`.

finishClosing()  : int

Step 9: finish. Invoice link, `state = 'invoiced'`, `bill = 0` and the stamp, all in one statement, so link and state appear together (see class docblock).

groupItemsBySheet()  : array<int, WorkItem>}>

Groups items under their sheets, the generator input shape: `['sheet' => WorkSheet, 'items' => WorkItem[]]` in sheet order.

guardInvoiceEntry()  : Result|array{list, array}

Input guards of invoicing, shared by the write path ({@see runInvoiceSheets()}) and the read-only preview ({@see previewInvoiceSheets()}).

guardSelectedSheets()  : Result|null

Guards of the selected sheets (step 2b): existence, membership in the job, deletion, unknown state and already invoiced. `null` means pass.

handleInvoiceSaveFailure()  : Result

Handles a failed `InvoiceManager::save()` and decides whether the invoice was created.

intOrNull()  : int|null

invoicedRowsOf()  : array<int, array<string, mixed>>

Rows of the selection in state `invoiced` linked exactly to invoice `$invoiceId`: the finished part of an interrupted run.

invoiceRowExists()  : bool

Whether the invoice row exists (see {@see self::INVOICES_TABLE}).

invoiceSuccess()  : Result

Uniform shape of the invoicing success: flat scalar data, so that the presenter only forwards it.

isAssetPathAllowed()  : bool

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

itemIds()  : array<int, int>

Sorted item ids, a comparable fingerprint of the selection. The order is normalized so that a mismatch is decided by the set, not by the random ordering of two queries.

ladd()  : numeric-string

lcmp()  : int

ldec()  : numeric-string

ldiv()  : numeric-string

Divides with half-up rounding to scale 3 (bcmath itself truncates; same rounding as {@see \App\UI\Api\Eshop\Models\Helpers\OrderCalculator::round3()}).

lInt()  : int

lmul()  : numeric-string

ln()  : numeric-string

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.

loadSheetsInOrder()  : array<int, WorkSheet>

Entities of the selected sheets ordered by `work_sheets.order` (then id), the order in which their items go on the invoice.

lockedFailure()  : Result

Uniform message of the read-only guard. An archived job is locked on purpose: it is a closed case and a silent edit would make the records diverge from what was already invoiced.

logDetachedInvoiceLinks()  : void

Logs the old invoice links that step 5 detaches, always before the update ({@see transitionToClosing()}).

lStr()  : string

lStrN()  : string|null

lsub()  : numeric-string

normalizeIds()  : array<int, int>

now()  : string

recoverInterrupted()  : Result

Recovery: at least one selected sheet is in `closing` (step 2c).

revertClosing()  : int

Reverts from `closing` to the original state with one update, again with a binding order in `set`: the target state is read from `state_before_closing` first, then the column is cleared.

rollbackBatch()  : void

runInvoiceSheets()  : Result

Invoicing body under the lock; never call outside {@see invoiceSheets()}.

runLockedListTransition()  : Result

Common envelope of job transitions: lock -> existence -> unknown state -> body. Legacy values `closing`/`closed` (rows from before the migration) behave like a "not open" job, so the conditional update does not match them and the admin gets a readable fail.

saveWithHooks()  : Result

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

sumItemPrices()  : string

Sum of item prices for the intent log: an indicative check number for finding the invoice, not the invoiced amount, which the Invoicer calculator computes authoritatively (VAT, rounding).

transitionToClosing()  : bool

Step 5: bulk transition `open|closed -> closing` in one conditional update.

unknownStateFailure()  : Result

Fail-closed guard: a raw `state` value outside the enum. The message prints the DB value instead of silently substituting `Open`/`Archived`: the column is `not null`, so only a genuinely broken row gets here (manual update, migration typo) and the admin must know exactly what is in the DB instead of getting an archive message that points to the wrong button.

usesAssetPathTrait()  : bool

set state_before_closing = state,   -- 1) reads the original value
    invoicer_invoice_id = null,     -- 2) detaches the old link (re-invoicing after reopen)
    state = 'closing'               -- 3) only now overwrites the state