class Versioned extends DataExtension implements TemplateGlobalProvider, Resettable

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

Config options

draft_site_secured bool Default config for $is_draft_site_secured
non_virtual_fields array Ensure versioned page doesn't attempt to virtualise these non-db fields
casting array Ensure versioned records cast extra fields properly
db array
prepopulate_versionnumber_cache boolean Used to enable or disable the prepopulation of the version number cache.
use_conditions_over_inner_joins bool Indicates whether augmentSQL operations should add subselects as WHERE conditions instead of INNER JOIN intersections. Performance of the INNER JOIN scales on the size of _Versions tables where as the condition scales on the number of records being returned from the base query.
versionableExtensions array 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 '_'.
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

DataObject|RecursivePublishable|Versioned $owner
int $Version

Methods

__construct($mode = self::STAGEDVERSIONED)

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

Set the owner of this extension.

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

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

from Extension
clearOwner()

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

from Extension
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 that's passed to {@link DataObject::$extensions} or {@link Object::add_extension()}.

from Extension
static 
unload_extra_statics($class, $extension)

No description

validate(ValidationResult $validationResult)

Hook for extension-specific validation.

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

Augment the the SQLSelect that is created by the DataQuery

augmentDatabase()

Update the database schema as required by this extension.

augmentWrite(array $manipulation)

Augment a write-record request.

onBeforeWrite()

No description

onAfterWrite()

No description

onBeforeDelete()

No description

onAfterDelete()

No description

requireDefaultRecords()

No description

populateDefaults()

No description

can($member)

No description

canEdit($member)

No description

canDelete($member)

No description

canCreate($member)

No description

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

Define extra database fields

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

updateCMSActions(FieldList $actions)

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

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

updateFieldLabels(array $labels)

No description

static 
reset()

Reset static configuration variables to their default values.

augmentDataQueryCreation(SQLSelect $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

getAtVersion(int|string|null $from)

Get this record at a specific version

updateInheritableQueryParams(array $params)

Updates query parameters of relations attached to versioned dataobjects

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

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

int
writeWithoutVersion()

Perform a write without affecting the version table.

bool
getNextWriteWithoutVersion()

Check if next write is without version

setNextWriteWithoutVersion(bool $flag)

Set if next write should be without version or not

bool
getDeleteWritesVersion()

Check if delete() should write _Version rows or not

setDeleteWritesVersion(bool $flag)

Set if delete() should write _Version rows

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.

mixed
canUnpublish(null $member = null)

Check if the current user can delete this record from live

bool
canArchive(Member $member = null)

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

bool
canRevertToLive(Member $member = null)

Check if the user can revert this record to live

bool
canRestoreToDraft(Member $member = null)

Check if the user can restore this record to draft

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

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

boolean
canBeVersioned(string $class)

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

boolean
hasVersionField(string $table)

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

string
extendWithSuffix(string $table)

No description

bool
latestPublished()

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

doPublish() deprecated

No description

bool
publishSingle()

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

bool
doArchive()

Removes the record from both live and stage

bool
doUnpublish()

Removes this record from the live site

bool
hasPublishedOwners()

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

bool
doRevertToLive()

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

onAfterRevertToLive() deprecated

No description

publish($fromStage, $toStage, $createNewVersion = true) deprecated

No description

copyVersionToStage(int|string|null $fromStage, string $toStage, bool $createNewVersion = true)

Move a database record from one stage to the other.

int|null
getMigratingVersion()

Get version migrated to

migrateVersion(string $version) deprecated

No description

setMigratingVersion(string $version)

Set the migrating version.

bool
stagesDiffer()

Compare two stages to see if they're different.

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

No description

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

Return a list of all the versions available.

compareVersions(string $from, string $to)

Compare two version, and return the diff between them.

string
stageTable(string $table, string $stage)

Given a table and stage determine the table name.

static bool
can_choose_site_stage(HTTPRequest $request)

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

static 
choose_site_stage(HTTPRequest $request)

Choose the stage the site is currently on.

static 
set_reading_mode(string $mode)

Set the current reading mode.

static string
get_reading_mode()

Get the current reading mode.

static string
get_stage()

Get the current reading stage.

static string
current_archived_date()

Get the current archive date.

static string
current_archived_stage()

Get the current archive stage.

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

Set the reading archive date.

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

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

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.

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

Hook into {@link Hierarchy::prepopulateTreeDataCache}.

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.

static DataList
get_by_stage(string $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.

deleteFromStage(string $stage)

Delete this record from the given stage

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

Write the given record to the given stage.

doRollbackTo(int $version) deprecated

Roll the draft version of this record to match the published record.

onAfterRollback() deprecated

No description

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.

rollbackSingle(int|string|null $version)

Rollback draft to a given version

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

Return the latest version of the given record.

boolean
isLatestVersion()

Returns whether the current record is the latest one.

bool
isLiveVersion()

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

bool
isLatestDraftVersion()

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

bool
isPublished()

Check if this record exists on live

bool
isArchived()

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

bool
isOnDraft()

Check if this record exists on the draft stage

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

bool
isOnDraftOnly()

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

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.

static DataList
get_including_deleted(string $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.

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

No description

string
cacheKeyComponent()

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

array
getVersionedStages()

Returns an array of possible stages.

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

bool
hasStages()

Check if this object has stages

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.

Member|null
Author()

Get author of this record.

Member|null
Publisher()

Get publisher of this record.

Details

at line 330
__construct($mode = self::STAGEDVERSIONED)

Construct a new Versioned object.

Parameters

$mode

in Extension at line 50
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 60
setOwner(object $owner)

Set the owner of this extension.

Parameters

object $owner The owner object

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

in Extension at line 87
clearOwner()

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

in Extension at line 100
Object getOwner()

Returns the owner of this extension.

Return Value

Object

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

Helper method to strip eval'ed arguments from a string that's 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 19
static unload_extra_statics($class, $extension)

Parameters

$class
$extension

in DataExtension at line 30
validate(ValidationResult $validationResult)

Hook for extension-specific validation.

Parameters

ValidationResult $validationResult Local validation result

Exceptions

ValidationException

at line 484
augmentSQL(SQLSelect $query, DataQuery $dataQuery = null)

Augment the the SQLSelect that is created by the DataQuery

See {see augmentLazyLoadFields} for lazy-loading applied prior to this.

Parameters

SQLSelect $query Query to augment.
DataQuery $dataQuery Container DataQuery for this SQLSelect

Exceptions

InvalidArgumentException

at line 940
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 1280
augmentWrite(array $manipulation)

Augment a write-record request.

Parameters

array $manipulation Array of operations to augment.

in DataExtension at line 63
onBeforeWrite()

at line 1369
onAfterWrite()

in DataExtension at line 71
onBeforeDelete()

at line 1903
onAfterDelete()

in DataExtension at line 79
requireDefaultRecords()

in DataExtension at line 83
populateDefaults()

in DataExtension at line 87
can($member)

Parameters

$member

in DataExtension at line 91
canEdit($member)

Parameters

$member

in DataExtension at line 95
canDelete($member)

Parameters

$member

in DataExtension at line 99
canCreate($member)

Parameters

$member

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

at line 2938
updateCMSFields(FieldList $fields)

Parameters

FieldList $fields FieldList with a contained TabSet

in DataExtension at line 144
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 154
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 166
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 2930
updateFieldLabels(array $labels)

Parameters

array $labels Array of field labels

at line 301
static reset()

Reset static configuration variables to their default values.

at line 314
augmentDataQueryCreation(SQLSelect $query, DataQuery $dataQuery)

Amend freshly created DataQuery objects with versioned-specific information.

Parameters

SQLSelect $query
DataQuery $dataQuery

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

at line 434
updateInheritableQueryParams(array $params)

Updates query parameters of relations attached to versioned dataobjects

Parameters

array $params

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

at line 1359
int writeWithoutVersion()

Perform a write without affecting the version table.

Return Value

int The ID of the record

at line 1379
bool getNextWriteWithoutVersion()

Check if next write is without version

Return Value

bool

at line 1390
DataObject setNextWriteWithoutVersion(bool $flag)

Set if next write should be without version or not

Parameters

bool $flag

Return Value

DataObject owner

at line 1400
bool getDeleteWritesVersion()

Check if delete() should write _Version rows or not

Return Value

bool

at line 1411
DataObject setDeleteWritesVersion(bool $flag)

Set if delete() should write _Version rows

Parameters

bool $flag

Return Value

DataObject owner

at line 1437
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 1453
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.

at line 1485
mixed canUnpublish(null $member = null)

Check if the current user can delete this record from live

Parameters

null $member

Return Value

mixed

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

at line 1560
bool canRevertToLive(Member $member = null)

Check if the user can revert this record to live

Parameters

Member $member

Return Value

bool

at line 1598
bool canRestoreToDraft(Member $member = null)

Check if the user can restore this record to draft

Parameters

Member $member

Return Value

bool

at line 1631
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 1656
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 1722
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 {@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 1741
boolean 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

boolean

at line 1755
boolean hasVersionField(string $table)

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

Parameters

string $table Table name

Return Value

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

at line 1767
string extendWithSuffix(string $table)

Parameters

string $table

Return Value

string

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

at line 1812
doPublish() deprecated

deprecated 4.0..5.0

at line 1825
bool publishSingle()

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

User code should call {see canPublish()} prior to invoking this method.

Return Value

bool True if publish was successful

at line 1849
bool doArchive()

Removes the record from both live and stage

User code should call {see canArchive()} prior to invoking this method.

Return Value

bool Success

at line 1875
bool doUnpublish()

Removes this record from the live site

User code should call {see canUnpublish()} prior to invoking this method.

Return Value

bool Flag whether the unpublish was successful

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

at line 1936
bool doRevertToLive()

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

User code should call {see canRevertToLive()} prior to invoking this method.

Return Value

bool True if the revert was successful

at line 1948
onAfterRevertToLive() deprecated

deprecated 1.2..2.0 This extension method is redundant and will be removed

at line 1955
publish($fromStage, $toStage, $createNewVersion = true) deprecated

deprecated 4.0..5.0

Parameters

$fromStage
$toStage
$createNewVersion

at line 1970
copyVersionToStage(int|string|null $fromStage, string $toStage, bool $createNewVersion = true)

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.
bool $createNewVersion [DEPRECATED] This parameter is ignored, as copying to stage should always create a new version.

at line 1996
int|null getMigratingVersion()

Get version migrated to

Return Value

int|null

at line 2005
migrateVersion(string $version) deprecated

deprecated 4.0...5.0

Parameters

string $version The version.

at line 2017
DataObject setMigratingVersion(string $version)

Set the migrating version.

Parameters

string $version The version.

Return Value

DataObject Owner

at line 2029
bool stagesDiffer()

Compare two stages to see if they're different.

Only checks the version numbers, not the actual content.

Return Value

bool

at line 2052
ArrayList Versions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")

Parameters

string $filter
string $sort
string $limit
string $join Deprecated, use leftJoin($table, $joinClause) instead
string $having

Return Value

ArrayList

at line 2082
ArrayList allVersions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "") deprecated

deprecated 1.5.0 Will be removed in 2.0.0, please use Versions() instead

Return a list of all the versions available.

Parameters

string $filter
string $sort
string $limit
string $join @deprecated use leftJoin($table, $joinClause) instead
string $having @deprecated

Return Value

ArrayList

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

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

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

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

at line 2281
static set_reading_mode(string $mode)

Set the current reading mode.

Parameters

string $mode

at line 2291
static string get_reading_mode()

Get the current reading mode.

Return Value

string

at line 2301
static string get_stage()

Get the current reading stage.

Return Value

string

at line 2316
static string current_archived_date()

Get the current archive date.

Return Value

string

at line 2330
static string current_archived_stage()

Get the current archive stage.

Return Value

string

at line 2345
static set_stage(string $stage)

Set the reading stage.

Parameters

string $stage New reading stage.

Exceptions

InvalidArgumentException

at line 2357
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 2367
static string get_default_reading_mode()

Get default reading mode

Return Value

string

at line 2378
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 2392
static set_draft_site_secured(bool $secured)

Set if the draft site should be secured or not

Parameters

bool $secured

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

at line 2420
static DataObject get_one_by_stage(string $class, string $stage, string $filter = '', boolean $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.
boolean $cache Use caching.
string $sort A sort expression to be inserted into the ORDER BY clause.

Return Value

DataObject

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

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

Hook into {@link 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.

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

at line 2558
static DataList get_by_stage(string $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

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
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 2580
deleteFromStage(string $stage)

Delete this record from the given stage

Parameters

string $stage

at line 2603
int writeToStage(string $stage, boolean $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
boolean $forceInsert

Return Value

int The ID of the record

at line 2639
doRollbackTo(int $version) deprecated

deprecated 4.2..5.0 Use rollbackRecursive() instead

Roll the draft version of this record to match the published record.

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

{see doRevertToLive()} to reollback to live

Parameters

int $version Version number

at line 2651
onAfterRollback() deprecated

deprecated 1.2..2.0 This extension method is redundant and will be removed

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

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

at line 2715
static DataObject get_latest_version(string $class, int $id)

Return the latest version of the given record.

Parameters

string $class
int $id

Return Value

DataObject

at line 2736
boolean isLatestVersion()

Returns whether the current record is the latest one.

Return Value

boolean

See also

get_latest_version()
latestPublished

at line 2753
bool isLiveVersion()

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

Return Value

bool

at line 2769
bool isLatestDraftVersion()

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

Return Value

bool

at line 2785
bool isPublished()

Check if this record exists on live

Return Value

bool

at line 2806
bool isArchived()

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

Return Value

bool

at line 2817
bool isOnDraft()

Check if this record exists on the draft stage

Return Value

bool

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

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

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

at line 2875
static DataList get_including_deleted(string $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

string $class
string $filter
string $sort

Return Value

DataList

at line 2898
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
int $id
int $version

Return Value

DataObject

at line 2918
static DataList get_all_versions(string $class, int $id)

Return a list of all versions for a given id.

Parameters

string $class
int $id

Return Value

DataList

at line 2951
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 2956
flushCache()

at line 2967
string cacheKeyComponent()

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

Return Value

string

at line 2977
array getVersionedStages()

Returns an array of possible stages.

Return Value

array

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

at line 2998
bool hasStages()

Check if this object has stages

Return Value

bool True if this object is staged

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

at line 3028
Member|null Author()

Get author of this record.

Note: Only works on records selected via Versions()

Return Value

Member|null

at line 3043
Member|null Publisher()

Get publisher of this record.

Note: Only works on records selected via Versions()

Return Value

Member|null