Versioned

class Versioned extends DataExtension implements TemplateGlobalProvider

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

Config options

draft_site_secured bool Default config for $is_draft_site_secured
db array
non_live_permissions array Permissions necessary to view records outside of the live stage (e.g. archive / draft stage).
use_session bool Use PHP's session storage for the "reading mode" and "unsecuredDraftSite", instead of explicitly relying on the "stage" query parameter.

Properties

$class from Extension
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.
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.
DataObject $owner
int $RecordID
int $Version
bool $WasPublished
int $AuthorID
int $PublisherID

Methods

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

Construct a new Versioned object.

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

Called when this extension is added to a particular class

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

Set the owner of this extension.

from Extension
clearOwner()

No description

from Extension
SS_Object
getOwner()

Returns the owner of this extension.

from Extension
static string
get_classname_without_arguments(string $extensionStr)

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

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

No description

from DataExtension
static 
unload_extra_statics($class, $extension)

No description

from DataExtension
validate(ValidationResult $validationResult)

Hook for extension-specific validation.

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

Augment the the SQLQuery that is created by the DataQuery.

augmentDatabase()

Update the database schema as required by this extension.

augmentWrite(array $manipulation)

No description

onBeforeWrite()

No description

from DataExtension
onAfterWrite()

No description

onBeforeDelete()

No description

from DataExtension
onAfterDelete()

No description

from DataExtension
requireDefaultRecords()

No description

from DataExtension
populateDefaults()

No description

from DataExtension
can($member)

No description

from DataExtension
canEdit($member)

No description

from DataExtension
canDelete($member)

No description

from DataExtension
canCreate($member)

No description

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

Define extra database fields

from DataExtension
updateCMSFields(FieldList $fields)

No description

updateFrontEndFields(FieldList $fields)

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

from DataExtension
updateCMSActions(FieldList $actions)

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

from DataExtension
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']

from DataExtension
updateFieldLabels(array $labels)

No description

static 
reset()

Reset static configuration variables to their default values.

augmentDataQueryCreation(SQLQuery $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

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

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

static 
on_db_reset()

Called by {@link SapphireTest} when the database is reset.

int
writeWithoutVersion()

Perform a write without affecting the version table.

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.

bool
canViewVersioned(Member $member = null)

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

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

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

bool
canBeVersioned(string $table)

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

bool
hasVersionField(string $table)

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

string
extendWithSuffix(string $table)

No description

bool
latestPublished()

Is the latest version of the object published?

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

Move a database record from one stage to the other.

migrateVersion(string $version)

Set the migrating 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.

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

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

DataObject
compareVersions(string $from, string $to)

Compare two version, and return the differences between them.

string
baseTable(string $stage = null)

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

static bool
can_choose_site_stage(SS_HTTPRequest $request)

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

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.

static 
set_reading_mode(string $mode)

Set the current reading mode.

static string
get_reading_mode()

Get the current reading mode.

static string
get_live_stage()

Get the name of the 'live' stage.

static string
current_stage()

Get the current reading stage.

static string
current_archived_date()

Get the current archive date.

static 
reading_stage(string $stage)

Set the reading stage.

static 
set_default_reading_mode(string $mode)

Replace default mode.

static string
get_default_reading_mode()

Get default reading mode

static bool
get_draft_site_secured()

Check if draft site should be secured.

static 
set_draft_site_secured(bool $secured)

Set if the draft site should be secured or not

static 
reading_archived_date(string $date)

Set the reading archive 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.

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

Gets the current version number of a specific record.

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.

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.

deleteFromStage(string $stage)

Delete this item from the specified stage.

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

Write this item to the specified stage.

doRollbackTo(string|int $version)

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

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

Return the latest version of the given object.

bool
isLatestVersion()

Returns whether the current record is the latest one.

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.

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

Return the specific version of the given ID.

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

Return a list of all versions for a given id.

onBeforeDuplicate(DataObject $source, bool $doWrite)

Ensure version ID is reset to 0 on duplicate

flushCache()

Clear the cached version numbers from previous queries.

string
cacheKeyComponent()

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

array
getVersionedStages()

Returns an array of possible stages.

string
getDefaultStage()

No description

static array
get_template_global_variables()

No description

Details

at line 217
__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.

in Extension at line 54
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

in Extension at line 66
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'.

in Extension at line 74
clearOwner()

in Extension at line 85
SS_Object getOwner()

Returns the owner of this extension.

Return Value

SS_Object

in Extension at line 97
static string get_classname_without_arguments(string $extensionStr)

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

Parameters

string $extensionStr E.g. "Versioned('Stage','Live')"

Return Value

string Extension classname, e.g. "Versioned"

in DataExtension at line 10
static get_extra_config($class, $extension, $args)

Parameters

$class
$extension
$args

in DataExtension at line 32
static unload_extra_statics($class, $extension)

Parameters

$class
$extension

in DataExtension at line 42
validate(ValidationResult $validationResult)

Hook for extension-specific validation.

Parameters

ValidationResult $validationResult Local validation result

Exceptions

ValidationException

at line 252
augmentSQL(SQLQuery $query, DataQuery $dataQuery = null)

Augment the the SQLQuery that is created by the DataQuery.

Parameters

SQLQuery $query Query to augment.
DataQuery $dataQuery

at line 442
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 {@link Versioned->augmentDatabase} for an example.

at line 720
augmentWrite(array $manipulation)

Parameters

array $manipulation Array of operations to augment.

in DataExtension at line 70
onBeforeWrite()

at line 802
onAfterWrite()

in DataExtension at line 76
onBeforeDelete()

in DataExtension at line 79
onAfterDelete()

in DataExtension at line 82
requireDefaultRecords()

in DataExtension at line 85
populateDefaults()

in DataExtension at line 88
can($member)

Parameters

$member

in DataExtension at line 91
canEdit($member)

Parameters

$member

in DataExtension at line 94
canDelete($member)

Parameters

$member

in DataExtension at line 97
canCreate($member)

Parameters

$member

in DataExtension at line 112
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.

at line 1649
updateCMSFields(FieldList $fields)

Parameters

FieldList $fields FieldList with a contained TabSet

in DataExtension at line 140
updateFrontEndFields(FieldList $fields)

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

Caution: Use {@link FieldList->push()} to add fields.

Parameters

FieldList $fields FieldList without TabSet nesting

in DataExtension at line 149
updateCMSActions(FieldList $actions)

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

Parameters

FieldList $actions FieldList

in DataExtension at line 160
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

at line 1642
updateFieldLabels(array $labels)

Parameters

array $labels Array of field labels

at line 203
static reset()

Reset static configuration variables to their default values.

at line 235
augmentDataQueryCreation(SQLQuery $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

Parameters

SQLQuery $query
DataQuery $dataQuery

at line 405
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

at line 430
static on_db_reset()

Called by {@link SapphireTest} when the database is reset.

at line 796
int writeWithoutVersion()

Perform a write without affecting the version table.

Return Value

int The ID of the written record

at line 810
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.

at line 820
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

at line 843
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

at line 894
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 {@link 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

at line 910
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

at line 922
bool hasVersionField(string $table)

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

Parameters

string $table Table name

Return Value

bool

at line 938
string extendWithSuffix(string $table)

Parameters

string $table

Return Value

string

at line 960
bool latestPublished()

Is the latest version of the object published?

Return Value

bool

at line 982
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.

at line 1042
migrateVersion(string $version)

Set the migrating version.

Parameters

string $version

at line 1053
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

at line 1084
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

at line 1098
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

at line 1150
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

at line 1165
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

at line 1185
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

at line 1217
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

at line 1275
static set_reading_mode(string $mode)

Set the current reading mode.

Parameters

string $mode

at line 1284
static string get_reading_mode()

Get the current reading mode.

Return Value

string

at line 1293
static string get_live_stage()

Get the name of the 'live' stage.

Return Value

string

at line 1302
static string current_stage()

Get the current reading stage.

Return Value

string

at line 1315
static string current_archived_date()

Get the current archive date.

Return Value

string

at line 1325
static reading_stage(string $stage)

Set the reading stage.

Parameters

string $stage

at line 1336
static set_default_reading_mode(string $mode)

Replace default mode.

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

Parameters

string $mode

at line 1345
static string get_default_reading_mode()

Get default reading mode

Return Value

string

at line 1355
static bool get_draft_site_secured()

Check if draft site should be secured.

Can be turned off if draft site unauthenticated

Return Value

bool

at line 1368
static set_draft_site_secured(bool $secured)

Set if the draft site should be secured or not

Parameters

bool $secured

at line 1377
static reading_archived_date(string $date)

Set the reading archive date.

Parameters

string $date

at line 1392
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

at line 1409
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

at line 1445
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

at line 1486
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

at line 1501
deleteFromStage(string $stage)

Delete this item from the specified stage.

Parameters

string $stage

at line 1522
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

at line 1540
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

at line 1556
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

at line 1575
bool isLatestVersion()

Returns whether the current record is the latest one.

Return Value

bool

See also

get_latest_version()
latestPublished

at line 1592
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

at line 1612
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

at line 1630
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

at line 1661
onBeforeDuplicate(DataObject $source, bool $doWrite)

Ensure version ID is reset to 0 on duplicate

Parameters

DataObject $source Record this was duplicated from
bool $doWrite

at line 1668
flushCache()

Clear the cached version numbers from previous queries.

at line 1677
string cacheKeyComponent()

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

Return Value

string

at line 1686
array getVersionedStages()

Returns an array of possible stages.

Return Value

array

at line 1693
string getDefaultStage()

Return Value

string

at line 1700
static array get_template_global_variables()

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)