Snapshot Storage

The history is in one table, resource_versions (with the installation's table prefix, such as omeka_resource_versions). It has no foreign keys into Omeka's tables, so the history outlives the record, its owner and everything its snapshot refers to.

Columns#

Indexes cover (record_type, record_id, version_num), (user_id, created_at), created_at, (batch_key, is_batch) and restored_from. A snapshot can be up to 16 MB; snapshots are not compressed.

A second table, resource_version_runs, records the batch rollbacks and prunes run in the background: their criteria, status (queued, running, done, error), result, the batch key of the versions they wrote, who started them, and when.

Operations#

Capture#

The plugin listens to Omeka's record hooks for items, collections and files: before_save_* and after_save_*, before_delete_* and after_delete_*. These run for every save, whatever made it: the admin forms, batch edit, the REST API, importers, background jobs, scripts.

• after_save_* builds one snapshot from the database (four queries for an item, two for a collection or file), compares its hash with the newest version's, read in before_save_*, and inserts one row when it differs.
• before_save_*, for a record with no history, first keeps its state as a baseline.
• before_delete_* reads the record's last state while it exists; after_delete_* writes it.
• Saves of a record made while it is being created (such as the derivative job Omeka runs on a new file) are left to the creation, which records the final state once.
• Saves made in Omeka's batch edit request (items/batch-edit-save) or in a background job or command-line script are marked as bulk, under the key of that request or process.

An exception in any of this is written to the PHP error log, and to Omeka's log, with the prefix [ResourceVersioning], and dropped: a failure to record never makes a save fail. A batch edit of 50 items takes about 3 ms more per item.

Changes made straight in the database, without saving the record through Omeka, are not recorded. Among Omeka's own:

• Adding files to an existing item from code (insert_files_for_item()) saves the files, not the item: the files get their create versions at once, and the item's file list is updated at its next save. Adding files from the item form saves the item.
• Deleting a collection takes its items out of it with a direct update: the items' histories show the change at their next save.
• Renaming or deleting a tag on the Tags page changes items without saving them.

Admin addresses#

All are under /admin/resource-versioning, handled by ResourceVersioning_IndexController.

POST requests need the CSRF token the pages include.