From b33fdba6d9808703c008a40bf889298a633b7cdd Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 25 Jan 2010 09:42:17 -0500 Subject: [PATCH] Updating doc blocks on Folder class and implementing a few small refactors to make code simpler. --- cake/libs/folder.php | 89 +++++++++++++++++++++----------------- cake/libs/log/file_log.php | 3 +- 2 files changed, 52 insertions(+), 40 deletions(-) diff --git a/cake/libs/folder.php b/cake/libs/folder.php index e1280001d..f8ea1ba0d 100644 --- a/cake/libs/folder.php +++ b/cake/libs/folder.php @@ -28,8 +28,7 @@ if (!class_exists('Object')) { /** * Folder structure browser, lists folders and files. - * - * Long description for class + * Provides an Object interface for Common directory related tasks. * * @package cake * @subpackage cake.cake.libs @@ -45,7 +44,8 @@ class Folder extends Object { var $path = null; /** - * Sortedness. + * Sortedness. Whether or not list results + * should be sorted by name. * * @var boolean * @access public @@ -53,15 +53,15 @@ class Folder extends Object { var $sort = false; /** - * mode to be used on create. + * Mode to be used on create. Does nothing on windows platforms. * - * @var boolean + * @var integer * @access public */ var $mode = 0755; /** - * holds messages from last method. + * Holds messages from last method. * * @var array * @access private @@ -69,7 +69,7 @@ class Folder extends Object { var $__messages = array(); /** - * holds errors from last method. + * Holds errors from last method. * * @var array * @access private @@ -77,7 +77,7 @@ class Folder extends Object { var $__errors = false; /** - * holds array of complete directory paths. + * Holds array of complete directory paths. * * @var array * @access private @@ -85,7 +85,7 @@ class Folder extends Object { var $__directories; /** - * holds array of complete file paths. + * Holds array of complete file paths. * * @var array * @access private @@ -148,7 +148,8 @@ class Folder extends Object { * Returns an array of the contents of the current directory. * The returned array holds two arrays: One of directories and one of files. * - * @param boolean $sort + * @param boolean $sort Whether you want the results sorted, set this and the sort property + * to false to get unsorted results. * @param mixed $exceptions Either an array or boolean true will not grab dot files * @param boolean $fullPath True returns the full path * @return mixed Contents of current directory as an array, an empty array on failure @@ -195,6 +196,7 @@ class Folder extends Object { * Returns an array of all matching files in current directory. * * @param string $pattern Preg_match pattern (Defaults to: .*) + * @param boolean $sort Whether results should be sorted. * @return array Files that match given pattern * @access public */ @@ -207,6 +209,7 @@ class Folder extends Object { * Returns an array of all matching files in and below current directory. * * @param string $pattern Preg_match pattern (Defaults to: .*) + * @param boolean $sort Whether results should be sorted. * @return array Files matching $pattern * @access public */ @@ -224,6 +227,7 @@ class Folder extends Object { * Private helper function for findRecursive. * * @param string $pattern Pattern to match against + * @param boolean $sort Whether results should be sorted. * @return array Files matching pattern * @access private */ @@ -254,23 +258,19 @@ class Folder extends Object { * @static */ function isWindowsPath($path) { - if (preg_match('/^[A-Z]:\\\\/i', $path)) { - return true; - } - return false; + return (bool) preg_match('/^[A-Z]:\\\\/i', $path); } /** * Returns true if given $path is an absolute path. * * @param string $path Path to check - * @return bool + * @return bool true if path is absolute. * @access public * @static */ function isAbsolute($path) { - $match = preg_match('/^\\//', $path) || preg_match('/^[A-Z]:\\\\/i', $path); - return $match; + return (bool) (preg_match('/^\\//', $path) || preg_match('/^[A-Z]:\\\\/i', $path)); } /** @@ -294,10 +294,7 @@ class Folder extends Object { * @static */ function correctSlashFor($path) { - if (Folder::isWindowsPath($path)) { - return '\\'; - } - return '/'; + return (Folder::isWindowsPath($path)) ? '\\' : '/'; } /** @@ -331,6 +328,7 @@ class Folder extends Object { /** * Returns true if the File is in a given CakePath. * + * @param string $path The path to check. * @return bool * @access public */ @@ -344,6 +342,8 @@ class Folder extends Object { /** * Returns true if the File is in given path. * + * @param string $path The path to check that the current pwd() resides with in. + * @param boolean $reverse * @return bool * @access public */ @@ -356,11 +356,7 @@ class Folder extends Object { } else { $return = preg_match('/^(.*)' . preg_quote($current, '/') . '(.*)/', $dir); } - if ($return == 1) { - return true; - } else { - return false; - } + return (bool) $return; } /** @@ -368,7 +364,7 @@ class Folder extends Object { * * @param string $path The path to chmod * @param integer $mode octal value 0755 - * @param boolean $recursive chmod recursively + * @param boolean $recursive chmod recursively, set to false to only change the current directory. * @param array $exceptions array of files, directories to skip * @return boolean Returns TRUE on success, FALSE on failure * @access public @@ -419,7 +415,7 @@ class Folder extends Object { * Returns an array of nested directories and files in each directory * * @param string $path the directory path to build the tree from - * @param boolean $hidden return hidden files and directories + * @param mixed $exceptions Array of files to exclude, defaults to excluding hidden files. * @param string $type either file or dir. null returns both files and directories * @return mixed array of nested directories and files in each directory * @access public @@ -431,8 +427,8 @@ class Folder extends Object { $this->__directories = array($path); $directories = array(); - if ($exceptions === false) { - $exceptions = true; + if ($hidden === false) { + $hidden = true; } while (count($this->__directories)) { $dir = array_pop($this->__directories); @@ -454,20 +450,21 @@ class Folder extends Object { /** * Private method to list directories and files in each directory * - * @param string $path - * @param = boolean $hidden + * @param string $path The Path to read. + * @param mixed $hidden Array of files to exclude from the read that will be performed. * @access private */ - function __tree($path, $exceptions) { + function __tree($path, $hidden) { if ($this->cd($path)) { - list($dirs, $files) = $this->read(false, $exceptions, true); + list($dirs, $files) = $this->read(false, $hidden, true); $this->__directories = array_merge($this->__directories, $dirs); $this->__files = array_merge($this->__files, $files); } } /** - * Create a directory structure recursively. + * Create a directory structure recursively. Can be used to create + * deep path structures like `/foo/bar/baz/shoe/horn` * * @param string $pathname The directory structure to create * @param integer $mode octal value 0755 @@ -507,7 +504,7 @@ class Folder extends Object { } /** - * Returns the size in bytes of this Folder. + * Returns the size in bytes of this Folder and its contents. * * @param string $directory Path to directory * @return int size in bytes of current folder @@ -544,7 +541,7 @@ class Folder extends Object { } /** - * Recursively Remove directories if system allow. + * Recursively Remove directories if the system allows. * * @param string $path Path of directory to delete * @return boolean Success @@ -596,8 +593,15 @@ class Folder extends Object { /** * Recursive directory copy. * - * @param array $options (to, from, chmod, skip) - * @return bool + * ### Options + * + * - `to` The directory to copy to. + * - `from` The directory to copy from, this will cause a cd() to occur, changing the results of pwd(). + * - `chmod` The mode to copy the files/directories with. + * - `skip` Files/directories to skip. + * + * @param mixed $options Either an array of options (see above) or a string of the destination directory. + * @return bool Success * @access public */ function copy($options = array()) { @@ -675,6 +679,13 @@ class Folder extends Object { /** * Recursive directory move. * + * ### Options + * + * - `to` The directory to copy to. + * - `from` The directory to copy from, this will cause a cd() to occur, changing the results of pwd(). + * - `chmod` The mode to copy the files/directories with. + * - `skip` Files/directories to skip. + * * @param array $options (to, from, chmod, skip) * @return boolean Success * @access public diff --git a/cake/libs/log/file_log.php b/cake/libs/log/file_log.php index 3702d882a..b5d2bec1c 100644 --- a/cake/libs/log/file_log.php +++ b/cake/libs/log/file_log.php @@ -21,7 +21,8 @@ if (!class_exists('File')) { require LIBS . 'file.php'; } /** - * File Storage stream for Logging + * File Storage stream for Logging. Writes logs to different files + * based on the type of log it is. * * @package cake * @subpackage cake.cake.libs.log