CoolCMS API

ComplaintManager extends Manager

in package

• Application

uses BlacklistGuardTrait, ComplaintFileTrait, SourceLockTransactionTrait

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

Tags

extends

Table of Contents

Constants

MAX_FILE_SIZE  : int = 5 * 1024 * 1024

MAX_FILES  : int = 5

Attachment limits per complaint.

DELETED_IDS_META  : string = '__deletedIds'

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

COMPLAINTS_TABLE  : string = 'cms_mod_eshop_complaints'

CREATED_STATUS_KEY  : string = 'CREATED'

DEFAULT_EXPIRATION_DAYS  : int = 30

Fallback number of days until expiry when `4/complaint.expirationDays` is not set.

DESCRIPTION_MAX_LENGTH  : int = 5000

DESCRIPTION_MIN_LENGTH  : int = 20

Length limits of the defect description, column `text`.

ELIGIBLE_ORDER_STATUS_KEYS  : array<string|int, mixed> = ['SENT', 'DONE', 'RETURNED']

Order status keys from which a complaint may be submitted.

FK_STATUS  : string = 'cms_mod_eshop_complaint_statuses_complaint_sta...

ITEMS_TABLE  : string = 'cms_mod_eshop_complaint_items'

LOCK_MAX_ATTEMPTS  : int = 3

LOCK_SCALE  : int = 3

META_CREATED_EMAIL  : string = '__complaintCreatedEmail'

Internal meta flag meaning "this complaint gets the `CREATED` e-mail"; set only by {@see self::doSubmitForUser()}.

REJECTED_STATUS_KEY  : string = 'REJECTED'

SAVE_LOCK_TIMEOUT  : int = 5

Per-complaint lock timeout; the lock name is the same as in {@see ComplaintTransitionManager} and {@see ComplaintStockManager}.

STATUSES_TABLE  : string = 'cms_mod_eshop_complaint_statuses'

STORE_DOCUMENTS_TABLE  : string = 'cms_mod_store_stock_documents'

STORE_SOURCE_MODULE  : int = 4

Source of the Store return document, see {@see ComplaintStockManager} (`SourceRef(4,'complaint',$id)`).

STORE_SOURCE_TYPE  : string = 'complaint'

SUBMIT_LOCK_TIMEOUT  : int = 5

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

$defaultSkipFields  : array<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

$complaintSolutionManager  : ComplaintSolutionManager

$complaintStatusManager  : ComplaintStatusManager

$em  : EntityManagerInterface

$emailGenerator  : ComplaintEmailGenerator

$emailQueueManager  : EmailQueueManager

$fileManager  : FileManager

$orderManager  : OrderManager

$pendingComplaintDirs  : array<int, string>

Attachment directories created by this save (deleted when they stay empty).

$pendingComplaintFiles  : array<int, string>

Absolute paths of files written during the currently running complaint save.

$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

canUserWrite()  : bool

Tells whether `$userId` may write this complaint; the single input of the RBAC gate of the `save` action ({@see \App\UI\Api\Eshop\Presenters\ComplaintPresenter::verifyOwnership()}).

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

Bulk delete by filters (`api/eshop/complaint/delete-all`); it goes through {@see delete()}.

detailForUser()  : array{success: bool, message?: string, errorCode?: string, complaint?: array}

Returns the detail of the user's own complaint.

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 the owner data: the owner is the `$user` association (mapped in the Api leaf to `cms_system_users_user_id`), filled from the JWT on an external insert.

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

getFileData()  : array{success: bool, errorCode?: string, message?: string, path?: string, extension?: string, complaintId?: int, position?: int}

Same for the admin, without the ownership gate (admin sees all complaints); the privilege is checked by {@see \App\UI\Api\Eshop\Presenters\ComplaintPresenter::internalActionFile()}.

getFileDataForUser()  : array{success: bool, errorCode?: string, message?: string, path?: string, extension?: string, complaintId?: int, position?: int}

Returns the relative path of a complaint attachment for its owner.

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

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

getLanguageContext()  : LanguageContext|null

getOrderPrefillData()  : array{success: bool, message?: string, customer?: array, items?: list>}

Prefills complaint items from an order picked in the admin.

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

Tells whether the complaint `$complaintId` belongs to the user `$userId`.

listForUser()  : array{success: bool, complaints: list>, total: int}

Lists the user's own complaints.

prefillForUser()  : array{success: bool, message?: string, errorCode?: string, customer?: array, items?: list>, solutions?: list}

Returns order items with the remaining quantity that can still be complained about, plus the code list of preferred solutions (in the order language).

registerEvent()  : Result

rejectionReasonForNewFiles()  : string|null

Pre-write guard for new attachments, called by {@see \App\UI\Api\Eshop\Models\Managers\ComplaintManager::submitForUser()}.

save()  : Result

Saves a complaint; an update of an existing one runs under the per-complaint lock (`cms_eshop_complaint_<id>`).

setAppContext()  : $this

setAssetFormatRegistry()  : static

setCacheTagInvalidator()  : static

setInternalCallContext()  : static

setLanguageContext()  : $this

setParamsConfig()  : static

setPresenterContext()  : $this

setSettingContext()  : $this

submitForUser()  : Result

Creates a complaint from the front end; the only write entry from the front end.

updateAllRelations()  : Result

updateColumn()  : Result

updateColumns()  : Result

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

afterSave()  : Result|null

Runs inside the `save()` transaction: attachments first, then (front end submit only) the `CREATED` e-mail into the queue.

beforeDelete()  : Result|null

Refuses to hard-delete a complaint that has a stock return.

beforeSave()  : Result|null

Guards the generic `save` (admin form, Api `save`, internal calls): complaint status, stock return and the economic items after a return have their own paths that the generic object graph must not bypass.

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

associationId()  : int|null

blacklistRefusal()  : Result|null

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.

checkOrderEligibility()  : array<string, mixed>|Result

Common gate of `submitForUser()` and `prefillForUser()`: eligibility of the order status plus ownership.

columnsInvalidateCache()  : bool

complaintAssetDir()  : string

complaintFilesWriteResult()  : Result|null

Returns a failure for `afterSave()` (rollback) when the relation write failed, `null` on success.

complaintItemsChanged()  : bool

Tells whether the economic shape of the items differs from the DB.

complaintsWithStockReturn()  : array<int, int>

Returns which complaints have a stock return: a `stock_document_id`, or a Store document with source `4/complaint/<id>` in any state.

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.

discardPendingComplaintFiles()  : void

Deletes files (and empty directories) written by the running save; called when it fails.

doSubmitForUser()  : Result

enqueueCreatedEmail()  : Result|null

Renders the `CREATED` e-mail and inserts it into the queue on the same connection inside the save transaction (a transactional outbox, like {@see ComplaintTransitionManager}).

expirationDays()  : int

fileByPosition()  : array{path: string, extension: string}|null

Resolves the attachment by position, with the same ordering and filter as {@see self::fileSummaryForDetail()} (`cf.order, file_id`, only `removed = 0`); `$position` is 1-based, so `OFFSET position - 1`.

fileDataResult()  : array{success: bool, errorCode?: string, message?: string, path?: string, extension?: string, complaintId?: int, position?: int}

fileSummaryForDetail()  : array<int, array{extension: string}>

Returns attachments for the customer detail, only order and extension.

forgetPendingComplaintFiles()  : void

The save finished (success) or was already cleaned up: files stop being pending.

isAssetPathAllowed()  : bool

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

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

loadComplaintById()  : Complaint|null

Typed wrapper over {@see \App\Core\Traits\Api\Models\Managers\GetTrait::find()} that returns the concrete Api leaf entity, not `?BaseEntity`.

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.

lStr()  : string

lStrN()  : string|null

lsub()  : numeric-string

normalizeFileItems()  : array<int, array{type: string, fileId?: int, name?: string, data?: string, path?: string, order?: int}>

Normalizes `meta['files']`, which is Api/admin input, into a guaranteed shape.

orderItemProxy()  : OrderItem|null

Returns an `OrderItem` reference via `getReference()`, not `new OrderItem(); setId()`.

orderLanguageId()  : int

persistedComplaintState()  : array{statusId: int|null, stockDocumentId: int|null}|null

Returns the authoritative status and stock return from the DB; the row stays locked until the end of the `save()` transaction.

processComplaintFiles()  : Result|null

Processes the ordered attachment list (existing and new items in one array).

remainingQuantities()  : array<int, int>

Returns the remaining quantity per order item that can still be complained about.

rollbackBatch()  : void

saveWithHooks()  : Result

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

scalarInt()  : int

scalarStr()  : string

scalarStrN()  : string|null

solutionTranslationName()  : string|null

statusReturnsStock()  : bool

statusTranslationName()  : string|null

usesAssetPathTrait()  : bool

writeComplaintFiles()  : Result|null