Versioned
class Versioned extends DataExtension implements TemplateGlobalProvider (View source)
The Versioned extension allows your DataObjects to have several versions, allowing you to rollback changes and view history. An example of this is the pages used in the CMS.
Constants
| DEFAULT_MODE |
The default reading mode |
| LIVE |
The Public stage. |
| DRAFT |
The draft (default) stage |
Properties
| DataObject | $owner | |||
| protected | DataObject | $ownerBaseClass | The base class that this extension was applied to; $this->owner must be one of these |
from Extension |
| public | $class | from Extension | ||
| protected | array | $stages | An array of possible stages. |
|
| protected | string | $defaultStage | The 'default' stage. |
|
| protected | string | $liveStage | The 'live' stage. |
|
| public | string | $migratingVersion | A version that a DataObject should be when it is 'migrating', that is, when it is in the process of moving from one stage to another. |
|
| protected static | array | $cache_versionnumber | A cache used by get_versionnumber_by_stage(). Clear through flushCache(). |
|
| protected static | bool|null | $is_draft_site_secured | Set if draft site is secured or not. Fails over to $draft_site_secured if unset |
|
| protected static | string | $reading_mode | Current reading mode |
|
| protected static | null | $default_reading_mode | Default reading mode, if none set. |
|
| public | bool | $_nextWriteWithoutVersion | Flag which is temporarily changed during the write() process to influence augmentWrite() behaviour. If set to true, no new version will be created for the following write. Needs to be public as other classes introspect this state during the write process in order to adapt to this versioning behaviour. |
|
| protected static | array | $versionableExtensions | An array of DataObject extensions that may require versioning for extra tables. The array value is a set of suffixes to form these table names, assuming a preceding '_'. E.g. if Extension1 creates a new table 'Class_suffix1' and Extension2 the tables 'Class_suffix2' and 'Class_suffix3': |
|
| int | $RecordID | |||
| int | $Version | |||
| bool | $WasPublished | |||
| int | $AuthorID | |||
| int | $PublisherID |
Methods
Called when this extension is added to a particular class
Helper method to strip eval'ed arguments from a string thats passed to DataObject::$extensions or Object::add_extension().
Augment the the SQLQuery that is created by the DataQuery.
Define extra database fields
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.
For lazy loaded fields requiring extra SQL manipulation, ie versioning.
Generates a ($table)_version DB manipulation and injects it into the current $manipulation
Rewrite the given manipulation to update the selected (non-default) stage
If a write was skipped, then we need to ensure that we don't leave a migrateVersion() value lying around for the next write.
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 table supports the Versioned extensions (e.g. $table_versions does exists).
Move a database record from one stage to the other.
Compare two stages to see if they're different. Only checks the version numbers, not the actual content.
Get a list of versions for this object, optionally with additional SQL parameters
Get a list of versions for this object, optionally with additional SQL parameters
Compare two version, and return the differences between them.
Return the base table - the class that directly extends DataObject.
Determine if the current user is able to set the given site stage / archive
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.
Get a singleton instance of a class in the given stage.
Gets the current version number of a specific record.
Prepopulate the cache for Versioned::get_versionnumber_by_stage() for a list of record IDs, for more efficient database querying. If $idList is null, then every object will be pre-cached.
Get a set of class instances by the given stage.
Write this item to the specified stage.
Roll the draft version of this object to match the published one.
Return the latest version of the given object.
Return the equivalent of a DataList::create() call, querying the latest version of each object stored in the (class)_versions tables. In particular, this will query deleted records as well as active ones.
Return the specific version of the given ID.
Return a list of all versions for a given id.
Returns a piece of text to keep DataObject cache keys appropriately specific.
Details
__construct(array $stages = array('Stage', 'Live'))
Construct a new Versioned object.
static
add_to_class(string $class, string $extensionClass, mixed $args = null)
Called when this extension is added to a particular class
setOwner(SS_Object $owner, string $ownerBaseClass = null)
Set the owner of this extension.
clearOwner()
No description
SS_Object
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 thats passed to DataObject::$extensions or Object::add_extension().
static
get_extra_config($class, $extension, $args)
No description
static
unload_extra_statics($class, $extension)
No description
validate(ValidationResult $validationResult)
Hook for extension-specific validation.
augmentSQL(SQLQuery $query, DataQuery $dataQuery = null)
Augment the the SQLQuery that is created by the DataQuery.
augmentDatabase()
Update the database schema as required by this extension.
When duplicating a table's structure, remember to duplicate the create options as well. See Versioned->augmentDatabase for an example.
augmentWrite(array $manipulation)
No description
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($class = null, $extension = null)
Define extra database fields
Return a map where the keys are db, has_one, etc, and the values are additional fields/relations to be defined.
updateCMSFields(FieldList $fields)
No description
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(SQLQuery $query, DataQuery $dataQuery)
Amend freshly created DataQuery objects with versioned-specific information.
augmentLoadLazyFields(SQLQuery $query, DataQuery $dataQuery = null, DataObject $dataObject)
For lazy loaded fields requiring extra SQL manipulation, ie versioning.
static
on_db_reset()
Called by SapphireTest when the database is reset.
protected
augmentWriteVersioned(SQLQuery $manipulation, string $table, string|int $recordID)
Generates a ($table)_version DB manipulation and injects it into the current $manipulation
protected
augmentWriteStaged(array $manipulation, string $table, string|int $recordID)
Rewrite the given manipulation to update the selected (non-default) stage
int
writeWithoutVersion()
Perform a write without affecting the version table.
onAfterSkippedWrite()
If a write was skipped, then we need to ensure that we don't leave a migrateVersion() value lying around for the next write.
bool|null
canView(Member $member = null)
Extend permissions to include additional security for objects that are not published to live.
bool
canViewVersioned(Member $member = null)
Determine if there are any additional restrictions on this object for the given reading version.
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 = '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 $table)
Determine if a table supports the Versioned extensions (e.g. $table_versions does exists).
bool
hasVersionField(string $table)
Check if a certain table has the 'Version' field.
string
extendWithSuffix(string $table)
No description
bool
latestPublished()
Is the latest version of the object published?
publish(string $fromStage, string $toStage, bool $createNewVersion = false)
Move a database record from one stage to the other.
migrateVersion(string $version)
Set the migrating version.
bool
stagesDiffer(string $stage1, string $stage2)
Compare two stages to see if they're different. Only checks the version numbers, not the actual content.
DataList
Versions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")
Get a list of versions for this object, optionally with additional SQL parameters
DataList
allVersions(string $filter = "", string $sort = "", string $limit = "", string $join = "", string $having = "")
Get a list of versions for this object, optionally with additional SQL parameters
DataObject
compareVersions(string $from, string $to)
Compare two version, and return the differences between them.
string
baseTable(string $stage = null)
Return the base table - the class that directly extends DataObject.
static bool
can_choose_site_stage(SS_HTTPRequest $request)
Determine if the current user is able to set the given site stage / archive
static
choose_site_stage(SS_HTTPRequest $request = null)
Choose the stage the site is currently on:
- If $_GET['stage'] is set, then it will use that stage, and store it in the session.
- 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_live_stage()
Get the name of the 'live' stage.
static string
current_stage()
Get the current reading stage.
static string
current_archived_date()
Get the current archive date.
static
reading_stage(string $stage)
Set the reading stage.
static
set_default_reading_mode(string $mode)
Replace default mode.
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)
Set the reading archive date.
static DataObject
get_one_by_stage(string $class, string $stage, string $filter = '', bool $cache = true, string $sort = '')
Get a singleton instance of a class in the given stage.
static int
get_versionnumber_by_stage(string $class, string $stage, int $id, bool $cache = true)
Gets the current version number of a specific record.
static
prepopulate_versionnumber_cache(string $class, string $stage, array $idList = null)
Prepopulate the cache for Versioned::get_versionnumber_by_stage() for a list of record IDs, for more efficient database querying. If $idList is null, then every object will be pre-cached.
static DataList
get_by_stage(string $class, string $stage, string $filter = '', string $sort = '', string $join = '', string|int $limit = '', string $containerClass = 'DataList')
Get a set of class instances by the given stage.
deleteFromStage(string $stage)
Delete this item from the specified stage.
int
writeToStage(string $stage, bool $forceInsert = false)
Write this item to the specified stage.
doRollbackTo(string|int $version)
Roll the draft version of this object to match the published one.
Caution: Doesn't overwrite the object properties with the rolled back version.
static DataObject
get_latest_version(string $class, string $id)
Return the latest version of the given object.
bool
isLatestVersion()
Returns whether the current record is the latest one.
static
get_including_deleted(string $class, string $filter = "", string $sort = "")
Return the equivalent of a DataList::create() call, querying the latest version of each object stored in the (class)_versions tables. In particular, this will query deleted records as well as active ones.
static DataObject
get_version(string $class, int $id, int $version)
Return the specific version of the given ID.
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 DataList
get_all_versions(string $class, int $id)
Return a list of all versions for a given id.
onBeforeDuplicate(DataObject $source, bool $doWrite)
Ensure version ID is reset to 0 on duplicate
flushCache()
Clear the cached version numbers from previous queries.
string
cacheKeyComponent()
Returns a piece of text to keep DataObject cache keys appropriately specific.
array
getVersionedStages()
Returns an array of possible stages.
string
getDefaultStage()
No description
static array
get_template_global_variables()
No description