class Versioned extends DataExtension implements TemplateGlobalProvider (View source)

The Versioned extension allows your DataObjects to have several versions, allowing you to rollback changes and view history. An example of this is the pages used in the CMS.

Constants

DEFAULT_MODE

The default reading mode

LIVE

The Public stage.

DRAFT

The draft (default) stage

Properties

DataObject $owner
protected DataObject $ownerBaseClass

The base class that this extension was applied to; $this->owner must be one of these

from  Extension
public $class from  Extension
protected array $stages

An array of possible stages.

protected string $defaultStage

The 'default' stage.

protected string $liveStage

The 'live' stage.

public string $migratingVersion

A version that a DataObject should be when it is 'migrating', that is, when it is in the process of moving from one stage to another.

protected static array $cache_versionnumber

A cache used by get_versionnumber_by_stage(). Clear through flushCache().

protected static bool|null $is_draft_site_secured

Set if draft site is secured or not. Fails over to $draft_site_secured if unset

protected static string $reading_mode

Current reading mode

protected static null $default_reading_mode

Default reading mode, if none set.

public bool $_nextWriteWithoutVersion

Flag which is temporarily changed during the write() process to influence augmentWrite() behaviour. If set to true, no new version will be created for the following write. Needs to be public as other classes introspect this state during the write process in order to adapt to this versioning behaviour.

protected static array $versionableExtensions

An array of DataObject extensions that may require versioning for extra tables. The array value is a set of suffixes to form these table names, assuming a preceding '_'. E.g. if Extension1 creates a new table 'Class_suffix1' and Extension2 the tables 'Class_suffix2' and 'Class_suffix3':

int $RecordID
int $Version
bool $WasPublished
int $AuthorID
int $PublisherID

Methods

public
__construct(array $stages = array('Stage', 'Live'))

Construct a new Versioned object.

public static 
add_to_class(string $class, string $extensionClass, mixed $args = null)

Called when this extension is added to a particular class

public
setOwner(SS_Object $owner, string $ownerBaseClass = null)

Set the owner of this extension.

public
clearOwner()

No description

public
getOwner()

Returns the owner of this extension.

public static 
string
get_classname_without_arguments(string $extensionStr)

Helper method to strip eval'ed arguments from a string thats passed to DataObject::$extensions or Object::add_extension().

public static 
get_extra_config($class, $extension, $args)

No description

public static 
unload_extra_statics($class, $extension)

No description

public
validate(ValidationResult $validationResult)

Hook for extension-specific validation.

public
augmentSQL(SQLQuery $query, DataQuery $dataQuery = null)

Augment the the SQLQuery that is created by the DataQuery.

public
augmentDatabase()

Update the database schema as required by this extension.

public
augmentWrite(array $manipulation)

No description

public
onBeforeWrite()

No description

public
onAfterWrite()

No description

public
onBeforeDelete()

No description

public
onAfterDelete()

No description

public
requireDefaultRecords()

No description

public
populateDefaults()

No description

public
can($member)

No description

public
canEdit($member)

No description

public
canDelete($member)

No description

public
canCreate($member)

No description

public
array
extraStatics($class = null, $extension = null)

Define extra database fields

public
updateCMSFields(FieldList $fields)

No description

public
updateFrontEndFields(FieldList $fields)

This function is used to provide modifications to the form used for front end forms. DataObject->getFrontEndFields()

public
updateCMSActions(FieldList $actions)

This is used to provide modifications to the form actions used in the CMS. DataObject->getCMSActions().

public
updateSummaryFields(array $fields)

this function is used to provide modifications to the summary fields in CMS by the extension By default, the summaryField() of its owner will merge more fields defined in the extension's $extra_fields['summary_fields']

public
updateFieldLabels(array $labels)

No description

public static 
reset()

Reset static configuration variables to their default values.

public
augmentDataQueryCreation(SQLQuery $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

public
augmentLoadLazyFields(SQLQuery $query, DataQuery $dataQuery = null, DataObject $dataObject)

For lazy loaded fields requiring extra SQL manipulation, ie versioning.

public static 
on_db_reset()

Called by SapphireTest when the database is reset.

protected
augmentWriteVersioned(SQLQuery $manipulation, string $table, string|int $recordID)

Generates a ($table)_version DB manipulation and injects it into the current $manipulation

protected
augmentWriteStaged(array $manipulation, string $table, string|int $recordID)

Rewrite the given manipulation to update the selected (non-default) stage

public
int
writeWithoutVersion()

Perform a write without affecting the version table.

public
onAfterSkippedWrite()

If a write was skipped, then we need to ensure that we don't leave a migrateVersion() value lying around for the next write.

public
bool|null
canView(Member $member = null)

Extend permissions to include additional security for objects that are not published to live.

public
bool
canViewVersioned(Member $member = null)

Determine if there are any additional restrictions on this object for the given reading version.

public
bool
canViewStage(string $stage = 'Live', Member $member = null)

Determines canView permissions for the latest version of this object on a specific stage.

public
bool
canBeVersioned(string $table)

Determine if a table supports the Versioned extensions (e.g. $table_versions does exists).

public
bool
hasVersionField(string $table)

Check if a certain table has the 'Version' field.

public
string
extendWithSuffix(string $table)

No description

public
bool
latestPublished()

Is the latest version of the object published?

public
publish(string $fromStage, string $toStage, bool $createNewVersion = false)

Move a database record from one stage to the other.

public
migrateVersion(string $version)

Set the migrating version.

public
bool
stagesDiffer(string $stage1, string $stage2)

Compare two stages to see if they're different. Only checks the version numbers, not the actual content.

public
Versions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")

Get a list of versions for this object, optionally with additional SQL parameters

public
allVersions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")

Get a list of versions for this object, optionally with additional SQL parameters

public
compareVersions(string $from, string $to)

Compare two version, and return the differences between them.

public
string
baseTable(string $stage = null)

Return the base table - the class that directly extends DataObject.

public static 
bool
can_choose_site_stage(SS_HTTPRequest $request)

Determine if the current user is able to set the given site stage / archive

public static 
choose_site_stage(SS_HTTPRequest $request = null)

Choose the stage the site is currently on:

  • If $_GET['stage'] is set, then it will use that stage, and store it in the session.

public static 
set_reading_mode(string $mode)

Set the current reading mode.

public static 
string
get_reading_mode()

Get the current reading mode.

public static 
string
get_live_stage()

Get the name of the 'live' stage.

public static 
string
current_stage()

Get the current reading stage.

public static 
string
current_archived_date()

Get the current archive date.

public static 
reading_stage(string $stage)

Set the reading stage.

public static 
set_default_reading_mode(string $mode)

Replace default mode.

public static 
string
get_default_reading_mode()

Get default reading mode

public static 
bool
get_draft_site_secured()

Check if draft site should be secured.

public static 
set_draft_site_secured(bool $secured)

Set if the draft site should be secured or not

public static 
reading_archived_date(string $date)

Set the reading archive date.

public static 
get_one_by_stage(string $class, string $stage, string $filter = '', bool $cache = true, string $sort = '')

Get a singleton instance of a class in the given stage.

public static 
int
get_versionnumber_by_stage(string $class, string $stage, int $id, bool $cache = true)

Gets the current version number of a specific record.

public static 
prepopulate_versionnumber_cache(string $class, string $stage, array $idList = null)

Prepopulate the cache for Versioned::get_versionnumber_by_stage() for a list of record IDs, for more efficient database querying. If $idList is null, then every object will be pre-cached.

public static 
get_by_stage(string $class, string $stage, string $filter = '', string $sort = '', string $join = '', string|int $limit = '', string $containerClass = 'DataList')

Get a set of class instances by the given stage.

public
deleteFromStage(string $stage)

Delete this item from the specified stage.

public
int
writeToStage(string $stage, bool $forceInsert = false)

Write this item to the specified stage.

public
doRollbackTo(string|int $version)

Roll the draft version of this object to match the published one.

public static 
get_latest_version(string $class, string $id)

Return the latest version of the given object.

public
bool
isLatestVersion()

Returns whether the current record is the latest one.

public static 
get_including_deleted(string $class, string $filter = "", string $sort = "")

Return the equivalent of a DataList::create() call, querying the latest version of each object stored in the (class)_versions tables. In particular, this will query deleted records as well as active ones.

public static 
get_version(string $class, int $id, int $version)

Return the specific version of the given ID.

public static 
get_all_versions(string $class, int $id)

Return a list of all versions for a given id.

public
onBeforeDuplicate(DataObject $source, bool $doWrite)

Ensure version ID is reset to 0 on duplicate

public
flushCache()

Clear the cached version numbers from previous queries.

public
string
cacheKeyComponent()

Returns a piece of text to keep DataObject cache keys appropriately specific.

public
array
getVersionedStages()

Returns an array of possible stages.

public
string
getDefaultStage()

No description

public static 
array

Details

__construct(array $stages = array('Stage', 'Live'))

Construct a new Versioned object.

Parameters

array $stages

The different stages the versioned object can be. The first stage is considered the 'default' stage, the last stage is considered the 'live' stage.

static add_to_class(string $class, string $extensionClass, mixed $args = null)

Called when this extension is added to a particular class

Parameters

string $class
string $extensionClass
mixed $args

setOwner(SS_Object $owner, string $ownerBaseClass = null)

Set the owner of this extension.

Parameters

SS_Object $owner

The owner object,

string $ownerBaseClass

The base class that the extension is applied to; this may be the class of owner, or it may be a parent. For example, if Versioned was applied to SiteTree, and then a Page object was instantiated, $owner would be a Page object, but $ownerBaseClass would be 'SiteTree'.

clearOwner()

No description

SS_Object getOwner()

Returns the owner of this extension.

Return Value

SS_Object

static string get_classname_without_arguments(string $extensionStr)

Helper method to strip eval'ed arguments from a string thats passed to DataObject::$extensions or Object::add_extension().

Parameters

string $extensionStr

E.g. "Versioned('Stage','Live')"

Return Value

string

Extension classname, e.g. "Versioned"

static get_extra_config($class, $extension, $args)

No description

Parameters

$class
$extension
$args

static unload_extra_statics($class, $extension)

No description

Parameters

$class
$extension

validate(ValidationResult $validationResult)

Hook for extension-specific validation.

Parameters

ValidationResult $validationResult

Local validation result

Exceptions

ValidationException

augmentSQL(SQLQuery $query, DataQuery $dataQuery = null)

Augment the the SQLQuery that is created by the DataQuery.

Should this all go into VersionedDataQuery?

Parameters

SQLQuery $query

Query to augment.

DataQuery $dataQuery

augmentDatabase()

Update the database schema as required by this extension.

When duplicating a table's structure, remember to duplicate the create options as well. See Versioned->augmentDatabase for an example.

augmentWrite(array $manipulation)

No description

Parameters

array $manipulation

Array of operations to augment.

onBeforeWrite()

No description

onAfterWrite()

No description

onBeforeDelete()

No description

onAfterDelete()

No description

requireDefaultRecords()

No description

populateDefaults()

No description

can($member)

No description

Parameters

$member

canEdit($member)

No description

Parameters

$member

canDelete($member)

No description

Parameters

$member

canCreate($member)

No description

Parameters

$member

array extraStatics($class = null, $extension = null)

Define extra database fields

Return a map where the keys are db, has_one, etc, and the values are additional fields/relations to be defined.

Parameters

$class

since this method might be called on the class directly

$extension

since this can help to extract parameters to help set indexes

Return Value

array

Returns a map where the keys are db, has_one, etc, and the values are additional fields/relations to be defined.

updateCMSFields(FieldList $fields)

No description

Parameters

FieldList $fields

FieldList with a contained TabSet

updateFrontEndFields(FieldList $fields)

This function is used to provide modifications to the form used for front end forms. DataObject->getFrontEndFields()

Caution: Use FieldList->push() to add fields.

Parameters

FieldList $fields

FieldList without TabSet nesting

updateCMSActions(FieldList $actions)

This is used to provide modifications to the form actions used in the CMS. DataObject->getCMSActions().

Parameters

FieldList $actions FieldList

updateSummaryFields(array $fields)

this function is used to provide modifications to the summary fields in CMS by the extension By default, the summaryField() of its owner will merge more fields defined in the extension's $extra_fields['summary_fields']

Parameters

array $fields

Array of field names

updateFieldLabels(array $labels)

No description

Parameters

array $labels

Array of field labels

static reset()

Reset static configuration variables to their default values.

augmentDataQueryCreation(SQLQuery $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

Parameters

SQLQuery $query
DataQuery $dataQuery

augmentLoadLazyFields(SQLQuery $query, DataQuery $dataQuery = null, DataObject $dataObject)

For lazy loaded fields requiring extra SQL manipulation, ie versioning.

Parameters

SQLQuery $query
DataQuery $dataQuery
DataObject $dataObject

static on_db_reset()

Called by SapphireTest when the database is reset.

Reduce the coupling between this and SapphireTest, somehow.

protected augmentWriteVersioned(SQLQuery $manipulation, string $table, string|int $recordID)

Generates a ($table)_version DB manipulation and injects it into the current $manipulation

Parameters

SQLQuery $manipulation

The query to augment

string $table
string|int $recordID

protected augmentWriteStaged(array $manipulation, string $table, string|int $recordID)

Rewrite the given manipulation to update the selected (non-default) stage

Parameters

array $manipulation

Source manipulation data

string $table

Name of table

string|int $recordID

ID of record to version

int writeWithoutVersion()

Perform a write without affecting the version table.

Return Value

int

The ID of the written record

onAfterSkippedWrite()

If a write was skipped, then we need to ensure that we don't leave a migrateVersion() value lying around for the next write.

bool|null canView(Member $member = null)

Extend permissions to include additional security for objects that are not published to live.

Parameters

Member $member

Return Value

bool|null

bool canViewVersioned(Member $member = null)

Determine if there are any additional restrictions on this object for the given reading version.

Override this in a subclass to customise any additional effect that Versioned applies to canView.

This is expected to be called by canView, and thus is only responsible for denying access if the default canView would otherwise ALLOW access. Thus it should not be called in isolation as an authoritative permission check.

This has the following extension points:

  • canViewDraft is invoked if Mode = stage and Stage = stage
  • canViewArchived is invoked if Mode = archive

Parameters

Member $member

Return Value

bool

False is returned if the current viewing mode denies visibility

bool canViewStage(string $stage = 'Live', Member $member = null)

Determines canView permissions for the latest version of this object on a specific stage.

Usually the stage is read from Versioned::current_stage().

This method should be invoked by user code to check if a record is visible in the given stage.

This method should not be called via ->extend('canViewStage'), but rather should be overridden in the extended class.

Parameters

string $stage
Member $member

Return Value

bool

bool canBeVersioned(string $table)

Determine if a table supports the Versioned extensions (e.g. $table_versions does exists).

Parameters

string $table

Table name

Return Value

bool

bool hasVersionField(string $table)

Check if a certain table has the 'Version' field.

Parameters

string $table

Table name

Return Value

bool

string extendWithSuffix(string $table)

No description

Parameters

string $table

Return Value

string

bool latestPublished()

Is the latest version of the object published?

Return Value

bool

publish(string $fromStage, string $toStage, bool $createNewVersion = false)

Move a database record from one stage to the other.

Parameters

string $fromStage

Place to copy from. Can be either a stage name or a version number.

string $toStage

Place to copy to. Must be a stage name.

bool $createNewVersion

Set this to true to create a new version number. By default, the existing version number will be copied over.

migrateVersion(string $version)

Set the migrating version.

Parameters

string $version

bool stagesDiffer(string $stage1, string $stage2)

Compare two stages to see if they're different. Only checks the version numbers, not the actual content.

Parameters

string $stage1

The first stage to check

string $stage2

The second stage to check

Return Value

bool

DataList Versions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")

Get a list of versions for this object, optionally with additional SQL parameters

Parameters

string $filter
string $sort
string $limit
string $join

Deprecated, use leftJoin($table, $joinClause) instead

string $having

Return Value

DataList

DataList allVersions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")

Get a list of versions for this object, optionally with additional SQL parameters

Parameters

string $filter
string $sort
string $limit
string $join

Deprecated, use leftJoin($table, $joinClause) instead

string $having

Return Value

DataList

DataObject compareVersions(string $from, string $to)

Compare two version, and return the differences between them.

Parameters

string $from

The version to compare from

string $to

The version to compare to

Return Value

DataObject

string baseTable(string $stage = null)

Return the base table - the class that directly extends DataObject.

Parameters

string $stage

Override the stage used

Return Value

string

static bool can_choose_site_stage(SS_HTTPRequest $request)

Determine if the current user is able to set the given site stage / archive

Parameters

SS_HTTPRequest $request

Return Value

bool

static choose_site_stage(SS_HTTPRequest $request = null)

Choose the stage the site is currently on:

  • If $_GET['stage'] is set, then it will use that stage, and store it in the session.

  • If $_GET['archiveDate'] is set, it will use that date, and store it in the session.
  • If neither of these are set, it checks the session, otherwise the stage is set to 'Live'.

Parameters

SS_HTTPRequest $request

static set_reading_mode(string $mode)

Set the current reading mode.

Parameters

string $mode

static string get_reading_mode()

Get the current reading mode.

Return Value

string

static string get_live_stage()

Get the name of the 'live' stage.

Return Value

string

static string current_stage()

Get the current reading stage.

Return Value

string

static string current_archived_date()

Get the current archive date.

Return Value

string

static reading_stage(string $stage)

Set the reading stage.

Parameters

string $stage

static set_default_reading_mode(string $mode)

Replace default mode.

An non-default mode should be specified via querystring arguments.

Parameters

string $mode

static string get_default_reading_mode()

Get default reading mode

Return Value

string

static bool get_draft_site_secured()

Check if draft site should be secured.

Can be turned off if draft site unauthenticated

Return Value

bool

static set_draft_site_secured(bool $secured)

Set if the draft site should be secured or not

Parameters

bool $secured

static reading_archived_date(string $date)

Set the reading archive date.

Parameters

string $date

static DataObject get_one_by_stage(string $class, string $stage, string $filter = '', bool $cache = true, string $sort = '')

Get a singleton instance of a class in the given stage.

Parameters

string $class

The name of the class

string $stage

The name of the stage

string $filter

A filter to be inserted into the WHERE clause

bool $cache

Whether to load from the cache instead of fresh from the database

string $sort

A sort expression to be inserted into the ORDER BY clause.

Return Value

DataObject

static int get_versionnumber_by_stage(string $class, string $stage, int $id, bool $cache = true)

Gets the current version number of a specific record.

Parameters

string $class

The classname of the desired object

string $stage

The name of the stage to load from

int $id

The object's ID

bool $cache

Whether to load from the cache instead of fresh from the database

Return Value

int

static prepopulate_versionnumber_cache(string $class, string $stage, array $idList = null)

Prepopulate the cache for Versioned::get_versionnumber_by_stage() for a list of record IDs, for more efficient database querying. If $idList is null, then every object will be pre-cached.

Parameters

string $class

The object class to prepopulate version numbers for

string $stage

The stage to prepopulate version numbers from

array $idList

A whitelist of IDs to use when prepopulating

static DataList get_by_stage(string $class, string $stage, string $filter = '', string $sort = '', string $join = '', string|int $limit = '', string $containerClass = 'DataList')

Get a set of class instances by the given stage.

Parameters

string $class

The name of the class.

string $stage

The name of the stage.

string $filter

A filter to be inserted into the WHERE clause.

string $sort

A sort expression to be inserted into the ORDER BY clause.

string $join

Deprecated, use leftJoin($table, $joinClause) instead

string|int $limit

A limit on the number of records returned from the database.

string $containerClass

The container class for the result set (default is DataList)

Return Value

DataList

A modified DataList designated to the specified stage

deleteFromStage(string $stage)

Delete this item from the specified stage.

Parameters

string $stage

int writeToStage(string $stage, bool $forceInsert = false)

Write this item to the specified stage.

Parameters

string $stage

The stage to write this item to

bool $forceInsert

Whether to force an INSERT query over an UPDATE query

Return Value

int

The ID of the item being written

doRollbackTo(string|int $version)

Roll the draft version of this object to match the published one.

Caution: Doesn't overwrite the object properties with the rolled back version.

Parameters

string|int $version

Either the string 'Live' or a version number

static DataObject get_latest_version(string $class, string $id)

Return the latest version of the given object.

Parameters

string $class

The classname of the object to lookup

string $id

The object of the ID to retrieve

Return Value

DataObject

bool isLatestVersion()

Returns whether the current record is the latest one.

Performance - could do this directly via SQL.

Return Value

bool

See also

get_latest_version()
latestPublished

static get_including_deleted(string $class, string $filter = "", string $sort = "")

Return the equivalent of a DataList::create() call, querying the latest version of each object stored in the (class)_versions tables. In particular, this will query deleted records as well as active ones.

Parameters

string $class

The type of object to lookup

string $filter

An optional SQL comparison to add to the WHERE clause

string $sort

An optional SQL statement to add to the SORT clause

static DataObject get_version(string $class, int $id, int $version)

Return the specific version of the given ID.

Caution: The record is retrieved as a DataObject, but saving back modifications via write() will create a new version, rather than modifying the existing one.

Parameters

string $class

The type of object to lookup

int $id

The ID of the object to retrieve

int $version

The desired version of the object

Return Value

DataObject

static DataList get_all_versions(string $class, int $id)

Return a list of all versions for a given id.

Parameters

string $class

The type of object to lookup

int $id

The ID of the object to retrieve

Return Value

DataList

onBeforeDuplicate(DataObject $source, bool $doWrite)

Ensure version ID is reset to 0 on duplicate

Parameters

DataObject $source

Record this was duplicated from

bool $doWrite

flushCache()

Clear the cached version numbers from previous queries.

string cacheKeyComponent()

Returns a piece of text to keep DataObject cache keys appropriately specific.

Return Value

string

array getVersionedStages()

Returns an array of possible stages.

Return Value

array

string getDefaultStage()

No description

Return Value

string

static array get_template_global_variables()

No description

Return Value

array

Returns an array of items. Each key => value pair is one of three forms:

  • template name (no key)
  • template name => method name
  • template name => array(), where the array can contain these key => value pairs
    • "method" => method name
    • "casting" => casting class to use (i.e., Varchar, HTMLText, etc)