[TASK] Clean up phpDoc comments in t3lib_admin
authorWouter Wolters <typo3@wouterwolters.nl>
Fri, 4 May 2012 17:32:00 +0000 (19:32 +0200)
committerChristian Kuhn <lolli@schwarzbu.ch>
Fri, 4 May 2012 18:14:40 +0000 (20:14 +0200)
* Provide correct parameter names in phpDoc
* Provide correct data types in phpDoc
* CGLify phpDoc (remove tabs)
* CGLify method signatures (the first line of the method)

Change-Id: Ie5c9e6db3834a57ef3501b4eda783851e1fc6937
Resolves: #36852
Releases: 6.0
Reviewed-on: http://review.typo3.org/11006
Reviewed-by: Christian Kuhn
Tested-by: Christian Kuhn
t3lib/class.t3lib_admin.php

index b213067..6669dc7 100644 (file)
  * Revised for TYPO3 3.6 July/2003 by Kasper Skårhøj
  * XHTML compliant
  *
- * @author     Kasper Skårhøj <kasperYYYY@typo3.com>
+ * @author Kasper Skårhøj <kasperYYYY@typo3.com>
  */
 
-
 /**
  * This class holds functions used by the TYPO3 backend to check the integrity of the database (The DBint module, 'lowlevel' extension)
  *
- * Depends on:         Depends on loaddbgroup from t3lib/
+ * Depends on: Depends on loaddbgroup from t3lib/
  *
- * @todo       Need to really extend this class when the tcemain library has been updated and the whole API is better defined. There are some known bugs in this library. Further it would be nice with a facility to not only analyze but also clean up!
+ * @todo Need to really extend this class when the tcemain library has been updated and the whole API is better defined. There are some known bugs in this library. Further it would be nice with a facility to not only analyze but also clean up!
  * @see SC_mod_tools_dbint_index::func_relations(), SC_mod_tools_dbint_index::func_records()
- * @author     Kasper Skårhøj <kasperYYYY@typo3.com>
+ * @author Kasper Skårhøj <kasperYYYY@typo3.com>
  * @package TYPO3
  * @subpackage t3lib
  */
 class t3lib_admin {
-       /** @var bool If set, genTree() includes deleted pages. This is default.*/
+       /** @var boolean If set, genTree() includes deleted pages. This is default.*/
        var $genTree_includeDeleted = TRUE;
 
-       /** @var bool  If set, genTree() includes versionized pages/records. This is default.*/
+       /** @var boolean If set, genTree() includes versionized pages/records. This is default.*/
        var $genTree_includeVersions = TRUE;
 
-       /** @var bool  If set, genTree() includes records from pages. */
+       /** @var boolean If set, genTree() includes records from pages. */
        var $genTree_includeRecords = FALSE;
 
-       /** @var string  Extra where-clauses for the tree-selection */
+       /** @var string Extra where-clauses for the tree-selection */
        var $perms_clause = '';
 
-       /** @var int  If set, genTree() generates HTML, that visualizes the tree. */
+       /** @var int If set, genTree() generates HTML, that visualizes the tree. */
        var $genTree_makeHTML = 0;
 
-               // internal
+               // Internal
        /** @var array Will hold id/rec pairs from genTree() */
        var $page_idArray = array();
 
@@ -75,7 +74,7 @@ class t3lib_admin {
        /** @var string */
        var $backPath = '';
 
-               // internal
+               // Internal
        /** @var array */
        var $checkFileRefs = array();
 
@@ -100,12 +99,13 @@ class t3lib_admin {
 
 
        /**
-        * Generates a list of Page-uid's that corresponds to the tables in the tree. This list should ideally include all records in the pages-table.
+        * Generates a list of Page-uid's that corresponds to the tables in the tree.
+        * This list should ideally include all records in the pages-table.
         *
-        * @param       integer         a pid (page-record id) from which to start making the tree
-        * @param       string          HTML-code (image-tags) used when this function calls itself recursively.
-        * @param       boolean         Internal variable, don't set from outside!
-        * @return      void
+        * @param integer $theID a pid (page-record id) from which to start making the tree
+        * @param string $depthData HTML-code (image-tags) used when this function calls itself recursively.
+        * @param boolean $versions Internal variable, don't set from outside!
+        * @return void
         */
        function genTree($theID, $depthData, $versions = FALSE) {
 
@@ -159,7 +159,7 @@ class t3lib_admin {
                        $this->page_idArray[$newID] = $row;
 
                        $this->recStats['all_valid']['pages'][$newID] = $newID;
-                       #                       if ($versions)  $this->recStats['versions']['pages'][$newID] = $newID;
+
                        if ($row['deleted']) {
                                $this->recStats['deleted']['pages'][$newID] = $newID;
                        }
@@ -198,10 +198,10 @@ class t3lib_admin {
        }
 
        /**
-        * @param       integer         a pid (page-record id) from which to start making the tree
-        * @param       string          HTML-code used when this function calls itself recursively.
-        * @param       string          Table to get the records from
-        * @param       bool            Internal variable, don't set from outside!
+        * @param integer $theID a pid (page-record id) from which to start making the tree
+        * @param string $depthData HTML-code used when this function calls itself recursively.
+        * @param string $table Table to get the records from
+        * @param boolean $versions Internal variable, don't set from outside!
         * @return      void
         */
        function genTree_records($theID, $depthData, $table = '', $versions = FALSE) {
@@ -254,7 +254,7 @@ class t3lib_admin {
                        $this->rec_idArray[$table][$newID] = $row;
 
                        $this->recStats['all_valid'][$table][$newID] = $newID;
-                       #                       $this->recStats[$versions?'versions':'live'][$table][$newID] = $newID;
+
                        if ($row['deleted']) {
                                $this->recStats['deleted'][$table][$newID] = $newID;
                        }
@@ -262,10 +262,6 @@ class t3lib_admin {
                                $this->recStats['published_versions'][$table][$newID] = $newID;
                        }
 
-                       #                       if ($row['deleted']) {$this->recStat['deleted']++;}
-                       #                       if ($row['hidden']) {$this->recStat['hidden']++;}
-
-
                                // Select all versions of this record:
                        if ($this->genTree_includeVersions && $GLOBALS['TCA'][$table]['ctrl']['versioningWS']) {
                                $genHTML = $depthData . '<img' . t3lib_iconWorks::skinImg($this->backPath, 'gfx/ol/' . $LN . '.gif', 'width="18" height="16"') . ' align="top" alt="" />';
@@ -278,9 +274,12 @@ class t3lib_admin {
        /**
         * Generates tree and returns statistics
         *
-        * @return      array           Record statistics
+        * @param integer $root
+        * @return array Record statistics
+        * @deprecated and unused since 6.0, will be removed two versions later
         */
        function genTreeStatus($root = 0) {
+               t3lib_div::logDeprecatedFunction();
                $this->genTree_includeDeleted = TRUE; // if set, genTree() includes deleted pages. This is default.
                $this->genTree_includeVersions = TRUE; // if set, genTree() includes verisonized pages/records. This is default.
                $this->genTree_includeRecords = TRUE; // if set, genTree() includes records from pages.
@@ -292,12 +291,11 @@ class t3lib_admin {
                return $this->recStats;
        }
 
-
        /**
         * Fills $this->lRecords with the records from all tc-tables that are not attached to a PID in the pid-list.
         *
-        * @param       string          list of pid's (page-record uid's). This list is probably made by genTree()
-        * @return      void
+        * @param string $pid_list list of pid's (page-record uid's). This list is probably made by genTree()
+        * @return void
         */
        function lostRecords($pid_list) {
                $this->lostPagesList = '';
@@ -333,18 +331,20 @@ class t3lib_admin {
        }
 
        /**
-        * Fixes lost record from $table with uid $uid by setting the PID to zero. If there is a disabled column for the record that will be set as well.
+        * Fixes lost record from $table with uid $uid by setting the PID to zero.
+        * If there is a disabled column for the record that will be set as well.
         *
-        * @param       string          Database tablename
-        * @param       integer         The uid of the record which will have the PID value set to 0 (zero)
-        * @return      boolean         TRUE if done.
+        * @param string $table Database tablename
+        * @param integer $uid The uid of the record which will have the PID value set to 0 (zero)
+        * @return boolean TRUE if done.
         */
        function fixLostRecord($table, $uid) {
                if ($table && $GLOBALS['TCA'][$table] && $uid && is_array($this->lRecords[$table][$uid]) && $GLOBALS['BE_USER']->user['admin']) {
 
                        $updateFields = array();
                        $updateFields['pid'] = 0;
-                       if ($GLOBALS['TCA'][$table]['ctrl']['enablecolumns']['disabled']) { // If possible a lost record restored is hidden as default
+                               // If possible a lost record restored is hidden as default
+                       if ($GLOBALS['TCA'][$table]['ctrl']['enablecolumns']['disabled']) {
                                $updateFields[$GLOBALS['TCA'][$table]['ctrl']['enablecolumns']['disabled']] = 1;
                        }
 
@@ -359,8 +359,8 @@ class t3lib_admin {
        /**
         * Counts records from $GLOBALS['TCA']-tables that ARE attached to an existing page.
         *
-        * @param       string          list of pid's (page-record uid's). This list is probably made by genTree()
-        * @return      array           an array with the number of records from all $GLOBALS['TCA']-tables that are attached to a PID in the pid-list.
+        * @param string $pid_list list of pid's (page-record uid's). This list is probably made by genTree()
+        * @return array an array with the number of records from all $GLOBALS['TCA']-tables that are attached to a PID in the pid-list.
         */
        function countRecords($pid_list) {
                $list = array();
@@ -392,8 +392,8 @@ class t3lib_admin {
        /**
         * Finding relations in database based on type 'group' (files or database-uid's in a list)
         *
-        * @param       string          $mode = file, $mode = db, $mode = '' (all...)
-        * @return      array           An array with all fields listed that somehow are references to other records (foreign-keys) or files
+        * @param string $mode $mode = file, $mode = db, $mode = '' (all...)
+        * @return array An array with all fields listed that somehow are references to other records (foreign-keys) or files
         */
        function getGroupFields($mode) {
                $result = array();
@@ -423,8 +423,8 @@ class t3lib_admin {
        /**
         * Finds all fields that hold filenames from uploadfolder
         *
-        * @param       string          Path to uploadfolder
-        * @return      array           An array with all fields listed that have references to files in the $uploadfolder
+        * @param string $uploadfolder Path to uploadfolder
+        * @return array An array with all fields listed that have references to files in the $uploadfolder
         */
        function getFileFields($uploadfolder) {
                $result = array();
@@ -443,8 +443,8 @@ class t3lib_admin {
        /**
         * Returns an array with arrays of table/field pairs which are allowed to hold references to the input table name - according to $GLOBALS['TCA']
         *
-        * @param       string          Table name
-        * @return      array
+        * @param string $theSearchTable Table name
+        * @return array
         */
        function getDBFields($theSearchTable) {
                $result = array();
@@ -467,8 +467,8 @@ class t3lib_admin {
        /**
         * This selects non-empty-records from the tables/fields in the fkey_array generated by getGroupFields()
         *
-        * @param       array           Array with tables/fields generated by getGroupFields()
-        * @return      void
+        * @param array $fkey_arrays Array with tables/fields generated by getGroupFields()
+        * @return void
         * @see getGroupFields()
         */
        function selectNonEmptyRecordsWithFkeys($fkey_arrays) {
@@ -506,7 +506,7 @@ class t3lib_admin {
                                                                $fieldConf = $GLOBALS['TCA'][$table]['columns'][$field]['config'];
                                                                if ($fieldConf['type'] == 'group') {
                                                                        if ($fieldConf['internal_type'] == 'file') {
-                                                                                       // files...
+                                                                                       // Files...
                                                                                if ($fieldConf['MM']) {
                                                                                        $tempArr = array();
                                                                                        /** @var $dbAnalysis t3lib_loadDBGroup */
@@ -558,14 +558,14 @@ class t3lib_admin {
        /**
         * Depends on selectNonEmpty.... to be executed first!!
         *
-        * @return      array           Report over files; keys are "moreReferences", "noReferences", "noFile", "error"
+        * @return array Report over files; keys are "moreReferences", "noReferences", "noFile", "error"
         */
        function testFileRefs() {
                $output = array();
-                       // handle direct references with upload folder setting (workaround)
+                       // Handle direct references with upload folder setting (workaround)
                $newCheckFileRefs = array();
                foreach ($this->checkFileRefs as $folder => $files) {
-                               // only direct references without a folder setting
+                               // Only direct references without a folder setting
                        if ($folder !== '') {
                                $newCheckFileRefs[$folder] = $files;
                                continue;
@@ -573,12 +573,12 @@ class t3lib_admin {
 
                        foreach ($files as $file => $references) {
 
-                                       // direct file references have often many references (removes occurences in the moreReferences section of the result array)
+                                       // Direct file references have often many references (removes occurences in the moreReferences section of the result array)
                                if ($references > 1) {
                                        $references = 1;
                                }
 
-                                       // the directory must be empty (prevents checking of the root directory)
+                                       // The directory must be empty (prevents checking of the root directory)
                                $directory = dirname($file);
                                if ($directory !== '') {
                                        $newCheckFileRefs[$directory][basename($file)] = $references;
@@ -604,7 +604,7 @@ class t3lib_admin {
                                                        }
                                                        unset($fileArr[$entry]);
                                                } else {
-                                                               // contains workaround for direct references
+                                                               // Contains workaround for direct references
                                                        if (!strstr($entry, 'index.htm') && !preg_match('/^' . preg_quote($GLOBALS['TYPO3_CONF_VARS']['BE']['fileadminDir'], '/') . '/', $folder)) {
                                                                $output['noReferences'][] = array($path, $entry);
                                                        }
@@ -614,7 +614,7 @@ class t3lib_admin {
                                $d->close();
                                $tempCounter = 0;
                                foreach ($fileArr as $file => $value) {
-                                               // workaround for direct file references
+                                               // Workaround for direct file references
                                        if (preg_match('/^' . preg_quote($GLOBALS['TYPO3_CONF_VARS']['BE']['fileadminDir'], '/') . '/', $folder)) {
                                                $file = $folder . '/' . $file;
                                                $folder = '';
@@ -638,8 +638,8 @@ class t3lib_admin {
        /**
         * Depends on selectNonEmpty.... to be executed first!!
         *
-        * @param       array           Table with key/value pairs being table names and arrays with uid numbers
-        * @return      string          HTML Error message
+        * @param array $theArray Table with key/value pairs being table names and arrays with uid numbers
+        * @return string HTML Error message
         */
        function testDBRefs($theArray) {
                $result = '';
@@ -671,12 +671,13 @@ class t3lib_admin {
        /**
         * Finding all references to record based on table/uid
         *
-        * @param       string          Table name
-        * @param       integer         Uid of database record
-        * @return      array           Array with other arrays containing information about where references was found
+        * @param string $searchTable Table name
+        * @param integer $id Uid of database record
+        * @return array Array with other arrays containing information about where references was found
         */
        function whereIsRecordReferenced($searchTable, $id) {
-               $fileFields = $this->getDBFields($searchTable); // Gets tables / Fields that reference to files...
+                       // Gets tables / Fields that reference to files
+               $fileFields = $this->getDBFields($searchTable);
                $theRecordList = array();
                foreach ($fileFields as $info) {
                        $table = $info[0];
@@ -708,12 +709,13 @@ class t3lib_admin {
        /**
         * Finding all references to file based on uploadfolder / filename
         *
-        * @param       string          Upload folder where file is found
-        * @param       string          Filename to search for
-        * @return      array           Array with other arrays containing information about where references was found
+        * @param string $uploadfolder Upload folder where file is found
+        * @param string $filename Filename to search for
+        * @return array Array with other arrays containing information about where references was found
         */
        function whereIsFileReferenced($uploadfolder, $filename) {
-               $fileFields = $this->getFileFields($uploadfolder); // Gets tables / Fields that reference to files...
+                       // Gets tables / Fields that reference to files
+               $fileFields = $this->getFileFields($uploadfolder);
                $theRecordList = array();
                foreach ($fileFields as $info) {
                        $table = $info[0];
@@ -724,7 +726,8 @@ class t3lib_admin {
                                        $field . ' LIKE \'%' . $GLOBALS['TYPO3_DB']->quoteStr($filename, $table) . '%\''
                        );
                        while ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($mres)) {
-                                       // Now this is the field, where the reference COULD come from. But we're not guaranteed, so we must carefully examine the data.
+                                       // Now this is the field, where the reference COULD come from.
+                                       // But we're not guaranteed, so we must carefully examine the data.
                                $tempArr = explode(',', trim($row[$field]));
                                foreach ($tempArr as $file) {
                                        $file = trim($file);