Versioned
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
Called when this extension is added to a particular class
Temporarily modify the owner. The original owner is ensured to be restored
Clear the current owner, and restore extension to the state prior to the last setOwner()
Helper method to strip eval'ed arguments from a string that's passed to DataObject::$extensions or Object::add_extension().
Invoke extension point. This will prefer explicit extend prefixed
methods.
Augment the the SQLSelect that is created by the DataQuery
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.
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.
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.
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.
Define extra database fields
This function is used to provide modifications to the Validators used on a DataObject.
This function is used to provide modifications to the form used for front end forms. DataObject->getFrontEndFields()
This is used to provide modifications to the form actions used in the CMS. DataObject->getCMSActions().
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']
Amend freshly created DataQuery objects with versioned-specific information.
Get this record at a specific version
Get modified date and stage for the given version
Updates query parameters of relations attached to versioned dataobjects
Reading a specific stage, but only return items that aren't in any other stage
Augment SQL to select from _Versions table instead.
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
Indicates if a subquery filtering versioned records should apply as a condition instead of an inner join
Filter the versioned history by a specific date and archive stage
Return latest version instance, regardless of whether it is on a particular stage.
Return latest version instances, regardless of whether they are on a particular stage.
If selecting a specific version, filter it here
If all versions are requested, ensure that records are sorted by this field
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
For lazy loaded fields requiring extra sql manipulation, ie versioning.
Cleanup orphaned records in the _Versions table
Generates a ($table)_version DB manipulation and injects it into the current $manipulation
Rewrite the given manipulation to update the selected (non-default) stage
Adds a WasDeleted=1 version entry for this record, and records any stages the deletion applies to
Set if next write should be without version or not
Helper method to safely suppress delete callback
If a write was skipped, then we need to ensure that we don't leave a migrateVersion() value lying around for the next write.
This function should return true if the current user can publish this record.
Check if the current user can delete this record from live
Check if the current user is allowed to archive this record.
Determine if there are any additional restrictions on this object for the given reading version.
Determines canView permissions for the latest version of this object on a specific stage.
Determine if a class is supporting the Versioned extensions (e.g.
Determines if the current draft version is the same as live or rather, that there are no outstanding draft changes
Determine if this object is published, and has any published owners.
Revert the draft changes: replace the draft content with the content on live
Move a database record from one stage to the other.
Determine if content differs on stages including nested objects 'owns' configuration drives the relationship traversal
No description
Compare two version, and return the diff between them.
Return the base table - the class that directly extends DataObject.
Given a table and stage determine the table name.
Determine if the current user is able to set the given site stage / archive
Set the reading archive date.
Get a singleton instance of a class in the given stage.
Gets the current version number of a specific record.
Hook into Hierarchy::prepopulateTreeDataCache.
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.
Get a set of class instances by the given stage.
Write the given record to the given stage.
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.
Return the latest version of the given record.
Returns whether the current record's version is the current live/published version
Returns whether the current record's version is the current draft/modified version
Check if this record exists on live On objects with only 1 stage, check if the record exists on that stage.
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).
Compares current draft with live version, and returns true if no live version exists, meaning the page was never published.
Compares current draft with live version, and returns true if these versions differ, meaning there have been unpublished changes to the draft site.
Return the equivalent of a DataList::create() call, querying the latest version of each record stored in the (class)_Versions tables.
Return the specific version of the given id.
Return a piece of text to keep DataObject cache keys appropriately specific.
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
Invoke a callback which may modify reading mode, but ensures this mode is restored after completion, without modifying global state.
Details
__construct($mode = Versioned::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
setOwner(object $owner)
Set the owner of this extension.
mixed
withOwner(mixed $owner, callable $callback, array $args = [])
Temporarily modify the owner. The original owner is ensured to be restored
clearOwner()
Clear the current owner, and restore extension to the state prior to the last setOwner()
T
getOwner()
Returns the owner of this extension.
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().
mixed
invokeExtension(object $owner, string $method, array ...$arguments)
Invoke extension point. This will prefer explicit extend prefixed
methods.
validate(ValidationResult $validationResult)
Hook for extension-specific validation.
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.
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.
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.
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.
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.
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.
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.
updateCMSFields(FieldList $fields)
No description
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.
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.
updateCMSActions(FieldList $actions)
This is used to provide modifications to the form actions used in the CMS. 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.
Versioned|DataObject
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
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 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
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.
This is similar to augmentSQLVersionedLatest() below, except it only returns a single value selected by Versioned.id
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.
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
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
int
writeWithoutVersion()
Perform a write without affecting the version table.
bool
getNextWriteWithoutVersion()
Check if next write is without version
DataObject
setNextWriteWithoutVersion(bool $flag)
Set if next write should be without version or not
bool
getDeleteWritesVersion()
Check if delete() should write _Version rows or not
DataObject
setDeleteWritesVersion(bool $flag)
Set if delete() should write _Version rows
protected mixed
suppressDeletedVersion(callable $callback)
Helper method to safely suppress delete 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
protected
extendCanPublish()
No description
mixed
canUnpublish(null $member = null)
Check if the current user can delete this record from live
protected
extendCanUnpublish()
No description
bool
canArchive(Member $member = null)
deprecated
deprecated
Check if the current user is allowed to archive this record.
If extended, ensure that both canDelete and canUnpublish are extended also
protected
extendCanArchive()
deprecated
deprecated
No description
bool
canRevertToLive(Member $member = null)
Check if the user can revert this record to live
protected
extendCanRevertToLive()
No description
bool
canRestoreToDraft(Member $member = null)
Check if the user can restore this record to draft
protected
extendcanRestoreToDraft()
No description
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.
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
bool
canViewStage(string $stage = Versioned::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.
bool
canBeVersioned(string $class)
Determine if a class is supporting 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()
Determines if the current draft version is the same as live or rather, that there are no outstanding draft changes
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.
bool
doArchive()
Removes the record from both live and stage
User code should call {\SilverStripe\Versioned\canArchive()} prior to invoking this method.
bool
doUnpublish()
Removes this record from the live site
User code should call {\SilverStripe\Versioned\canUnpublish()} prior to invoking this method.
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.
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.
copyVersionToStage(int|string|null $fromStage, string $toStage)
Move a database record from one stage to the other.
int|null
getMigratingVersion()
Get version migrated to
DataObject
setMigratingVersion(string $version)
Set the migrating version.
bool
stagesDiffer()
Compare two stages to see if they're different.
Only checks the version numbers, not the actual content.
bool
stagesDifferRecursive()
Determine if content differs on stages including nested objects 'owns' configuration drives the relationship traversal
Versioned_Version>
Versions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")
No description
DataObject
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.
Protected so it doesn't conflict with DataObject::baseTable()
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.
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.
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'.
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.
An non-default mode should be specified via querystring arguments.
static string
get_default_reading_mode()
Get default reading mode
static bool
get_draft_site_secured()
Check if draft site should be secured.
Can be turned off if draft site unauthenticated
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 = Versioned::DRAFT)
Set the reading archive date.
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.
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 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 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.
deleteFromStage(string $stage)
Delete this record from the given 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.
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.
rollbackSingle(int|string|null $version)
Rollback draft to a given version
static T&Versioned
get_latest_version(T> $class, int $id)
Return the latest version of the given record.
bool
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 On objects with only 1 stage, check if the record exists on that stage.
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.
On objects with only 1 stage, check if the record exists on that 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 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.
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.
static T>
get_all_versions(T> $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
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.
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.
The desired reading mode should be set by the callback directly
Member|null
Author()
Get author of this record.
Note: Only works on records selected via Versions()
Member|null
Publisher()
Get publisher of this record.
Note: Only works on records selected via Versions()