Reference

Services and Jobs

The module registers three services in the Omeka S service manager and two background jobs. Other modules and CLI scripts can use them directly.

Services

ResourceVersioning\Service\VersionManager

Storage and retrieval of version rows. Key methods:

Method Description
snapshot(string $resourceType, int $resourceId, array $jsonLd, string $operation, $user = null, array $options = []): int Store a snapshot. Returns the new row id, or 0 when skipped (capture disabled, type not enabled, or duplicate of the latest version). Options: is_batch, batch_key, restored_from.
getVersion(int $versionId): ?array One row with payload decoded to an array
getLatest(string $resourceType, int $resourceId): ?array Newest version of a resource
getPredecessor(array $version): ?array The version before the given one
getVersionBefore(string $resourceType, int $resourceId, string $cutoff): ?array Newest version created strictly before cutoff (Y-m-d H:i:s)
listForResource(string $resourceType, int $resourceId, int $limit = 50, int $offset = 0): array History rows without payloads, newest first
listAll(array $filters = []): array, countAll(array $filters = []): int Global browse; filters resource_type, resource_id, user_id, operation, batch_key, date_from, date_to, limit, offset
listBatchGroups(array $filters = []): array Batch keys with more than one version, with counts and time span
findAffectedResources(array $criteria): array Distinct resource_type / resource_id pairs matching the criteria
prune(string $resourceType, int $resourceId): void Enforce the per-resource cap
pruneByAge(int $batchSize = 1000): int Delete one batch of rows older than the retention period; returns rows deleted
hashPayload(array $jsonLd): string (static) The deduplication hash
beginRestore(int $versionId), endRestore(), restoringFrom(): ?int Flag used so that the capture listener records a restore as operation restore

Setting accessors: isEnabled(), enabledResourceTypes(), isTypeEnabled(string), captureBatchEnabled(), maxVersionsPerResource(), retentionDays().

Constants: VersionManager::RESOURCE_TYPES (items, media, item_sets), OPERATION_CREATE, OPERATION_UPDATE, OPERATION_DELETE, OPERATION_RESTORE, OPERATION_BASELINE, TABLE.

ResourceVersioning\Service\RestoreService

Method Description
prepareRestorePayload(array $jsonLd): array Returns ['payload' => array, 'warnings' => string[]]: strips the keys listed in Restoring a Version, removes the owner unless the setting allows it, and drops values and item set references whose target resource no longer exists
restore(int $versionId): array Apply one version via a full API update. Returns ['success' => bool, 'message' => string, 'warnings' => string[]]. Refuses delete snapshots and resources that no longer exist.
rollbackTargets(array $criteria): array Dry run. Returns ['cutoff' => ?string, 'targets' => array]; each target has resource_type, resource_id, resource_exists, target (id, version_num, operation, resource_title, created_at) and skip_reason
rollback(array $criteria, ?callable $shouldStop = null): array Execute the plan. Returns ['restored' => int, 'skipped' => int, 'failed' => int, 'errors' => string[]] (at most 100 error strings)

Criteria keys: batch_key, or date_from with optional date_to, user_id, and resource_type. Dates are Y-m-d H:i:s.

ResourceVersioning\Service\ReferenceLabelResolver

resolve(string $key, int $id): ?string looks up a display label for a JSON-LD reference at render time and caches it for the request. Supported keys: o:resource_class (label and term), o:resource_template, o:item_set, o:media, o:primary_media, o:owner, o:thumbnail, o:site. Returns null when the target no longer exists.

Diff classes

ResourceVersioning\Diff\JsonLdDiff::compare(array $old, array $new, ?callable $labelResolver = null): array returns has_changes, scalars, properties, and summary. JsonLdDiff::toText(array $jsonLd): string produces the canonical pretty-printed JSON used by ResourceVersioning\Diff\TextDiff::diff() and TextDiff::toHtml() for the raw view.

Jobs

ResourceVersioning\Job\BatchRollback

Arguments: batch_key, user_id, date_from, date_to, resource_type, all optional but at least one required. Calls RestoreService::rollback() with the job's stop flag and logs the criteria, the final counts, and each error. Dispatch it from code with:

$services->get('Omeka\Job\Dispatcher')->dispatch(
    \ResourceVersioning\Job\BatchRollback::class,
    ['batch_key' => '0a1b2c3d4e5f60718293a4b5c6d7']
);

ResourceVersioning\Job\PruneVersions

No arguments. Calls VersionManager::pruneByAge() in batches of 1,000 rows until no rows remain, logging the total. Exits immediately when the retention period is 0.

Settings keys

resource_versioning_enabled, resource_versioning_resource_types, resource_versioning_max_versions, resource_versioning_retention_days, resource_versioning_capture_batch, resource_versioning_restore_owner. All are global settings (Omeka\Settings).

Log in for Support