Add types to Folder.

Move adoption of ?string instead of string|false. I had to expand types
on a few methods as the usage did not match the documentation.

src/Filesystem/Folder.php

@@ -132,9 +132,9 @@ class Folder
      *
      * @param string|null $path Path to folder
      * @param bool $create Create folder if not found
-     * @param int|false $mode Mode (CHMOD) to apply to created folder, false to ignore
+     * @param int|null $mode Mode (CHMOD) to apply to created folder, false to ignore
      */
-    public function __construct($path = null, $create = false, $mode = false)
+    public function __construct(?string $path = null, bool $create = false, ?int $mode = null)
     {
         if (empty($path)) {
             $path = TMP;
@@ -157,9 +157,9 @@ class Folder
     /**
      * Return current path.
      *
-     * @return string Current path
+     * @return string|null Current path
      */
-    public function pwd()
+    public function pwd(): ?string
     {
         return $this->path;
     }
@@ -168,16 +168,16 @@ class Folder
      * Change directory to $path.
      *
      * @param string $path Path to the directory to change to
-     * @return string|bool The new path. Returns false on failure
+     * @return string|bool The new path. Returns null on failure
      */
-    public function cd($path)
+    public function cd(string $path): ?string
     {
         $path = $this->realpath($path);
         if ($path !== false && is_dir($path)) {
             return $this->path = $path;
         }
 
-        return false;
+        return null;
     }
 
     /**
@@ -190,7 +190,7 @@ class Folder
      * @param bool $fullPath True returns the full path
      * @return array Contents of current directory as an array, an empty array on failure
      */
-    public function read($sort = self::SORT_NAME, $exceptions = false, $fullPath = false)
+    public function read($sort = self::SORT_NAME, $exceptions = false, bool $fullPath = false): array
     {
         $dirs = $files = [];
 
@@ -253,10 +253,10 @@ class Folder
      * Returns an array of all matching files in current directory.
      *
      * @param string $regexpPattern Preg_match pattern (Defaults to: .*)
-     * @param bool $sort Whether results should be sorted.
+     * @param string|bool $sort Whether results should be sorted.
      * @return array Files that match given pattern
      */
-    public function find($regexpPattern = '.*', $sort = false)
+    public function find(string $regexpPattern = '.*', $sort = false): array
     {
         list(, $files) = $this->read($sort);
 
@@ -267,10 +267,10 @@ class Folder
      * Returns an array of all matching files in and below current directory.
      *
      * @param string $pattern Preg_match pattern (Defaults to: .*)
-     * @param bool $sort Whether results should be sorted.
+     * @param string|bool $sort Whether results should be sorted.
      * @return array Files matching $pattern
      */
-    public function findRecursive($pattern = '.*', $sort = false)
+    public function findRecursive(string $pattern = '.*', $sort = false): array
     {
         if (!$this->pwd()) {
             return [];
@@ -289,7 +289,7 @@ class Folder
      * @param bool $sort Whether results should be sorted.
      * @return array Files matching pattern
      */
-    protected function _findRecursive($pattern, $sort = false)
+    protected function _findRecursive(string $pattern, bool $sort = false): array
     {
         list($dirs, $files) = $this->read($sort);
         $found = [];
@@ -315,7 +315,7 @@ class Folder
      * @param string $path Path to check
      * @return bool true if windows path, false otherwise
      */
-    public static function isWindowsPath($path)
+    public static function isWindowsPath(string $path): bool
     {
         return (preg_match('/^[A-Z]:\\\\/i', $path) || substr($path, 0, 2) === '\\\\');
     }
@@ -326,7 +326,7 @@ class Folder
      * @param string $path Path to check
      * @return bool true if path is absolute.
      */
-    public static function isAbsolute($path)
+    public static function isAbsolute(string $path): bool
     {
         if (empty($path)) {
             return false;
@@ -344,7 +344,7 @@ class Folder
      * @param string $path Path to check
      * @return bool True if path is registered stream wrapper.
      */
-    public static function isRegisteredStreamWrapper($path)
+    public static function isRegisteredStreamWrapper(string $path): bool
     {
         return preg_match('/^[^:\/\/]+?(?=:\/\/)/', $path, $matches) &&
             in_array($matches[0], stream_get_wrappers());
@@ -356,7 +356,7 @@ class Folder
      * @param string $path Path to transform
      * @return string Path with the correct set of slashes ("\\" or "/")
      */
-    public static function normalizeFullPath($path)
+    public static function normalizeFullPath(string $path): string
     {
         $to = Folder::correctSlashFor($path);
         $from = ($to == '/' ? '\\' : '/');
@@ -370,7 +370,7 @@ class Folder
      * @param string $path Path to check
      * @return string Set of slashes ("\\" or "/")
      */
-    public static function correctSlashFor($path)
+    public static function correctSlashFor(string $path): string
     {
         return Folder::isWindowsPath($path) ? '\\' : '/';
     }
@@ -381,7 +381,7 @@ class Folder
      * @param string $path Path to check
      * @return string Path with ending slash
      */
-    public static function slashTerm($path)
+    public static function slashTerm(string $path): string
     {
         if (Folder::isSlashTerm($path)) {
             return $path;
@@ -397,7 +397,7 @@ class Folder
      * @param string|array $element Element to add at end of path
      * @return string Combined path
      */
-    public static function addPathElement($path, $element)
+    public static function addPathElement(string $path, $element): string
     {
         $element = (array)$element;
         array_unshift($element, rtrim($path, DIRECTORY_SEPARATOR));
@@ -413,7 +413,7 @@ class Folder
      * @return bool
      * @throws \InvalidArgumentException When the given `$path` argument is not an absolute path.
      */
-    public function inPath($path, $reverse = false)
+    public function inPath(string $path, bool $reverse = false): bool
     {
         if (!Folder::isAbsolute($path)) {
             throw new InvalidArgumentException('The $path argument is expected to be an absolute path.');
@@ -440,7 +440,7 @@ class Folder
      * @param array $exceptions Array of files, directories to skip.
      * @return bool Success.
      */
-    public function chmod($path, $mode = false, $recursive = true, array $exceptions = [])
+    public function chmod(string $path, ?int $mode = null, bool $recursive = true, array $exceptions = []): bool
     {
         if (!$mode) {
             $mode = $this->mode;
@@ -497,7 +497,7 @@ class Folder
      * @param bool $fullPath Whether to return the full path or only the directory name.
      * @return array Array of subdirectories for the provided or current path.
      */
-    public function subdirectories($path = null, $fullPath = true)
+    public function subdirectories(?string $path = null, bool $fullPath = true): array
     {
         if (!$path) {
             $path = $this->path;
@@ -529,7 +529,7 @@ class Folder
      * @param string|null $type either 'file' or 'dir'. Null returns both files and directories
      * @return array Array of nested directories and files in each directory
      */
-    public function tree($path = null, $exceptions = false, $type = null)
+    public function tree(?string $path = null, $exceptions = false, ?string $type = null): array
     {
         if (!$path) {
             $path = $this->path;
@@ -599,10 +599,10 @@ class Folder
      * @param string $pathname The directory structure to create. Either an absolute or relative
      *   path. If the path is relative and exists in the process' cwd it will not be created.
      *   Otherwise relative paths will be prefixed with the current pwd().
-     * @param int|bool $mode octal value 0755
+     * @param int|null $mode octal value 0755
      * @return bool Returns TRUE on success, FALSE on failure
      */
-    public function create($pathname, $mode = false)
+    public function create(string $pathname, ?int $mode = null): bool
     {
         if (is_dir($pathname) || empty($pathname)) {
             return true;
@@ -648,7 +648,7 @@ class Folder
      *
      * @return int size in bytes of current folder
      */
-    public function dirsize()
+    public function dirsize(): int
     {
         $size = 0;
         $directory = Folder::slashTerm($this->path);
@@ -686,7 +686,7 @@ class Folder
      * @param string|null $path Path of directory to delete
      * @return bool Success
      */
-    public function delete($path = null)
+    public function delete(?string $path = null): bool
     {
         if (!$path) {
             $path = $this->pwd();
@@ -756,7 +756,7 @@ class Folder
      * @param array $options Array of options (see above).
      * @return bool Success.
      */
-    public function copy($to, array $options = [])
+    public function copy(string $to, array $options = []): bool
     {
         if (!$this->pwd()) {
             return false;
@@ -857,7 +857,7 @@ class Folder
      * @param array $options Array of options (see above).
      * @return bool Success
      */
-    public function move($to, array $options = [])
+    public function move(string $to, array $options = []): bool
     {
         $options += ['from' => $this->path, 'mode' => $this->mode, 'skip' => [], 'recursive' => true];
 
@@ -874,7 +874,7 @@ class Folder
      * @param bool $reset Reset message stack after reading
      * @return array
      */
-    public function messages($reset = true)
+    public function messages(bool $reset = true): array
     {
         $messages = $this->_messages;
         if ($reset) {
@@ -890,7 +890,7 @@ class Folder
      * @param bool $reset Reset error stack after reading
      * @return array
      */
-    public function errors($reset = true)
+    public function errors(bool $reset = true): array
     {
         $errors = $this->_errors;
         if ($reset) {
@@ -948,7 +948,7 @@ class Folder
      * @param string $path Path to check
      * @return bool true if path ends with slash, false otherwise
      */
-    public static function isSlashTerm($path)
+    public static function isSlashTerm(string $path): bool
     {
         $lastChar = $path[strlen($path) - 1];
 

tests/TestCase/Filesystem/FolderTest.php

@@ -86,7 +86,7 @@ class FolderTest extends TestCase
         $this->assertEquals($expected, $result);
 
         $result = $Folder->cd(ROOT . DS . 'non-existent');
-        $this->assertFalse($result);
+        $this->assertNull($result);
     }
 
     /**