diff --git a/model/Hierarchy.php b/model/Hierarchy.php
index 9a8cf67d9..c3e10ae17 100644
--- a/model/Hierarchy.php
+++ b/model/Hierarchy.php
@@ -1,9 +1,14 @@
'
- * @param string $extraArg Extra arguments that will be passed on to children, for if they overload this function.
- * @param boolean $limitToMarked Display only marked children.
- * @param string $childrenMethod The name of the method used to get children from each object
- * @param boolean $rootCall Set to true for this first call, and then to false for calls inside the recursion. You
- * should not change this.
- * @param int $nodeCountThreshold See {@link self::$node_threshold_total}
- * @param callable $nodeCountCallback Called with the node count, which gives the callback an opportunity
- * to intercept the query. Useful e.g. to avoid excessive children listings
- * (Arguments: $parent, $numChildren)
+ * Returns the children of this DataObject as an XHTML UL. This will be called recursively on each child, so if they
+ * have children they will be displayed as a UL inside a LI.
+ *
+ * @param string $attributes Attributes to add to the UL
+ * @param string|callable $titleEval PHP code to evaluate to start each child - this should include '
'
+ * @param string $extraArg Extra arguments that will be passed on to children, for if they
+ * overload this function
+ * @param bool $limitToMarked Display only marked children
+ * @param string $childrenMethod The name of the method used to get children from each object
+ * @param bool $rootCall Set to true for this first call, and then to false for calls inside
+ * the recursion. You should not change this.
+ * @param int $nodeCountThreshold See {@link self::$node_threshold_total}
+ * @param callable $nodeCountCallback Called with the node count, which gives the callback an opportunity to
+ * intercept the query. Useful e.g. to avoid excessive children listings
+ * (Arguments: $parent, $numChildren)
*
* @return string
*/
@@ -175,11 +182,12 @@ class Hierarchy extends DataExtension {
/**
* Mark a segment of the tree, by calling mark().
- * The method performs a breadth-first traversal until the number of nodes is more than minCount.
- * This is used to get a limited number of tree nodes to show in the CMS initially.
*
- * This method returns the number of nodes marked. After this method is called other methods
- * can check isExpanded() and isMarked() on individual nodes.
+ * The method performs a breadth-first traversal until the number of nodes is more than minCount. This is used to
+ * get a limited number of tree nodes to show in the CMS initially.
+ *
+ * This method returns the number of nodes marked. After this method is called other methods can check
+ * {@link isExpanded()} and {@link isMarked()} on individual nodes.
*
* @param int $nodeCountThreshold See {@link getChildrenAsUL()}
* @return int The actual number of nodes marked.
@@ -205,9 +213,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Filter the marking to only those object with $node->$parameterName = $parameterValue
- * @param string $parameterName The parameter on each node to check when marking.
- * @param mixed $parameterValue The value the parameter must be to be marked.
+ * Filter the marking to only those object with $node->$parameterName == $parameterValue
+ *
+ * @param string $parameterName The parameter on each node to check when marking.
+ * @param mixed $parameterValue The value the parameter must be to be marked.
*/
public function setMarkingFilter($parameterName, $parameterValue) {
$this->markingFilter = array(
@@ -217,9 +226,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Filter the marking to only those where the function returns true.
- * The node in question will be passed to the function.
- * @param string $funcName The function name.
+ * Filter the marking to only those where the function returns true. The node in question will be passed to the
+ * function.
+ *
+ * @param string $funcName The name of the function to call
*/
public function setMarkingFilterFunction($funcName) {
$this->markingFilter = array(
@@ -229,8 +239,9 @@ class Hierarchy extends DataExtension {
/**
* Returns true if the marking filter matches on the given node.
- * @param DataObject $node Node to check.
- * @return boolean
+ *
+ * @param DataObject $node Node to check
+ * @return bool
*/
public function markingFilterMatches($node) {
if(!$this->markingFilter) {
@@ -257,7 +268,11 @@ class Hierarchy extends DataExtension {
/**
* Mark all children of the given node that match the marking filter.
- * @param DataObject $node Parent node.
+ *
+ * @param DataObject $node Parent node
+ * @param mixed $context
+ * @param string $childrenMethod The name of the instance method to call to get the object's list of children
+ * @param string $numChildrenMethod The name of the instance method to call to count the object's children
* @return DataList
*/
public function markChildren($node, $context = null, $childrenMethod = "AllChildrenIncludingDeleted",
@@ -288,8 +303,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Ensure marked nodes that have children are also marked expanded.
- * Call this after marking but before iterating over the tree.
+ * Ensure marked nodes that have children are also marked expanded. Call this after marking but before iterating
+ * over the tree.
+ *
+ * @param string $numChildrenMethod The name of the instance method to call to count the object's children
*/
protected function markingFinished($numChildrenMethod = "numChildren") {
// Mark childless nodes as expanded.
@@ -303,9 +320,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Return CSS classes of 'unexpanded', 'closed', both, or neither, as well as a
- * 'jstree-*' state depending on the marking of this DataObject.
+ * Return CSS classes of 'unexpanded', 'closed', both, or neither, as well as a 'jstree-*' state depending on the
+ * marking of this DataObject.
*
+ * @param string $numChildrenMethod The name of the instance method to call to count the object's children
* @return string
*/
public function markingClasses($numChildrenMethod="numChildren") {
@@ -327,8 +345,10 @@ class Hierarchy extends DataExtension {
/**
* Mark the children of the DataObject with the given ID.
- * @param int $id ID of parent node.
- * @param boolean $open If this is true, mark the parent node as opened.
+ *
+ * @param int $id ID of parent node
+ * @param bool $open If this is true, mark the parent node as opened
+ * @return bool
*/
public function markById($id, $open = false) {
if(isset($this->markedNodes[$id])) {
@@ -344,6 +364,7 @@ class Hierarchy extends DataExtension {
/**
* Expose the given object in the tree, by marking this page and all it ancestors.
+ *
* @param DataObject $childObj
*/
public function markToExpose($childObj) {
@@ -356,7 +377,9 @@ class Hierarchy extends DataExtension {
}
/**
- * Return the IDs of all the marked nodes
+ * Return the IDs of all the marked nodes.
+ *
+ * @return array
*/
public function markedNodeIDs() {
return array_keys($this->markedNodes);
@@ -364,7 +387,8 @@ class Hierarchy extends DataExtension {
/**
* Return an array of this page and its ancestors, ordered item -> root.
- * @return array
+ *
+ * @return SiteTree[]
*/
public function parentStack() {
$p = $this->owner;
@@ -378,20 +402,20 @@ class Hierarchy extends DataExtension {
}
/**
- * True if this DataObject is marked.
- * @var boolean
+ * Cache of DataObjects' marked statuses: [ClassName][ID] = bool
+ * @var array
*/
protected static $marked = array();
/**
- * True if this DataObject is expanded.
- * @var boolean
+ * Cache of DataObjects' expanded statuses: [ClassName][ID] = bool
+ * @var array
*/
protected static $expanded = array();
/**
- * True if this DataObject is opened.
- * @var boolean
+ * Cache of DataObjects' opened statuses: [ClassName][ID] = bool
+ * @var array
*/
protected static $treeOpened = array();
@@ -430,7 +454,8 @@ class Hierarchy extends DataExtension {
/**
* Check if this DataObject is marked.
- * @return boolean
+ *
+ * @return bool
*/
public function isMarked() {
$baseClass = ClassInfo::baseDataClass($this->owner->class);
@@ -440,7 +465,8 @@ class Hierarchy extends DataExtension {
/**
* Check if this DataObject is expanded.
- * @return boolean
+ *
+ * @return bool
*/
public function isExpanded() {
$baseClass = ClassInfo::baseDataClass($this->owner->class);
@@ -450,6 +476,8 @@ class Hierarchy extends DataExtension {
/**
* Check if this DataObject's tree is opened.
+ *
+ * @return bool
*/
public function isTreeOpened() {
$baseClass = ClassInfo::baseDataClass($this->owner->class);
@@ -459,7 +487,8 @@ class Hierarchy extends DataExtension {
/**
* Get a list of this DataObject's and all it's descendants IDs.
- * @return int
+ *
+ * @return int[]
*/
public function getDescendantIDList() {
$idList = array();
@@ -468,8 +497,9 @@ class Hierarchy extends DataExtension {
}
/**
- * Get a list of this DataObject's and all it's descendants ID, and put it in $idList.
- * @var array $idList Array to put results in.
+ * Get a list of this DataObject's and all it's descendants ID, and put them in $idList.
+ *
+ * @param array $idList Array to put results in.
*/
public function loadDescendantIDListInto(&$idList) {
if($children = $this->AllChildren()) {
@@ -488,7 +518,8 @@ class Hierarchy extends DataExtension {
/**
* Get the children for this DataObject.
- * @return ArrayList
+ *
+ * @return DataList
*/
public function Children() {
if(!(isset($this->_cache_children) && $this->_cache_children)) {
@@ -506,7 +537,8 @@ class Hierarchy extends DataExtension {
/**
* Return all children, including those 'not in menus'.
- * @return SS_List
+ *
+ * @return DataList
*/
public function AllChildren() {
return $this->owner->stageChildren(true);
@@ -514,11 +546,13 @@ class Hierarchy extends DataExtension {
/**
* Return all children, including those that have been deleted but are still in live.
- * Deleted children will be marked as "DeletedFromStage"
- * Added children will be marked as "AddedToStage"
- * Modified children will be marked as "ModifiedOnStage"
- * Everything else has "SameOnStage" set, as an indicator that this information has been looked up.
- * @return SS_List
+ * - Deleted children will be marked as "DeletedFromStage"
+ * - Added children will be marked as "AddedToStage"
+ * - Modified children will be marked as "ModifiedOnStage"
+ * - Everything else has "SameOnStage" set, as an indicator that this information has been looked up.
+ *
+ * @param mixed $context
+ * @return ArrayList
*/
public function AllChildrenIncludingDeleted($context = null) {
return $this->doAllChildrenIncludingDeleted($context);
@@ -527,8 +561,8 @@ class Hierarchy extends DataExtension {
/**
* @see AllChildrenIncludingDeleted
*
- * @param unknown_type $context
- * @return SS_List
+ * @param mixed $context
+ * @return ArrayList
*/
public function doAllChildrenIncludingDeleted($context = null) {
if(!$this->owner) user_error('Hierarchy::doAllChildrenIncludingDeleted() called without $this->owner');
@@ -560,8 +594,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Return all the children that this page had, including pages that were deleted
- * from both stage & live.
+ * Return all the children that this page had, including pages that were deleted from both stage & live.
+ *
+ * @return DataList
+ * @throws Exception
*/
public function AllHistoricalChildren() {
if(!$this->owner->hasExtension('Versioned')) {
@@ -574,7 +610,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Return the number of children that this page ever had, including pages that were deleted
+ * Return the number of children that this page ever had, including pages that were deleted.
+ *
+ * @return int
+ * @throws Exception
*/
public function numHistoricalChildren() {
if(!$this->owner->hasExtension('Versioned')) {
@@ -586,11 +625,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Return the number of direct children.
- * By default, values are cached after the first invocation.
- * Can be augumented by {@link augmentNumChildrenCountQuery()}.
+ * Return the number of direct children. By default, values are cached after the first invocation. Can be
+ * augumented by {@link augmentNumChildrenCountQuery()}.
*
- * @param Boolean $cache
+ * @param bool $cache Whether to retrieve values from cache
* @return int
*/
public function numChildren($cache = true) {
@@ -606,10 +644,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Return children from the stage site
+ * Return children in the stage site.
*
- * @param showAll Inlcude all of the elements, even those not shown in the menus.
- * (only applicable when extension is applied to {@link SiteTree}).
+ * @param bool $showAll Include all of the elements, even those not shown in the menus. Only applicable when
+ * extension is applied to {@link SiteTree}.
* @return DataList
*/
public function stageChildren($showAll = false) {
@@ -625,12 +663,13 @@ class Hierarchy extends DataExtension {
}
/**
- * Return children from the live site, if it exists.
+ * Return children in the live site, if it exists.
*
- * @param boolean $showAll Include all of the elements, even those not shown in the menus.
- * (only applicable when extension is applied to {@link SiteTree}).
- * @param boolean $onlyDeletedFromStage Only return items that have been deleted from stage
- * @return SS_List
+ * @param bool $showAll Include all of the elements, even those not shown in the menus. Only
+ * applicable when extension is applied to {@link SiteTree}.
+ * @param bool $onlyDeletedFromStage Only return items that have been deleted from stage
+ * @return DataList
+ * @throws Exception
*/
public function liveChildren($showAll = false, $onlyDeletedFromStage = false) {
if(!$this->owner->hasExtension('Versioned')) {
@@ -652,7 +691,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Get the parent of this class.
+ * Get this object's parent, optionally filtered by an SQL clause. If the clause doesn't match the parent, nothing
+ * is returned.
+ *
+ * @param string $filter
* @return DataObject
*/
public function getParent($filter = null) {
@@ -669,7 +711,7 @@ class Hierarchy extends DataExtension {
/**
* Return all the parents of this class in a set ordered from the lowest to highest parent.
*
- * @return SS_List
+ * @return ArrayList
*/
public function getAncestors() {
$ancestors = new ArrayList();
@@ -683,11 +725,10 @@ class Hierarchy extends DataExtension {
}
/**
- * Returns a human-readable, flattened representation of the path to the object,
- * using its {@link Title()} attribute.
+ * Returns a human-readable, flattened representation of the path to the object, using its {@link Title} attribute.
*
- * @param String
- * @return String
+ * @param string $separator
+ * @return string
*/
public function getBreadcrumbs($separator = ' » ') {
$crumbs = array();
@@ -702,22 +743,25 @@ class Hierarchy extends DataExtension {
* then search the parents.
*
* @todo Write!
+ *
+ * @param string $className Class name of the node to find
+ * @param DataObject $afterNode Used for recursive calls to this function
+ * @return DataObject
*/
- public function naturalPrev( $className, $afterNode = null ) {
+ public function naturalPrev($className, $afterNode = null ) {
return null;
}
/**
* Get the next node in the tree of the type. If there is no instance of the className descended from this node,
* then search the parents.
- * @param string $className Class name of the node to find.
- * @param string|int $root ID/ClassName of the node to limit the search to
- * @param DataObject afterNode Used for recursive calls to this function
+ * @param string $className Class name of the node to find.
+ * @param string|int $root ID/ClassName of the node to limit the search to
+ * @param DataObject $afterNode Used for recursive calls to this function
* @return DataObject
*/
- public function naturalNext( $className = null, $root = 0, $afterNode = null ) {
- // If this node is not the node we are searching from, then we can possibly return this
- // node as a solution
+ public function naturalNext($className = null, $root = 0, $afterNode = null ) {
+ // If this node is not the node we are searching from, then we can possibly return this node as a solution
if($afterNode && $afterNode->ID != $this->owner->ID) {
if(!$className || ($className && $this->owner->class == $className)) {
return $this->owner;
@@ -761,6 +805,14 @@ class Hierarchy extends DataExtension {
return null;
}
+ /**
+ * Flush all Hierarchy caches:
+ * - Children (instance)
+ * - NumChildren (instance)
+ * - Marked (global)
+ * - Expanded (global)
+ * - TreeOpened (global)
+ */
public function flushCache() {
$this->_cache_children = null;
$this->_cache_numChildren = null;
@@ -769,6 +821,12 @@ class Hierarchy extends DataExtension {
self::$treeOpened = array();
}
+ /**
+ * Reset global Hierarchy caches:
+ * - Marked
+ * - Expanded
+ * - TreeOpened
+ */
public static function reset() {
self::$marked = array();
self::$expanded = array();
diff --git a/model/Versioned.php b/model/Versioned.php
index 0b4e720cf..c17d11f12 100644
--- a/model/Versioned.php
+++ b/model/Versioned.php
@@ -1,16 +1,24 @@
"Int",
@@ -78,33 +79,25 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
"PublisherID" => "Int"
);
- /**
- * @var array
- */
private static $db = array(
'Version' => 'Int'
);
/**
- * Used to enable or disable the prepopulation of the version number cache.
- * Defaults to true.
- *
- * @var boolean
- */
+ * Used to enable or disable the prepopulation of the version number cache. Defaults to true.
+ * @var bool
+ */
private static $prepopulate_versionnumber_cache = true;
/**
* Keep track of the archive tables that have been created.
- *
* @var array
*/
private static $archive_tables = array();
/**
- * Additional database indexes for the new
- * "_versions" table. Used in {@link augmentDatabase()}.
- *
- * @var array $indexes_for_versions_table
+ * Additional database indexes for the new "_versions" table. Used in {@link augmentDatabase()}.
+ * @var array
*/
private static $indexes_for_versions_table = array(
'RecordID_Version' => '("RecordID","Version")',
@@ -116,10 +109,9 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
- * 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',
@@ -142,9 +134,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
* Config::inst()->update($this->owner->class, '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.
+ * Make sure your extension has a static $enabled-property that determines if it is processed by Versioned.
*
* @var array
*/
@@ -170,9 +160,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Construct a new Versioned object.
*
- * @var array $stages The different stages the versioned object can be.
- * The first stage is considered the 'default' stage, the last stage is
- * considered the 'live' stage.
+ * @param array $stages The different stages the versioned object can be. The first stage is considered the
+ * 'default' stage, the last stage is considered the 'live' stage.
*/
public function __construct($stages = array('Stage','Live')) {
parent::__construct();
@@ -187,11 +176,10 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Amend freshly created DataQuery objects with versioned-specific
- * information.
+ * Amend freshly created DataQuery objects with versioned-specific information.
*
- * @param SQLQuery
- * @param DataQuery
+ * @param SQLQuery $query
+ * @param DataQuery $dataQuery
*/
public function augmentDataQueryCreation(SQLQuery &$query, DataQuery &$dataQuery) {
$parts = explode('.', Versioned::get_reading_mode());
@@ -206,12 +194,14 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
$dataQuery->setQueryParam('Versioned.mode', 'stage');
$dataQuery->setQueryParam('Versioned.stage', $parts[1]);
}
-
}
/**
- * Augment the the SQLQuery that is created by the DataQuery
+ * Augment the the SQLQuery that is created by the DataQuery.
* @todo Should this all go into VersionedDataQuery?
+ *
+ * @param SQLQuery $query
+ * @param DataQuery $dataQuery
*/
public function augmentSQL(SQLQuery &$query, DataQuery &$dataQuery = null) {
if(!$dataQuery || !$dataQuery->getQueryParam('Versioned.mode')) {
@@ -328,9 +318,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
$query->setOrderBy($orders);
- // latest_version has one more step
- // Return latest version instances, regardless of whether they are on a particular stage
- // This provides "show all, including deleted" functonality
+ // latest_version has one more step. Return latest version instances, regardless of whether they are on a
+ // particular stage. This provides "show all, including deleted" functonality
if($dataQuery->getQueryParam('Versioned.mode') == 'latest_versions') {
$query->addWhere(
"\"{$alias}_versions\".\"Version\" IN
@@ -355,17 +344,16 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * For lazy loaded fields requiring extra sql manipulation, ie versioning.
+ * For lazy loaded fields requiring extra SQL manipulation, ie versioning.
*
- * @param SQLQuery $query
- * @param DataQuery $dataQuery
+ * @param SQLQuery $query
+ * @param DataQuery $dataQuery
* @param DataObject $dataObject
*/
public function augmentLoadLazyFields(SQLQuery &$query, DataQuery &$dataQuery = null, $dataObject) {
- // The VersionedMode local variable ensures that this decorator only applies to
- // queries that have originated from the Versioned object, and have the Versioned
- // metadata set on the query object. This prevents regular queries from
- // accidentally querying the *_versions tables.
+ // The VersionedMode local variable ensures that this decorator only applies to queries that have originated
+ // from the Versioned object, and have the Versioned metadata set on the query object. This prevents regular
+ // queries from accidentally querying the *_versions tables.
$versionedMode = $dataObject->getSourceQueryParam('Versioned.mode');
$dataClass = $dataQuery->dataClass();
$modesToAllowVersioning = array('all_versions', 'latest_versions', 'archive');
@@ -382,7 +370,6 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
}
-
/**
* Called by {@link SapphireTest} when the database is reset.
*
@@ -498,8 +485,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
if(DB::get_schema()->hasTable("{$table}_versions")) {
- // Fix data that lacks the uniqueness constraint (since this was added later and
- // bugs meant that the constraint was validated)
+ // Fix data that lacks the uniqueness constraint (since this was added later and bugs meant that
+ // the constraint was validated)
$duplications = DB::query("SELECT MIN(\"ID\") AS \"ID\", \"RecordID\", \"Version\"
FROM \"{$table}_versions\" GROUP BY \"RecordID\", \"Version\"
HAVING COUNT(*) > 1");
@@ -514,8 +501,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
);
}
- // Remove junk which has no data in parent classes. Only needs to run the following
- // when versioned data is spread over multiple tables
+ // Remove junk which has no data in parent classes. Only needs to run the following when versioned
+ // data is spread over multiple tables
if(!$isRootClass && ($versionedTables = ClassInfo::dataClassesFor($table))) {
foreach($versionedTables as $child) {
@@ -595,9 +582,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Generates a ($table)_version DB manipulation and injects it into the current $manipulation
*
- * @param array $manipulation Source manipulation data
- * @param string $table Name of table
- * @param int $recordID ID of record to version
+ * @param SQLQuery $manipulation The query to augment
*/
protected function augmentWriteVersioned(&$manipulation, $table, $recordID) {
$baseDataClass = ClassInfo::baseDataClass($table);
@@ -740,8 +725,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
$this->migrateVersion(null);
}
- // Add the new version # back into the data object, for accessing
- // after this write
+ // Add the new version # back into the data object, for accessing after this write
if(isset($thisVersion)) {
$this->owner->Version = str_replace("'","", $thisVersion);
}
@@ -749,9 +733,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Perform a write without affecting the version table.
- * On objects without versioning.
*
- * @return int The ID of the record
+ * @return int The ID of the written record
*/
public function writeWithoutVersion() {
$this->_nextWriteWithoutVersion = true;
@@ -759,18 +742,13 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
return $this->owner->write();
}
- /**
- *
- */
public function onAfterWrite() {
$this->_nextWriteWithoutVersion = false;
}
/**
- * 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 function onAfterSkippedWrite() {
$this->migrateVersion(null);
@@ -867,11 +845,10 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Determine if a table is supporting the Versioned extensions (e.g.
- * $table_versions does exists).
+ * Determine if a table supports the Versioned extensions (e.g. $table_versions does exists).
*
* @param string $table Table name
- * @return boolean
+ * @return bool
*/
public function canBeVersioned($table) {
return ClassInfo::exists($table)
@@ -883,8 +860,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
* Check if a certain table has the 'Version' field.
*
* @param string $table Table name
- *
- * @return boolean Returns false if the field isn't in the table, true otherwise
+ * @return bool
*/
public function hasVersionField($table) {
$rPos = strrpos($table,'_');
@@ -900,7 +876,6 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* @param string $table
- *
* @return string
*/
public function extendWithSuffix($table) {
@@ -921,7 +896,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Get the latest published DataObject.
+ * Get the latest published version of this object.
*
* @return DataObject
*/
@@ -942,10 +917,10 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Move a database record from one stage to the other.
*
- * @param int|string $fromStage Place to copy from. Can be either a stage name or a version number.
- * @param string $toStage Place to copy to. Must be a stage name.
- * @param bool $createNewVersion Set this to true to create a new version number.
- * By default, the existing version number will be copied over.
+ * @param string $fromStage Place to copy from. Can be either a stage name or a version number.
+ * @param string $toStage Place to copy to. Must be a stage name.
+ * @param bool $createNewVersion Set this to true to create a new version number. By default, the existing
+ * version number will be copied over.
*/
public function publish($fromStage, $toStage, $createNewVersion = false) {
$this->owner->extend('onBeforeVersionedPublish', $fromStage, $toStage, $createNewVersion);
@@ -1005,19 +980,18 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Set the migrating version.
*
- * @param string $version The version.
+ * @param string $version
*/
public function migrateVersion($version) {
$this->migratingVersion = $version;
}
/**
- * Compare two stages to see if they're different.
+ * Compare two stages to see if they're different. Only checks the version numbers, not the actual content.
*
- * Only checks the version numbers, not the actual content.
- *
- * @param string $stage1 The first stage to check.
- * @param string $stage2
+ * @param string $stage1 The first stage to check
+ * @param string $stage2 The second stage to check
+ * @return bool
*/
public function stagesDiffer($stage1, $stage2) {
$table1 = $this->baseTable($stage1);
@@ -1027,8 +1001,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
return true;
}
- // We test for equality - if one of the versions doesn't exist, this
- // will be false.
+ // We test for equality - if one of the versions doesn't exist, this will be false.
// TODO: DB Abstraction: if statement here:
$stagesAreEqual = DB::prepared_query(
@@ -1042,24 +1015,28 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
+ * Get a list of versions for this object, optionally with additional SQL parameters
+ *
* @param string $filter
* @param string $sort
* @param string $limit
* @param string $join Deprecated, use leftJoin($table, $joinClause) instead
* @param string $having
+ * @return DataList
*/
public function Versions($filter = "", $sort = "", $limit = "", $join = "", $having = "") {
return $this->allVersions($filter, $sort, $limit, $join, $having);
}
/**
- * Return a list of all the versions available.
+ * Get a list of versions for this object, optionally with additional SQL parameters
*
* @param string $filter
* @param string $sort
* @param string $limit
- * @param string $join Deprecated, use leftJoin($table, $joinClause) instead
+ * @param string $join Deprecated, use leftJoin($table, $joinClause) instead
* @param string $having
+ * @return DataList
*/
public function allVersions($filter = "", $sort = "", $limit = "", $join = "", $having = "") {
// Make sure the table names are not postfixed (e.g. _Live)
@@ -1106,11 +1083,10 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Compare two version, and return the diff between them.
- *
- * @param string $from The version to compare from.
- * @param string $to The version to compare to.
+ * Compare two version, and return the differences between them.
*
+ * @param string $from The version to compare from
+ * @param string $to The version to compare to
* @return DataObject
*/
public function compareVersions($from, $to) {
@@ -1125,6 +1101,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Return the base table - the class that directly extends DataObject.
*
+ * @param string $stage Override the stage used
* @return string
*/
public function baseTable($stage = null) {
@@ -1162,16 +1139,12 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Choose the stage the site is currently on.
+ * 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'.
*
- * 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'.
+ * @param Session $session Optional session within which to store the resulting stage
*/
public static function choose_site_stage() {
// Check any pre-existing session mode
@@ -1268,7 +1241,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Set the reading stage.
*
- * @param string $stage New reading stage.
+ * @param string $stage
*/
public static function reading_stage($stage) {
Versioned::set_reading_mode('Stage.' . $stage);
@@ -1277,21 +1250,20 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Set the reading archive date.
*
- * @param string $date New reading archived date.
+ * @param string $date
*/
public static function reading_archived_date($date) {
Versioned::set_reading_mode('Archive.' . $date);
}
-
/**
* Get a singleton instance of a class in the given stage.
*
- * @param string $class The name of the class.
- * @param string $stage The name of the stage.
- * @param string $filter A filter to be inserted into the WHERE clause.
- * @param boolean $cache Use caching.
- * @param string $orderby A sort expression to be inserted into the ORDER BY clause.
+ * @param string $class The name of the class
+ * @param string $stage The name of the stage
+ * @param string $filter A filter to be inserted into the WHERE clause
+ * @param bool $cache Whether to load from the cache instead of fresh from the database
+ * @param string $sort A sort expression to be inserted into the ORDER BY clause.
*
* @return DataObject
*/
@@ -1305,10 +1277,10 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Gets the current version number of a specific record.
*
- * @param string $class
- * @param string $stage
- * @param int $id
- * @param boolean $cache
+ * @param string $class The classname of the desired object
+ * @param string $stage The name of the stage to load from
+ * @param int $id The object's ID
+ * @param bool $cache Whether to load from the cache instead of fresh from the database
*
* @return int
*/
@@ -1321,11 +1293,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
return self::$cache_versionnumber[$baseClass][$stage][$id];
}
- // get version as performance-optimized SQL query (gets called for each page in the sitetree)
- $version = DB::prepared_query(
- "SELECT \"Version\" FROM \"$stageTable\" WHERE \"ID\" = ?",
- array($id)
- )->value();
+ // get version as performance-optimized SQL query (gets called for each object of this class in the database)
+ $version = DB::query("SELECT \"Version\" FROM \"$stageTable\" WHERE \"ID\" = $id")->value();
// cache value (if required)
if($cache) {
@@ -1344,13 +1313,12 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * 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.
+ * 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.
*
- * @param string $class
- * @param string $stage
- * @param array $idList
+ * @param string $class The object class to prepopulate version numbers for
+ * @param string $stage The stage to prepopulate version numbers from
+ * @param array $idList A whitelist of IDs to use when prepopulating
*/
public static function prepopulate_versionnumber_cache($class, $stage, $idList = null) {
if (!Config::inst()->get('Versioned', 'prepopulate_versionnumber_cache')) {
@@ -1383,13 +1351,13 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Get a set of class instances by the given stage.
*
- * @param string $class The name of the class.
- * @param string $stage The name of the stage.
- * @param string $filter A filter to be inserted into the WHERE clause.
- * @param string $sort A sort expression to be inserted into the ORDER BY clause.
- * @param string $join Deprecated, use leftJoin($table, $joinClause) instead
- * @param int $limit A limit on the number of records returned from the database.
- * @param string $containerClass The container class for the result set (default is DataList)
+ * @param string $class The name of the class.
+ * @param string $stage The name of the stage.
+ * @param string $filter A filter to be inserted into the WHERE clause.
+ * @param string $sort A sort expression to be inserted into the ORDER BY clause.
+ * @param string $join Deprecated, use leftJoin($table, $joinClause) instead
+ * @param string|int $limit A limit on the number of records returned from the database.
+ * @param string $containerClass The container class for the result set (default is DataList)
*
* @return DataList A modified DataList designated to the specified stage
*/
@@ -1404,9 +1372,9 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * @param string $stage
+ * Delete this item from the specified stage.
*
- * @return int
+ * @param string $stage
*/
public function deleteFromStage($stage) {
$oldMode = Versioned::get_reading_mode();
@@ -1423,8 +1391,11 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * @param string $stage
- * @param boolean $forceInsert
+ * Write this item to the specified stage.
+ *
+ * @param string $stage The stage to write this item to
+ * @param bool $forceInsert Whether to force an INSERT query over an UPDATE query
+ * @return int The ID of the item being written
*/
public function writeToStage($stage, $forceInsert = false) {
$oldMode = Versioned::get_reading_mode();
@@ -1438,10 +1409,11 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Roll the draft version of this page to match the published page.
+ * Roll the draft version of this object to match the published one.
+ *
* Caution: Doesn't overwrite the object properties with the rolled back version.
*
- * @param int $version Either the string 'Live' or a version number
+ * @param string|int $version Either the string 'Live' or a version number
*/
public function doRollbackTo($version) {
$this->owner->extend('onBeforeRollback', $version);
@@ -1453,8 +1425,10 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Return the latest version of the given page.
+ * Return the latest version of the given object.
*
+ * @param string $class The classname of the object to lookup
+ * @param string $id The object of the ID to retrieve
* @return DataObject
*/
public static function get_latest_version($class, $id) {
@@ -1474,7 +1448,7 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
* @see get_latest_version()
* @see latestPublished
*
- * @return boolean
+ * @return bool
*/
public function isLatestVersion() {
$version = self::get_latest_version($this->owner->class, $this->owner->ID);
@@ -1486,14 +1460,12 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Return the equivalent of a DataList::create() call, querying the latest
- * version of each page stored in the (class)_versions tables.
+ * 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.
*
- * In particular, this will query deleted records as well as active ones.
- *
- * @param string $class
- * @param string $filter
- * @param string $sort
+ * @param string $class The type of object to lookup
+ * @param string $filter An optional SQL comparison to add to the WHERE clause
+ * @param string $sort An optional SQL statement to add to the SORT clause
*/
public static function get_including_deleted($class, $filter = "", $sort = "") {
$list = DataList::create($class)
@@ -1505,16 +1477,14 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
}
/**
- * Return the specific version of the given id.
+ * 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.
- *
- * @param string $class
- * @param int $id
- * @param int $version
+ * 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.
*
+ * @param string $class The type of object to lookup
+ * @param int $id The ID of the object to retrieve
+ * @param int $version The desired version of the object
* @return DataObject
*/
public static function get_version($class, $id, $version) {
@@ -1530,8 +1500,8 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
/**
* Return a list of all versions for a given id.
*
- * @param string $class
- * @param int $id
+ * @param string $class The type of object to lookup
+ * @param int $id The ID of the object to retrieve
*
* @return DataList
*/
@@ -1551,9 +1521,6 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
$labels['Versions'] = _t('Versioned.has_many_Versions', 'Versions', 'Past Versions of this page');
}
- /**
- * @param FieldList
- */
public function updateCMSFields(FieldList $fields) {
// remove the version field from the CMS as this should be left
// entirely up to the extension (not the cms user).
@@ -1570,12 +1537,15 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
$this->owner->Version = 0;
}
+ /**
+ * Clear the cached version numbers from previous queries.
+ */
public function flushCache() {
self::$cache_versionnumber = array();
}
/**
- * Return a piece of text to keep DataObject cache keys appropriately specific.
+ * Returns a piece of text to keep DataObject cache keys appropriately specific.
*
* @return string
*/
@@ -1615,14 +1585,11 @@ class Versioned extends DataExtension implements TemplateGlobalProvider {
* @see Versioned
*/
class Versioned_Version extends ViewableData {
- /**
- * @var array
- */
+
+ /** @var array */
protected $record;
- /**
- * @var DataObject
- */
+ /** @var DataObject */
protected $object;
public function __construct($record) {
@@ -1637,6 +1604,8 @@ class Versioned_Version extends ViewableData {
}
/**
+ * Get a CSS classname to use representing whether this version was published or not.
+ *
* @return string
*/
public function PublishedClass() {
@@ -1644,6 +1613,8 @@ class Versioned_Version extends ViewableData {
}
/**
+ * Gets this version's author (the person who saved to Stage).
+ *
* @return Member
*/
public function Author() {
@@ -1651,6 +1622,8 @@ class Versioned_Version extends ViewableData {
}
/**
+ * Get this version's publisher.
+ *
* @return Member
*/
public function Publisher() {
@@ -1662,7 +1635,9 @@ class Versioned_Version extends ViewableData {
}
/**
- * @return boolean
+ * Determines if this version was ever published.
+ *
+ * @return bool
*/
public function Published() {
return !empty($this->record['WasPublished']);
@@ -1670,6 +1645,9 @@ class Versioned_Version extends ViewableData {
/**
* Copied from DataObject to allow access via dot notation.
+ *
+ * @param string $fieldName
+ * @return mixed
*/
public function relField($fieldName) {
$component = $this;