From 9791426be62aedc73c743e2af4821fa5409931b4 Mon Sep 17 00:00:00 2001 From: Nik Rolls Date: Tue, 2 Dec 2014 01:20:09 +1300 Subject: [PATCH] PHPDoc improvements for Hierarchy and Versioned - Added missing @param and @method documentation - Fixed incorrect PHPDoc @params and @returns - Fixed wrapping width on many docblocks - Added and/or improved method documentation when missing or confusing - Fixed typos as found - Removed references to 'Page' in Versioned documentation --- model/Hierarchy.php | 256 ++++++++++++++++++++------------- model/Versioned.php | 336 +++++++++++++++++++++----------------------- 2 files changed, 314 insertions(+), 278 deletions(-) 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;