CoolCMS API

InvoiceManager extends Manager

in package

• Application

uses SaveTrait, DecimalQuantityGuardTrait

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

Tags

extends

Table of Contents

Constants

META_PDF_ONLY_ON_CHANGE  : string = 'pdfOnlyOnChange'

Save `$meta` key: regenerate the PDF/QR only when something printed in the PDF changed (or the file is missing). Sent only by the invoice form save in the admin; without it (order and payment generators, scheduler, Api) the PDF is generated on every save.

META_SEND_EMAIL_ON_SAVE  : string = 'sendEmailOnSave'

Meta of the admin form: after the save send the invoice by e-mail when "Send by e-mail" is checked and it was not sent yet ({@see sendEmailAfterSave()}). Only the admin passes it; the schedule and the payment invoice send on their own paths, external meta is stripped.

SAVE_INFO_EMAIL  : string = 'invoiceEmail'

`saveInfo` key with the outcome of {@see META_SEND_EMAIL_ON_SAVE} (`InvoiceEmailState` value).

DELETED_IDS_META  : string = '__deletedIds'

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

TABLE_INVOICE_ITEMS  : string = 'cms_mod_invoicer_invoice_items'

Tables whose `quantity` becomes `decimal(8,2)` (elsewhere it stays an integer piece count).

TABLE_INVOICE_TEMPLATE_ITEMS  : string = 'cms_mod_invoicer_invoice_template_items'

INVOICE_FK  : string = 'cms_mod_invoicer_invoices_invoice_id'

META_PDF_FINGERPRINT_BEFORE  : string = '__pdfFingerprintBefore'

Internal `$meta` key: fingerprint of the printed data computed from the database before saving (`beforeSave()` to `completedSave()`).

PAYMENT_DEFAULT_BATCH  : int = 10

PAYMENT_QUEUE  : string = 'invoicer.payment.invoice'

PDF_FINGERPRINT_LINES  : array<string|int, mixed> = ['cms_mod_invoicer_invoice_items' => 'invoice_i...

Invoice lines that go into the PDF (items, shipping, payment, gifts, vouchers): table => primary key.

PDF_FINGERPRINT_SKIP_HEAD  : array<string|int, mixed> = ['pdf', 'qr_code', 'update_datetime', 'send_ema...

Header columns that are not printed in the PDF/QR (email block, file pointers, update timestamp); only these are left out of the fingerprint. Everything else (seller and customer snapshot, VAT mode, language, localization, PDF variant, sums) is included.

SETTING_MODULE  : int = 7

TABLE_INVOICES  : string = 'cms_mod_invoicer_invoices'

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<int, string>

`pdf` and `qrCode` are filled only through `updateColumn` in the PDF/QR generator (post-commit), never by an object-graph save. Skipping them in hydration keeps a normal invoice save from overwriting them with the empty value from the form.

$emailManager  : EmailManager|null

Sends the invoice e-mail after an admin save ({@see sendEmailAfterSave()}). A plain property with a default: unit tests build the manager without the constructor and nothing is sent then.

$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

$calculator  : InvoiceCalculator

$cronFailureManager  : CronFailureManager

$currencyManager  : CurrencyManager

$decimalQuantityColumns  : array<string, bool>

Whether `quantity` is a decimal column, per table. Valid for this request only (the schema does not change during a request; the alter is a maintenance step between requests).

$em  : EntityManagerInterface

$generator  : InvoiceGenerator

$invoiceService  : InvoiceService

$numberGenerator  : InvoiceNumberGenerator

$paymentManager  : PaymentManager

$paymentStatusRuleManager  : PaymentStatusRuleManager

$pdfGenerator  : InvoicePdfGenerator

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

Methods

__construct()  : mixed

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

find()  : T|null

findAll()  : T> : list>)

findBy()  : T|null

findLatestNonCreditForOrder()  : array{invoiceId: int, number: ?string, pdf: ?string, qrCode: ?string, variableSymbol: ?string, dueDate: ?string, status: ?string, bankAccount: ?string, iban: ?string}|null

Returns the latest non-credit-note document of an order (proforma or invoice). Invoicer owns the documents, so the eshop checkout return page asks here instead of joining Invoicer tables itself.

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

lock()  : Result

Locks an invoice explicitly (administrator action). Irreversible; an already locked invoice keeps its original time and reason (returns success, `alreadyLocked = true`).

lockedAt()  : string|null

Returns the lock time of an invoice read straight from the database (raw DBAL: no Api read, so no `UoW::clear()` in the middle of save hooks). `null` when the invoice is not locked or does not exist.

processPaidPayments()  : array{processed: int, generated: int, emailed: int, skipped: int, ignored: int, errors: list}

Periodically issues invoices from payments by the rules "payment status to invoice type" (cron `cron/invoicer/payment/generate`). Generation is separate from the payment gateway callback (no PDF/QR is built in the gateway response) and serialized (the base cron holds {@see \App\UI\Api\System\Models\Managers\CronLockManager}).

registerEvent()  : Result

save()  : Result

setAppContext()  : $this

setAssetFormatRegistry()  : static

setCacheTagInvalidator()  : static

setInternalCallContext()  : static

setLanguageContext()  : $this

setParamsConfig()  : static

setPresenterContext()  : $this

setSettingContext()  : $this

updateAllRelations()  : Result

updateColumn()  : Result

updateColumns()  : Result

Writing `emailIsSent = true` locks the invoice, whoever writes it (admin through Api `send-email`, payment generator, scheduler). This `updateColumns()` is the only place the flag is written, so another sending path cannot bypass the lock.

updateRelations()  : Result

afterSave()  : Result|null

Locks the source of a credit note or cancellation. Runs inside the save transaction, so a credit note without a locked source cannot exist (a failed lock rolls the credit note back).

beforeDelete()  : Result|null

Blocks hard delete of an invoice with a number from a billing line.

beforeSave()  : Result|null

Domain core of the invoice: authoritative recalculation of totals from the collections (client numbers are never trusted); on insert without a number it generates the number, order and `period_key`, and fills in the variable symbol.

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.

completedSave()  : void

After the commit: PDF/QR ({@see refreshPdfAfterSave()}), then the invoice e-mail of an admin save ({@see META_SEND_EMAIL_ON_SAVE}); both best effort.

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

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

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.

duePayments()  : array<int, Payment>

Returns payments of the status not yet invoiced for it (`invoiced_status` is null or differs from the status). Parked payments (in backoff) are skipped; ordered by id (deterministic).

findFractionalQuantity()  : string|null

Returns the first fractional quantity in the collection, or `null`. Compared with `fmod()`, not by string shape: the setter also receives `int`/`float`, and after hydration the getter returns the database spelling, which may differ ('2.5' vs '2.50').

guardFractionalQuantity()  : Result|null

Rejects the write when a line has a fractional quantity and the column is still an integer.

hasDecimalQuantityColumn()  : bool

Tells whether `quantity` of the table is already `decimal`; unknown counts as no (rejecting is safer).

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.

lockRows()  : int

Locks rows that are not locked yet (conditional `UPDATE`; the first lock wins).

noInvoicingCurrencyIds()  : array<int, int>

Returns ids of currencies with invoicing off: `Currency.no_invoicing` or a non-monetary currency (`monetary = 0`, credits). A payment in credits (topping) never has an invoice, even if someone unticks `no_invoicing` on the currency.

pdfFingerprint()  : string|null

Returns a fingerprint of everything printed in the invoice PDF/QR: the whole header (except {@see PDF_FINGERPRINT_SKIP_HEAD}) and the content of all line kinds ({@see PDF_FINGERPRINT_LINES}), read with raw DBAL straight from the database. Called both before and after saving.

refreshPdfAfterSave()  : void

Regenerates QR and PDF after commit. Runs outside the save transaction, best effort: `SaveTrait` wraps the call in try/catch (an exception is only logged), so a generator failure must not break an already saved invoice (fail-open).

rollbackBatch()  : void

rulesByStatus()  : array<int, int>

Returns active rules grouped as payment status to invoice type (Api `findAll()` returns an array). One status maps to at most one type (unique on `payment_status`); a later row would overwrite a duplicate, which database integrity does not allow anyway.

saveWithHooks()  : Result

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

sendEmailAfterSave()  : InvoiceEmailState|null

Admin save with "Send by e-mail" checked: sends the invoice (PDF attached) with its own subject and body under the admin template ({@see InvoiceEmailTemplate::Admin}, straight to the recipient) unless it was sent already.

settingBool()  : bool

settingInt()  : int

settleWithoutInvoice()  : void

Settles a payment without a document (currency with invoicing off, or a payment with no customer invoice). `ignored` counts only when the `invoiced_status` watermark was really written; an unwritten watermark is an error with backoff, otherwise the payment would silently return to the queue.

usesAssetPathTrait()  : bool