CoolCMS API

ProductImportManager extends Manager

in package

• Application

Manages product import jobs: CRUD plus state transitions kept outside the generic save.

Tags

extends

Table of Contents

Constants

RUN_NOW_MAX_ITEMS  : int = 200

Maximum number of items for "run now" (synchronous in the admin request).

STALE_RUNNING_SECONDS  : int = 1800

Seconds after `startedTime` when a `running` job is considered dead (`php-fpm` crash, time limit, process kill: `finally` did not run and the job would stay `running` forever).

DELETED_IDS_META  : string = '__deletedIds'

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

ALLOWED_TRANSITIONS  : array<string|int, mixed> = [ // `validated`/`invalid` to `validated`/`inva...

CHART_BUCKETS  : array<string|int, mixed> = ['day' => '%Y-%m-%d', 'week' => '%x-%v', 'month...

MySQL `DATE_FORMAT` masks for the runs-over-time chart ({@see getRunsChart()}).

EXECUTE_LOG_SUFFIX  : string = '.execute.jsonl'

Suffix of the row log of the real run, a separate file next to the validation log (`phase:"execute"`).

EXECUTE_SUMMARY_SUFFIX  : string = '.execute.summary.json'

Suffix of the real run summary (write counts) next to the execution log.

LOG_SUFFIX  : string = '.validate.jsonl'

Suffix of the validation row log (JSONL) next to the import file.

NOTIFICATION_TYPE_KEY  : string = 'ESHOP_IMPORT_DONE'

Key of the "product import finished" notification type (`cms_system_notification_types.key`).

STATISTICS_DEFAULT_RANGE_DAYS  : int = 30

Default period length in days for {@see getStatistics()} and {@see getRunsChart()} when the caller sends no range.

STATISTICS_DEFAULT_RECENT_LIMIT  : int = 20

Number of latest runs {@see getStatistics()} returns for the admin table.

STATUS_TAIL  : int = 20

Number of last errors/warnings from the execution log returned by `status` polling.

SUMMARY_SUFFIX  : string = '.validate.summary.json'

Suffix of the dry-run summary (predicted create/update/skip counts) next to the log.

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

$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

$em  : EntityManagerInterface

$importExecutor  : ImportExecutor

$importLogReader  : ImportLogReader

$importParserFactory  : ImportParserFactory

$importValidator  : ImportValidator

$notificationManager  : NotificationManager

$notificationTypeManager  : NotificationTypeManager

$productSetManager  : ProductSetManager

$productXmlExporter  : ProductXmlExporter

$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

enqueue()  : Result

Queues the job (`validated` to `queued`); the cron `/cron/eshop/product-import/run` picks it up within a minute.

export()  : Result

Exports the catalog in the import format.

failStaleRunning()  : array<int, int>

Marks stuck `running` jobs as `failed` and appends a line to the execution log.

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

getRunsChart()  : Result

Returns the runs-over-time chart for {@see \App\UI\Admin\Eshop\Components\StatisticsChartComponent\StatisticsChartControl}.

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

getStatistics()  : Result

Returns a summary of runs in `[from, to]` (by `insertTime`): job counts by state, sums of the item counters and the last `$recentLimit` runs for the admin table.

getStatus()  : Result

Returns the job state for `status` polling: counters, state and the last errors/warnings from the execution log. The log path always comes from the job.

getTotalCount()  : int|null

getValidationReport()  : Result

Returns a paginated preview of the row log plus the summary.

initializeAllContexts()  : void

registerEvent()  : Result

run()  : Result

Performs the real run: `queued` to `running` to `done` or `failed`.

runNow()  : Result

Runs the job synchronously from the admin ("run now", up to {@see RUN_NOW_MAX_ITEMS} items).

save()  : Result

setAppContext()  : $this

setAssetFormatRegistry()  : static

setCacheTagInvalidator()  : static

setInternalCallContext()  : static

setLanguageContext()  : $this

setParamsConfig()  : static

setPresenterContext()  : $this

setSettingContext()  : $this

setState()  : Result

Moves the job to a new state with validation; this is the external channel (Api/admin).

updateAllRelations()  : Result

updateColumn()  : Result

updateColumns()  : Result

updateRelations()  : Result

validate()  : Result

Validates the job as a dry run: parses the file, checks matching, code lists and limits, and writes a JSONL row log. Writes nothing to the catalog.

beforeDelete()  : Result|null

Refuses to delete a running job; any other job can be deleted.

beforeSave()  : Result|null

On insert, enforces server defaults (state `uploaded`, zeroed counters) regardless of the form.

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

Best-effort file cleanup after the record is deleted (import file and row log).

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

appendExecuteLogRow()  : void

Appends an `error` row to the end of the execution log (the run log must not be overwritten). Best-effort.

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.

deleteImportFiles()  : void

deleteImportNotifications()  : void

Deletes the "import finished" notifications of deleted imports, because they link to the import detail and the bell would lead to a 404.

describeAbortProgress()  : string

Returns a suffix for the crash error describing what was written until then (it is not rolled back).

fetchStateRow()  : DateTime}|null

findNotificationTypeId()  : int|null

Returns the notification type id; creating a notification respects the type switch (`$onlyActive`).

invalidFilePathResult()  : Result

isAssetPathAllowed()  : bool

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

isStale()  : bool

Returns whether a run without `startedTime` or older than {@see STALE_RUNNING_SECONDS} is stuck.

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.

readExecutionSummaryFile()  : array<string, int|bool>

readSummaryFile()  : array<string, int>

resolveExecutionSummaryPath()  : string

resolvePrivateDir()  : string|null

resolveStatisticsRange()  : DateTime}

resolveSummaryPath()  : string

Returns the dry-run summary path: next to the log, same path with another suffix (deleted with it).

rollbackBatch()  : void

saveWithHooks()  : Result

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

sendDoneNotification()  : void

Sends the admin bell notification of type `ESHOP_IMPORT_DONE` to the user who uploaded the job.

staleCutoff()  : string

Returns the stuck-run boundary as a column value (`started_time < cutoff`), same time basis as {@see isStale()}.

toDateTimeOrNull()  : DateTime|null

toInt()  : int

Casts a `mixed` DBAL value to int (a direct cast of `mixed` fails PHPStan level 9).

toStringValue()  : string

transition()  : Result

Performs an atomic state transition: `UPDATE ... SET state = :new WHERE id = :id AND state = :old`.

updateValidationCounters()  : void

Writes the validation counters outside the generic `save()`, which resets them from the DB on UPDATE.

usesAssetPathTrait()  : bool

writeExecutionSummaryFile()  : void

writeProgress()  : bool

Writes the progress of the real run with raw DBAL on the own table.

writeSummaryFile()  : void