class Versioned extends DataExtension implements TemplateGlobalProvider, Resettable mixin RecursivePublishable (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.

Note: This extension relies on the object also having the {\SilverStripe\Versioned\Ownership} extension applied.

Constants

DEFAULT_MODE

The default reading mode

STAGEDVERSIONED

Constructor arg to specify that staging is active on this record.

'Staging' implies that 'Versioning' is also enabled.

VERSIONED

Constructor arg to specify that versioning only is active on this record.

LIVE

The Public stage.

DRAFT

The draft (default) stage

MIGRATING_VERSION

Field used to hold the migrating version

NEXT_WRITE_WITHOUT_VERSIONED

Field used to hold flag indicating the next write should be without a new version

DELETE_WRITES_VERSION_DISABLED

Prevents delete() from creating a _Versions record (in case this must be deferred) Best used with suppressDeleteVersion()

Properties

protected T $owner

The object this extension is applied to.

from  Extension
protected string $mode

Versioning mode for this object.

protected static array $cache_versionnumber

A cache used by get_versionnumber_by_stage().

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 array $versionModifiedCache

Cache of version to modified dates for this object

protected static string $reading_mode

Current reading mode. Supports stage / archive modes.

protected static null $default_reading_mode

Default reading mode, if none set.

int $Version

Methods

public
__construct($mode = self::STAGEDVERSIONED)

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(object $owner)

Set the owner of this extension.

public
mixed
withOwner(mixed $owner, callable $callback, array $args = [])

Temporarily modify the owner. The original owner is ensured to be restored

public
clearOwner()

Clear the current owner, and restore extension to the state prior to the last setOwner()

public
T
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 that's passed to DataObject::$extensions or Object::add_extension().

public
mixed
invokeExtension(object $owner, string $method, array ...$arguments)

Invoke extension point. This will prefer explicit extend prefixed methods.

public
validate(ValidationResult $validationResult)

Hook for extension-specific validation.

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

Augment the the SQLSelect that is created by the DataQuery

public
augmentDatabase()

Update the database schema as required by this extension.

public
augmentWrite(array $manipulation)

Augment a write-record request.

public
onBeforeWrite()

Extend the owner's onBeforeWrite() logic

public
onAfterWrite()

No description

public
onBeforeDelete()

Extend the owner's onBeforeDelete() logic

public
onAfterDelete()

Extend the owner's onAfterDelete() logic

public
requireDefaultRecords()

Extend the owner's requireDefaultRecords() logic

public
populateDefaults()

Extend the owner's populateDefaults() logic

public
onAfterBuild()

Extend the owner's onAfterBuild() logic

public
bool|null
can(Member $member)

Influence the owner's can() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

public
bool|null
canEdit(Member $member)

Influence the owner's canEdit() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

public
bool|null
canDelete(Member $member)

Influence the owner's canDelete() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

public
bool|null
canCreate(Member $member)

Influence the owner's canCreate() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

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

Define extra database fields

public
updateCMSFields(FieldList $fields)

No description

public
void
updateCMSCompositeValidator(CompositeValidator $compositeValidator)

This function is used to provide modifications to the Validators used on a DataObject.

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(SQLSelect $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

public
getAtVersion(int|string|null $from)

Get this record at a specific version

protected
array
getLastEditedAndStageForVersion(int $version)

Get modified date and stage for the given version

public
updateInheritableQueryParams(array $params)

Updates query parameters of relations attached to versioned dataobjects

protected
augmentSQLStage(SQLSelect $query, DataQuery $dataQuery)

Reading a specific stage (Stage or Live)

protected
augmentSQLStageUnique(SQLSelect $query, DataQuery $dataQuery)

Reading a specific stage, but only return items that aren't in any other stage

protected
augmentSQLVersioned(SQLSelect $query, bool $filterDeleted = true)

Augment SQL to select from _Versions table instead.

protected
prepareMaxVersionSubSelect(SQLSelect $baseQuery, DataQuery $dataQuery)

Prepare a sub-select for determining latest versions of records on the base table. This is used as either an inner join or sub-select on the base query

protected
shouldApplySubSelectAsCondition(SQLSelect $baseQuery)

Indicates if a subquery filtering versioned records should apply as a condition instead of an inner join

protected
augmentSQLVersionedArchive(SQLSelect $query, DataQuery $dataQuery)

Filter the versioned history by a specific date and archive stage

protected
augmentSQLVersionedLatestSingle(SQLSelect $query, DataQuery $dataQuery)

Return latest version instance, regardless of whether it is on a particular stage.

protected
augmentSQLVersionedLatest(SQLSelect $query, DataQuery $dataQuery)

Return latest version instances, regardless of whether they are on a particular stage.

protected
augmentSQLVersionedVersion(SQLSelect $query, DataQuery $dataQuery)

If selecting a specific version, filter it here

protected
augmentSQLVersionedAll(SQLSelect $query)

If all versions are requested, ensure that records are sorted by this field

protected
bool
isTableVersioned(string $table)

Determine if the given versioned table is a part of the sub-tree of the current dataobject This helps prevent rewriting of other tables that get joined in, in particular, many_many tables

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

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

protected
cleanupVersionedOrphans(string $baseTable, string $childTable)

Cleanup orphaned records in the _Versions table

protected
augmentWriteVersioned(array $manipulation, string $class, string $table, int $recordID, array|string $stages, bool $isDelete = false)

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

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

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

protected
createDeletedVersion(string[]|string $stages = [])

Adds a WasDeleted=1 version entry for this record, and records any stages the deletion applies to

public
int
writeWithoutVersion()

Perform a write without affecting the version table.

public
bool
getNextWriteWithoutVersion()

Check if next write is without version

public
setNextWriteWithoutVersion(bool $flag)

Set if next write should be without version or not

public
bool
getDeleteWritesVersion()

Check if delete() should write _Version rows or not

public
setDeleteWritesVersion(bool $flag)

Set if delete() should write _Version rows

protected
mixed
suppressDeletedVersion(callable $callback)

Helper method to safely suppress delete callback

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
canPublish(Member $member = null)

This function should return true if the current user can publish this record.

protected
extendCanPublish()

No description

public
mixed
canUnpublish(null $member = null)

Check if the current user can delete this record from live

protected
extendCanUnpublish()

No description

public
bool
canArchive(Member $member = null)

Check if the current user is allowed to archive this record.

protected
extendCanArchive()

No description

public
bool
canRevertToLive(Member $member = null)

Check if the user can revert this record to live

protected
extendCanRevertToLive()

No description

public
bool
canRestoreToDraft(Member $member = null)

Check if the user can restore this record to draft

protected
extendcanRestoreToDraft()

No description

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 = self::LIVE, Member $member = null)

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

public
bool
canBeVersioned(string $class)

Determine if a class is supporting the Versioned extensions (e.g.

public
bool
hasVersionField(string $table)

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

public
string
extendWithSuffix(string $table)

No description

public
bool
latestPublished()

Determines if the current draft version is the same as live or rather, that there are no outstanding draft changes

public
bool
publishSingle()

Publishes this object to Live, but doesn't publish owned objects.

public
bool
doArchive()

Removes the record from both live and stage

public
bool
doUnpublish()

Removes this record from the live site

public
bool
hasPublishedOwners()

Determine if this object is published, and has any published owners.

public
bool
doRevertToLive()

Revert the draft changes: replace the draft content with the content on live

public
copyVersionToStage(int|string|null $fromStage, string $toStage)

Move a database record from one stage to the other.

public
int|null
getMigratingVersion()

Get version migrated to

public
setMigratingVersion(string $version)

Set the migrating version.

public
bool
stagesDiffer()

Compare two stages to see if they're different.

public
bool
stagesDifferRecursive()

Determine if content differs on stages including nested objects 'owns' configuration drives the relationship traversal

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

No description

public
compareVersions(string $from, string $to)

Compare two version, and return the diff between them.

protected
string
baseTable(string $stage = null)

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

public
string
stageTable(string $table, string $stage)

Given a table and stage determine the table name.

public static 
bool
can_choose_site_stage(HTTPRequest $request)

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

public static 
choose_site_stage(HTTPRequest $request)

Choose the stage the site is currently on.

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_stage()

Get the current reading stage.

public static 
string
current_archived_date()

Get the current archive date.

public static 
string
current_archived_stage()

Get the current archive stage.

public static 
set_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, string $stage = self::DRAFT)

Set the reading archive date.

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

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

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

Gets the current version number of a specific record.

public
onPrepopulateTreeDataCache(DataList|array $recordList = null, array $options = [])

Hook into Hierarchy::prepopulateTreeDataCache.

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

Pre-populate 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 record will be pre-cached.

public static 
T>
get_by_stage(T> $class, string $stage, string $filter = '', string $sort = '', string $join = '', int $limit = null, string $containerClass = DataList::class)

Get a set of class instances by the given stage.

public
deleteFromStage(string $stage)

Delete this record from the given stage

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

Write the given record to the given stage.

public
rollbackRecursive(int|string|null $version = null)

Recursively rollback draft to the given version. This will also rollback any owned objects at that point in time to the same date. Objects which didn't exist (or weren't attached) to the record at the target point in time will be "unlinked", which dis-associates the record without requiring a hard deletion.

public
rollbackSingle(int|string|null $version)

Rollback draft to a given version

public static 
get_latest_version(T> $class, int $id)

Return the latest version of the given record.

public
bool
isLatestVersion()

Returns whether the current record is the latest one.

public
bool
isLiveVersion()

Returns whether the current record's version is the current live/published version

public
bool
isLatestDraftVersion()

Returns whether the current record's version is the current draft/modified version

public
bool
isPublished()

Check if this record exists on live On objects with only 1 stage, check if the record exists on that stage.

public
bool
isArchived()

Check if page doesn't exist on any stage, but used to be

public
bool
isOnDraft()

Check if this record exists on the draft stage.

public
bool
isOnLiveOnly()

Compares current draft with live version, and returns true if no draft version of this page exists but the page is still published (eg, after triggering "Delete from draft site" in the CMS).

public
bool
isOnDraftOnly()

Compares current draft with live version, and returns true if no live version exists, meaning the page was never published.

public
bool
isModifiedOnDraft()

Compares current draft with live version, and returns true if these versions differ, meaning there have been unpublished changes to the draft site.

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

Return the equivalent of a DataList::create() call, querying the latest version of each record stored in the (class)_Versions tables.

public static 
get_version(T> $class, int $id, int $version)

Return the specific version of the given id.

public static 
T>
get_all_versions(T> $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()

No description

public
string
cacheKeyComponent()

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

public
array
getVersionedStages()

Returns an array of possible stages.

public static 
array
get_template_global_variables()

Called by SSViewer to get a list of global variables to expose to the template, the static method to call on this class to get the value for those variables, and the class to use for casting the returned value for use in a template

public
bool
hasStages()

Check if this object has stages

public static 
mixed
withVersionedMode(callable $callback)

Invoke a callback which may modify reading mode, but ensures this mode is restored after completion, without modifying global state.

public
Member|null
Author()

Get author of this record.

public
Member|null
Publisher()

Get publisher of this record.

Details

__construct($mode = self::STAGEDVERSIONED)

Construct a new Versioned object.

Parameters

$mode

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(object $owner)

Set the owner of this extension.

Parameters

object $owner

The owner object

mixed withOwner(mixed $owner, callable $callback, array $args = [])

Temporarily modify the owner. The original owner is ensured to be restored

Parameters

mixed $owner

Owner to set

callable $callback

Callback to invoke

array $args

Args to pass to callback

Return Value

mixed

clearOwner()

Clear the current owner, and restore extension to the state prior to the last setOwner()

T getOwner()

Returns the owner of this extension.

Return Value

T

static string get_classname_without_arguments(string $extensionStr)

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

Parameters

string $extensionStr

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

Return Value

string

Extension classname, e.g. "Versioned"

mixed invokeExtension(object $owner, string $method, array ...$arguments)

Invoke extension point. This will prefer explicit extend prefixed methods.

Parameters

object $owner
string $method
array ...$arguments

Return Value

mixed

validate(ValidationResult $validationResult)

Hook for extension-specific validation.

Parameters

ValidationResult $validationResult

Local validation result

Exceptions

ValidationException

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

Augment the the SQLSelect that is created by the DataQuery

See {\SilverStripe\Versioned\augmentLazyLoadFields} for lazy-loading applied prior to this.

Parameters

SQLSelect $query

Query to augment.

DataQuery $dataQuery

Container DataQuery for this SQLSelect

Exceptions

InvalidArgumentException

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)

Augment a write-record request.

Parameters

array $manipulation

Array of operations to augment.

onBeforeWrite()

Extend the owner's onBeforeWrite() logic

See DataObject::onBeforeWrite() for context.

onAfterWrite()

No description

onBeforeDelete()

Extend the owner's onBeforeDelete() logic

See DataObject::onBeforeDelete() for context.

onAfterDelete()

Extend the owner's onAfterDelete() logic

See DataObject::onAfterDelete() for context.

requireDefaultRecords()

Extend the owner's requireDefaultRecords() logic

See DataObject::requireDefaultRecords() for context.

populateDefaults()

Extend the owner's populateDefaults() logic

See DataObject::populateDefaults() for context.

onAfterBuild()

Extend the owner's onAfterBuild() logic

See DataObject::onAfterBuild() for context.

bool|null can(Member $member)

Influence the owner's can() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

See DataObject::can()} and {@link DataObject::extendedCan() for context.

Parameters

Member $member

Return Value

bool|null

bool|null canEdit(Member $member)

Influence the owner's canEdit() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

See DataObject::canEdit()} and {@link DataObject::extendedCan() for context.

Parameters

Member $member

Return Value

bool|null

bool|null canDelete(Member $member)

Influence the owner's canDelete() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

See DataObject::canDelete()} and {@link DataObject::extendedCan() for context.

Parameters

Member $member

Return Value

bool|null

bool|null canCreate(Member $member)

Influence the owner's canCreate() permission check value to be disallowed (false), allowed (true) if no other processed results are to disallow, or open (null) to not affect the outcome.

See DataObject::canCreate()} and {@link DataObject::extendedCan() for context.

Parameters

Member $member

Return Value

bool|null

array extraStatics(string $class = null, string $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

string $class

since this method might be called on the class directly

string $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

void updateCMSCompositeValidator(CompositeValidator $compositeValidator)

This function is used to provide modifications to the Validators used on a DataObject.

Caution: Use CompositeValidator->addValidator() to add Validators.

Parameters

CompositeValidator $compositeValidator

Return Value

void

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(SQLSelect $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

Parameters

SQLSelect $query
DataQuery $dataQuery

Versioned|DataObject getAtVersion(int|string|null $from)

Get this record at a specific version

Parameters

int|string|null $from

Version or stage to get at. Null mean returns self object

Return Value

Versioned|DataObject

protected array getLastEditedAndStageForVersion(int $version)

Get modified date and stage for the given version

Parameters

int $version

Return Value

array

A list containing 0 => LastEdited, 1 => Stage

updateInheritableQueryParams(array $params)

Updates query parameters of relations attached to versioned dataobjects

Parameters

array $params

protected augmentSQLStage(SQLSelect $query, DataQuery $dataQuery)

Reading a specific stage (Stage or Live)

Parameters

SQLSelect $query
DataQuery $dataQuery

protected augmentSQLStageUnique(SQLSelect $query, DataQuery $dataQuery)

Reading a specific stage, but only return items that aren't in any other stage

Parameters

SQLSelect $query
DataQuery $dataQuery

protected augmentSQLVersioned(SQLSelect $query, bool $filterDeleted = true)

Augment SQL to select from _Versions table instead.

Parameters

SQLSelect $query
bool $filterDeleted

Whether to exclude deleted entries or not

protected SQLSelect prepareMaxVersionSubSelect(SQLSelect $baseQuery, DataQuery $dataQuery)

Prepare a sub-select for determining latest versions of records on the base table. This is used as either an inner join or sub-select on the base query

Parameters

SQLSelect $baseQuery
DataQuery $dataQuery

Return Value

SQLSelect

protected shouldApplySubSelectAsCondition(SQLSelect $baseQuery)

Indicates if a subquery filtering versioned records should apply as a condition instead of an inner join

Parameters

SQLSelect $baseQuery

protected augmentSQLVersionedArchive(SQLSelect $query, DataQuery $dataQuery)

Filter the versioned history by a specific date and archive stage

Parameters

SQLSelect $query
DataQuery $dataQuery

protected augmentSQLVersionedLatestSingle(SQLSelect $query, DataQuery $dataQuery)

Return latest version instance, regardless of whether it is on a particular stage.

This is similar to augmentSQLVersionedLatest() below, except it only returns a single value selected by Versioned.id

Parameters

SQLSelect $query
DataQuery $dataQuery

protected augmentSQLVersionedLatest(SQLSelect $query, DataQuery $dataQuery)

Return latest version instances, regardless of whether they are on a particular stage.

This provides "show all, including deleted" functionality.

Note: latest_version ignores deleted versions, and will select the latest non-deleted version.

Parameters

SQLSelect $query
DataQuery $dataQuery

protected augmentSQLVersionedVersion(SQLSelect $query, DataQuery $dataQuery)

If selecting a specific version, filter it here

Parameters

SQLSelect $query
DataQuery $dataQuery

protected augmentSQLVersionedAll(SQLSelect $query)

If all versions are requested, ensure that records are sorted by this field

Parameters

SQLSelect $query

protected bool isTableVersioned(string $table)

Determine if the given versioned table is a part of the sub-tree of the current dataobject This helps prevent rewriting of other tables that get joined in, in particular, many_many tables

Parameters

string $table

Return Value

bool

True if this table should be versioned

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

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

Parameters

SQLSelect $query
DataQuery $dataQuery
DataObject $dataObject

protected cleanupVersionedOrphans(string $baseTable, string $childTable)

Cleanup orphaned records in the _Versions table

Parameters

string $baseTable

base table to use as authoritative source of records

string $childTable

Sub-table to clean orphans from

protected augmentWriteVersioned(array $manipulation, string $class, string $table, int $recordID, array|string $stages, bool $isDelete = false)

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

Parameters

array $manipulation

Source manipulation data

string $class Class
string $table

Table Table for this class

int $recordID

ID of record to version

array|string $stages

Stage or array of affected stages

bool $isDelete

Set to true of version is created from a deletion

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

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

Parameters

array $manipulation

Source manipulation data

string $table

Name of table

int $recordID

ID of record to version

protected createDeletedVersion(string[]|string $stages = [])

Adds a WasDeleted=1 version entry for this record, and records any stages the deletion applies to

Parameters

string[]|string $stages

Stage or array of affected stages

int writeWithoutVersion()

Perform a write without affecting the version table.

Return Value

int

The ID of the record

bool getNextWriteWithoutVersion()

Check if next write is without version

Return Value

bool

DataObject setNextWriteWithoutVersion(bool $flag)

Set if next write should be without version or not

Parameters

bool $flag

Return Value

DataObject owner

bool getDeleteWritesVersion()

Check if delete() should write _Version rows or not

Return Value

bool

DataObject setDeleteWritesVersion(bool $flag)

Set if delete() should write _Version rows

Parameters

bool $flag

Return Value

DataObject owner

protected mixed suppressDeletedVersion(callable $callback)

Helper method to safely suppress delete callback

Parameters

callable $callback

Return Value

mixed

Result of $callback()

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 canPublish(Member $member = null)

This function should return true if the current user can publish this record.

It can be overloaded to customise the security model for an application.

Denies permission if any of the following conditions is true:

  • canPublish() on any extension returns false
  • canEdit() returns false

Parameters

Member $member

Return Value

bool

True if the current user can publish this record.

protected extendCanPublish()

No description

mixed canUnpublish(null $member = null)

Check if the current user can delete this record from live

Parameters

null $member

Return Value

mixed

protected extendCanUnpublish()

No description

bool canArchive(Member $member = null)

Check if the current user is allowed to archive this record.

If extended, ensure that both canDelete and canUnpublish are extended also

Parameters

Member $member

Return Value

bool

protected extendCanArchive()

No description

bool canRevertToLive(Member $member = null)

Check if the user can revert this record to live

Parameters

Member $member

Return Value

bool

protected extendCanRevertToLive()

No description

bool canRestoreToDraft(Member $member = null)

Check if the user can restore this record to draft

Parameters

Member $member

Return Value

bool

protected extendcanRestoreToDraft()

No description

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 = self::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 $class)

Determine if a class is supporting the Versioned extensions (e.g.

$table_Versions does exists).

Parameters

string $class

Class 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

Returns false if the field isn't in the table, true otherwise

string extendWithSuffix(string $table)

No description

Parameters

string $table

Return Value

string

bool latestPublished()

Determines if the current draft version is the same as live or rather, that there are no outstanding draft changes

Return Value

bool

bool publishSingle()

Publishes this object to Live, but doesn't publish owned objects.

User code should call {\SilverStripe\Versioned\canPublish()} prior to invoking this method.

Return Value

bool

True if publish was successful

bool doArchive()

Removes the record from both live and stage

User code should call {\SilverStripe\Versioned\canArchive()} prior to invoking this method.

Return Value

bool Success

bool doUnpublish()

Removes this record from the live site

User code should call {\SilverStripe\Versioned\canUnpublish()} prior to invoking this method.

Return Value

bool

Flag whether the unpublish was successful

bool hasPublishedOwners()

Determine if this object is published, and has any published owners.

If this is true, a warning should be shown before this is published.

Note: This method returns false if the object itself is unpublished, since owners are only considered on the same stage as the record itself.

Return Value

bool

bool doRevertToLive()

Revert the draft changes: replace the draft content with the content on live

User code should call {\SilverStripe\Versioned\canRevertToLive()} prior to invoking this method.

Return Value

bool

True if the revert was successful

copyVersionToStage(int|string|null $fromStage, string $toStage)

Move a database record from one stage to the other.

Parameters

int|string|null $fromStage

Place to copy from. Can be either a stage name or a version number. Null copies current object to stage

string $toStage

Place to copy to. Must be a stage name.

int|null getMigratingVersion()

Get version migrated to

Return Value

int|null

DataObject setMigratingVersion(string $version)

Set the migrating version.

Parameters

string $version

The version.

Return Value

DataObject Owner

bool stagesDiffer()

Compare two stages to see if they're different.

Only checks the version numbers, not the actual content.

Return Value

bool

bool stagesDifferRecursive()

Determine if content differs on stages including nested objects 'owns' configuration drives the relationship traversal

Return Value

bool

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

No description

Parameters

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

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

string $having

@deprecated 2.2.0 The $having parameter does nothing and will be removed without equivalent functionality to replace it

Return Value

Versioned_Version>

DataObject compareVersions(string $from, string $to)

Compare two version, and return the diff between them.

Parameters

string $from

The version to compare from.

string $to

The version to compare to.

Return Value

DataObject

protected string baseTable(string $stage = null)

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

Protected so it doesn't conflict with DataObject::baseTable()

Parameters

string $stage

Return Value

string

string stageTable(string $table, string $stage)

Given a table and stage determine the table name.

Note: Stages this asset does not exist in will default to the draft table.

Parameters

string $table

Main table

string $stage

Return Value

string

Staged table name

static bool can_choose_site_stage(HTTPRequest $request)

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

Parameters

HTTPRequest $request

Return Value

bool

static choose_site_stage(HTTPRequest $request)

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

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_stage()

Get the current reading stage.

Return Value

string

static string current_archived_date()

Get the current archive date.

Return Value

string

static string current_archived_stage()

Get the current archive stage.

Return Value

string

static set_stage(string $stage)

Set the reading stage.

Parameters

string $stage

New reading stage.

Exceptions

InvalidArgumentException

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, string $stage = self::DRAFT)

Set the reading archive date.

Parameters

string $date

New reading archived date.

string $stage

Set stage

static T&Versioned get_one_by_stage(T> $class, string $stage, string $filter = '', bool $cache = true, string $sort = '')

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

Parameters

T> $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

Use caching.

string $sort

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

Return Value

T&Versioned

static int|null 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

Class to search

string $stage

Stage name

int $id

ID of the record

bool $cache

Set to true to turn on cache

Return Value

int|null

Return the version number, or null if not on this stage

onPrepopulateTreeDataCache(DataList|array $recordList = null, array $options = [])

Hook into Hierarchy::prepopulateTreeDataCache.

Parameters

DataList|array $recordList

The list of records to prepopulate caches for. Null for all records.

array $options

A map of hints about what should be cached. "numChildrenMethod" and "childrenMethod" are allowed keys.

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

Pre-populate 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 record will be pre-cached.

Parameters

string $class
string $stage
array $idList

static T> get_by_stage(T> $class, string $stage, string $filter = '', string $sort = '', string $join = '', int $limit = null, string $containerClass = DataList::class)

Get a set of class instances by the given stage.

Parameters

T> $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

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

T>

A modified DataList designated to the specified stage

deleteFromStage(string $stage)

Delete this record from the given stage

Parameters

string $stage

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

Write the given record to the given stage.

Note: If writing to live, this will write to stage as well.

Parameters

string $stage
bool $forceInsert

Return Value

int

The ID of the record

DataObject|Versioned rollbackRecursive(int|string|null $version = null)

Recursively rollback draft to the given version. This will also rollback any owned objects at that point in time to the same date. Objects which didn't exist (or weren't attached) to the record at the target point in time will be "unlinked", which dis-associates the record without requiring a hard deletion.

Parameters

int|string|null $version

Version ID or Versioned::LIVE to rollback from live. Pass in null to rollback to the current object

Return Value

DataObject|Versioned

The object rolled back

rollbackSingle(int|string|null $version)

Rollback draft to a given version

Parameters

int|string|null $version

Version ID or Versioned::LIVE to rollback from live. Null to rollback current owner object.

static T&Versioned get_latest_version(T> $class, int $id)

Return the latest version of the given record.

Parameters

T> $class
int $id

Return Value

T&Versioned

bool isLatestVersion()

Returns whether the current record is the latest one.

Return Value

bool

See also

get_latest_version()
latestPublished

bool isLiveVersion()

Returns whether the current record's version is the current live/published version

Return Value

bool

bool isLatestDraftVersion()

Returns whether the current record's version is the current draft/modified version

Return Value

bool

bool isPublished()

Check if this record exists on live On objects with only 1 stage, check if the record exists on that stage.

Return Value

bool

bool isArchived()

Check if page doesn't exist on any stage, but used to be

Return Value

bool

bool isOnDraft()

Check if this record exists on the draft stage.

On objects with only 1 stage, check if the record exists on that stage.

Return Value

bool

bool isOnLiveOnly()

Compares current draft with live version, and returns true if no draft version of this page exists but the page is still published (eg, after triggering "Delete from draft site" in the CMS).

Return Value

bool

bool isOnDraftOnly()

Compares current draft with live version, and returns true if no live version exists, meaning the page was never published.

Return Value

bool

bool isModifiedOnDraft()

Compares current draft with live version, and returns true if these versions differ, meaning there have been unpublished changes to the draft site.

Return Value

bool

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

Return the equivalent of a DataList::create() call, querying the latest version of each record stored in the (class)_Versions tables.

In particular, this will query deleted records as well as active ones.

Parameters

T> $class
string $filter
string $sort

Return Value

T>

static T&Versioned get_version(T> $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

T> $class
int $id
int $version

Return Value

T&Versioned

static T> get_all_versions(T> $class, int $id)

Return a list of all versions for a given id.

Parameters

T> $class
int $id

Return Value

T>

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()

No description

string cacheKeyComponent()

Return 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

static array get_template_global_variables()

Called by SSViewer to get a list of global variables to expose to the template, the static method to call on this class to get the value for those variables, and the class to use for casting the returned value for use in a template

If the method to call is not included for a particular template variable, a method named the same as the template variable will be called

If the casting class is not specified for a particular template variable, ViewableData::$default_cast is used

The first letter of the template variable is case-insensitive. However the method name is always case sensitive.

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 => [], where the array can contain these key => value pairs
    • "method" => method name
    • "casting" => casting class to use (i.e., Varchar, HTMLFragment, etc)

bool hasStages()

Check if this object has stages

Return Value

bool

True if this object is staged

static mixed withVersionedMode(callable $callback)

Invoke a callback which may modify reading mode, but ensures this mode is restored after completion, without modifying global state.

The desired reading mode should be set by the callback directly

Parameters

callable $callback

Return Value

mixed

Result of $callback

Member|null Author()

Get author of this record.

Note: Only works on records selected via Versions()

Return Value

Member|null

Member|null Publisher()

Get publisher of this record.

Note: Only works on records selected via Versions()

Return Value

Member|null