Version: current

# Class Versioned

The Versioned decorator 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.

  Extension
  DataObjectDecorator
  Versioned

Package: sapphire\model
Located at sapphire/core/model/Versioned.php

## Methods summary

`public static` | # `reset( )` Reset static configuration variables to their default values Reset static configuration variables to their default values
`public` | # `__construct( mixed $stages )` Construct a new Versioned object. Construct a new Versioned object. #### Var array $stages The different stages the versioned object can be. The first stage is consiedered the 'default' stage, the last stage is considered the 'live' stage. #### Overrides `Extension::__construct`
`public array` | # `extraStatics( )` Define extra database fields 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. #### Returns `array` Returns a map where the keys are db, has_one, etc, and the values are additional fields/relations to be defined. #### Overrides `DataObjectDecorator::extraStatics`
`public` | # `augmentSQL( `SQLQuery` & $query )` Edit the given query object to support queries for this extension Edit the given query object to support queries for this extension #### Parameters $query SQLQuery $query Query to augment. #### Overrides `DataObjectDecorator::augmentSQL`
`public static` | # `on_db_reset( )` Called by `SapphireTest` when the database is reset. Called by `SapphireTest` when the database is reset.
`protected static` | # `requireArchiveTempTable( string $baseTable, string $date = null )` Create a temporary table mapping each database record to its version on the given date. This is used by the versioning system to return database content on that date. Create a temporary table mapping each database record to its version on the given date. This is used by the versioning system to return database content on that date. #### Parameters $baseTable string $baseTable The base table. $date string $date The date. If omitted, then the latest version of each page will be returned.
`public` | # `augmentDatabase( )` Update the database schema as required by this extension. Update the database schema as required by this extension. #### Overrides `DataObjectDecorator::augmentDatabase`
`public` | # `augmentWrite( `SQLQuery` & $manipulation )` Augment a write-record request. Augment a write-record request. #### Parameters $manipulation SQLQuery $manipulation Query to augment. #### Overrides `DataObjectDecorator::augmentWrite`
`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. 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 boolean` | # `canBeVersioned( string $table )` Determine if a table is supporting the Versioned extensions (e.g. $table_versions does exists) Determine if a table is supporting the Versioned extensions (e.g. $table_versions does exists) #### Parameters $table string $table Table name #### Returns `boolean` boolean
`public boolean` | # `hasVersionField( string $table )` Check if a certain table has the 'Version' field Check if a certain table has the 'Version' field #### Parameters $table string $table Table name #### Returns `boolean` Returns false if the field isn't in the table, true otherwise
`public` | # `extendWithSuffix( mixed $table )`
`public `DataObject`` | # `latestPublished( )` Get the latest published DataObject. Get the latest published DataObject. #### Returns ``DataObject`` DataObject
`public` | # `publish( fromStage $fromStage, toStage $toStage, createNewVersion $createNewVersion = false )` Move a database record from one stage to the other. Move a database record from one stage to the other. #### Parameters $fromStage fromStage Place to copy from. Can be either a stage name or a version number. $toStage toStage Place to copy to. Must be a stage name. $createNewVersion createNewVersion Set this to true to create a new version number. By default, the existing version number will be copied over.
`public` | # `clearOldVersions( mixed $ttl = 0 )`
`public` | # `migrateVersion( string $version )` Set the migrating version. Set the migrating version. #### Parameters $version string $version The version.
`public` | # `stagesDiffer( string $stage1, string $stage2 )` Compare two stages to see if they're different. Only checks the version numbers, not the actual content. Compare two stages to see if they're different. Only checks the version numbers, not the actual content. #### Parameters $stage1 string $stage1 The first stage to check. $stage2 string $stage2
`public` | # `Versions( mixed $filter = "", mixed $sort = "", mixed $limit = "", mixed $join = "", mixed $having = "" )`
`public` | # `allVersions( string $filter = "", mixed $sort = "", mixed $limit = "", mixed $join = "", mixed $having = "" )` Return a list of all the versions available. Return a list of all the versions available. #### Parameters $filter string $filter $sort $limit $join $having
`public `DataObject`` | # `compareVersions( string $from, string $to )` Compare two version, and return the diff between them. Compare two version, and return the diff between them. #### Parameters $from string $from The version to compare from. $to string $to The version to compare to. #### Returns ``DataObject`` DataObject
`public string` | # `baseTable( mixed $stage = null )` Return the base table - the class that directly extends DataObject. Return the base table - the class that directly extends DataObject. #### Returns `string` string
`public static` | # `choose_site_stage( )` 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'. 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'.
`public static` | # `set_reading_mode( mixed $mode )` Set the current reading mode. Set the current reading mode.
`public static string` | # `get_reading_mode( )` Get the current reading mode. Get the current reading mode. #### Returns `string` string
`public static string` | # `get_live_stage( )` Get the name of the 'live' stage. Get the name of the 'live' stage. #### Returns `string` string
`public static string` | # `current_stage( )` Get the current reading stage. Get the current reading stage. #### Returns `string` string
`public static string` | # `current_archived_date( )` Get the current archive date. Get the current archive date. #### Returns `string` string
`public static` | # `reading_stage( string $stage )` Set the reading stage. Set the reading stage. #### Parameters $stage string $stage New reading stage.
`public static` | # `reading_archived_date( string $date )` Set the reading archive date. Set the reading archive date. #### Parameters $date string $date New reading archived date.
`public static `DataObject`` | # `get_one_by_stage( string $class, string $stage, string $filter = '', boolean $cache = true, string $orderby = '' )` Get a singleton instance of a class in the given stage. Get a singleton instance of a class in the given stage. #### Parameters $class string $class The name of the class. $stage string $stage The name of the stage. $filter string $filter A filter to be inserted into the WHERE clause. $cache boolean $cache Use caching. $orderby string $orderby A sort expression to be inserted into the ORDER BY clause. #### Returns ``DataObject`` DataObject
`public static integer` | # `get_versionnumber_by_stage( string $class, string $stage, integer $id, boolean $cache = true )` Gets the current version number of a specific record. Gets the current version number of a specific record. #### Parameters $class string $class $stage string $stage $id int $id $cache boolean $cache #### Returns `integer` int
`public static` | # `prepopulate_versionnumber_cache( mixed $class, mixed $stage, mixed $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 page will be pre-cached. 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 page will be pre-cached.
`public static `DataObjectSet`` | # `get_by_stage( string $class, string $stage, string $filter = '', string $sort = '', string $join = '', integer $limit = '', string $containerClass = 'DataObjectSet' )` Get a set of class instances by the given stage. Get a set of class instances by the given stage. #### Parameters $class string $class The name of the class. $stage string $stage The name of the stage. $filter string $filter A filter to be inserted into the WHERE clause. $sort string $sort A sort expression to be inserted into the ORDER BY clause. $join string $join A join expression, such as LEFT JOIN or INNER JOIN $limit int $limit A limit on the number of records returned from the database. $containerClass string $containerClass The container class for the result set (default is DataObjectSet) #### Returns ``DataObjectSet`` DataObjectSet
`public` | # `deleteFromStage( mixed $stage )`
`public` | # `writeToStage( mixed $stage, mixed $forceInsert = false )`
`public` | # `buildVersionSQL( mixed $filter = "", mixed $sort = "" )` Build a SQL query to get data from the _version table. This function is similar in style to `DataObject::buildSQL()` Build a SQL query to get data from the _version table. This function is similar in style to `DataObject::buildSQL()`
`public static` | # `build_version_sql( mixed $className, mixed $filter = "", mixed $sort = "" )`
`public static `DataObject`` | # `get_latest_version( mixed $class, mixed $id )` Return the latest version of the given page. Return the latest version of the given page. #### Returns ``DataObject`` DataObject
`public static` | # `get_including_deleted( mixed $class, mixed $filter = "", mixed $sort = "" )` Return the equivalent of a DataObject::get() call, querying the latest version of each page stored in the (class)_versions tables. Return the equivalent of a DataObject::get() call, querying the latest version of each page stored in the (class)_versions tables. In particular, this will query deleted records as well as active ones.
`public static` | # `get_including_deleted_query( mixed $class, mixed $filter = "", mixed $sort = "" )` Return the query for the equivalent of a DataObject::get() call, querying the latest version of each page stored in the (class)_versions tables. Return the query for the equivalent of a DataObject::get() call, querying the latest version of each page stored in the (class)_versions tables. In particular, this will query deleted records as well as active ones.
`public static `DataObject`` | # `get_version( mixed $class, mixed $id, mixed $version )` #### Returns ``DataObject`` DataObject
`public static `DataObject`` | # `get_all_versions( mixed $class, mixed $id, mixed $version )` #### Returns ``DataObject`` DataObject
`public` | # `contentcontrollerInit( mixed $controller )`
`public` | # `modelascontrollerInit( mixed $controller )`
`public` | # `updateFieldLabels( mixed & $labels )` this function is used to provide modifications to the fields labels in CMS by the decorator By default, the fieldLabels() of its owner will merge more fields defined in the decorator's $extra_fields['field_labels'] this function is used to provide modifications to the fields labels in CMS by the decorator By default, the fieldLabels() of its owner will merge more fields defined in the decorator's $extra_fields['field_labels'] #### Overrides `DataObjectDecorator::updateFieldLabels`
`public` | # `flushCache( )` Clear any internal caches. Clear any internal caches. #### Overrides `DataObjectDecorator::flushCache`
`public` | # `cacheKeyComponent( )` Return a piece of text to keep DataObject cache keys appropriately specific Return a piece of text to keep DataObject cache keys appropriately specific

### Methods inherited from DataObjectDecorator

`can()`, `canCreate()`, `canDelete()`, `canEdit()`, `load_extra_statics()`, `onAfterDelete()`, `onAfterWrite()`, `onBeforeDelete()`, `onBeforeWrite()`, `populateDefaults()`, `requireDefaultRecords()`, `updateCMSActions()`, `updateCMSFields()`, `updateFrontEndFields()`, `updateSummaryFields()`

### Methods inherited from Extension

`clearOwner()`, `getOwner()`, `get_classname_without_arguments()`, `setOwner()`

### Magic methods summary

## Properties summary

`protected array` | $stages | # An array of possible stages. An array of possible stages.
`protected string` | $defaultStage | # The 'default' stage. The 'default' stage.
`protected string` | $liveStage | # The 'live' stage. 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. 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 `Versioned::flushCache()`. A cache used by get_versionnumber_by_stage(). Clear through `Versioned::flushCache()`.
`public static array` | $db_for_versions_table | # Additional database columns for the new "_versions" table. Used in `Versioned::augmentDatabase()` and all Versioned calls decorating or creating SELECT statements. Additional database columns for the new "_versions" table. Used in `Versioned::augmentDatabase()` and all Versioned calls decorating or creating SELECT statements.
`public static array` | $indexes_for_versions_table | # Additional database indexes for the new "_versions" table. Used in `Versioned::augmentDatabase()`. Additional database indexes for the new "_versions" table. Used in `Versioned::augmentDatabase()`.
`public static integer` | $versions_ttl | #
`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': 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': $versionableExtensions = array( 'Extension1' => 'suffix1', 'Extension2' => array('suffix2', 'suffix3'), ); Make sure your extension has a static $enabled-property that determines if it is processed by Versioned.
`protected static mixed` | $reading_mode | #

### Properties inherited from DataObjectDecorator

`$decoratable_statics`

### Properties inherited from Extension

`$allowed_actions`, `$class`, `$owner`, `$ownerBaseClass`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -