« Back to list view

The SuperVersionable behavior

This behavior is based on the Versionable behavior included with Doctrine 1.0.

 

Major differences are:

  • In addition to past versions it supports the creation of future updates (aka scheduled updates).
  • It removes the option to forgo the audit log.
  • It adds the option to enable support for future versions.

Versionable and SuperVersionable must never be used at the same time on the same model.

 

Definition

schema.yml

MyModel:
  actAs:
    SuperVersionable: 
      # Auto-delete versions when deleting a parent record
      # Otherwise deleting is not possible due to constraint failure
      cascadeDelete: true

 

Tables and columns

The SuperVersionable behavior adds the following fields to the model table itself:

  •  version
    • Indicates the current version of a row

It also manages an addition table (e.g. ull_user_version) with contains:

  • the same fields as the model itself (id, first_name, last_name, etc.) including the version column
  • reference_version
    • If the row is a scheduled update which is not yet applied, this column specifies the version of the row this update references, i.e. the version that was current at the update's insertion time.
    • If the row is a regular past version and the result of a scheduled update, this column references the future update which caused the creation of this version.
    • Is NULL otherwise.
  • scheduled_update_date
    • The date this future version is or was scheduled to apply.
    • Is NULL if this row is/was not a future version.
  • done_at
    • When a future version is applied, this column is set to the current date.

The primary key of this versioning table is a combined PK (id, version) - this ensures unique versions.


Future version creation

The table tool generator (which is responsible for column configuration before form creation) adds a 'scheduled update date' field if the model the generator is based on has the SuperVersionable-template. This field is an ullMetaWidgetDate and includes a special validator which checks if an optionally entered date is actually in the future.


Future version insertion

The SuperVersionable behavior watches all record updates (via the preUpdate() method) for changsets where scheduled_update_date is set (see above). If it finds one, it skips the actual record insertion (skipOperation() in the Doctrine_Event) but creates a new entry in the versioning table with fitting scheduled_update_date and reference_version column data.


Future version application

ullright specifies a new task which should be run at least daily to ensure the correct application of future updates which are due, i.e. have scheduled update dates in the past.

php symfony ullright:apply-scheduled-updates

This task enumerates all models which feature the SuperVersionable-template, looks for due scheduled updates and applies them, also setting the done_at and reference_version columns.

 

Related files

All in plugins/ullCorePlugin/lib/behaviours:

  • SuperAuditLog.php
  • SuperAuditLogListener.php
  • SuperVersionable.php