Folder & File

The Folder and File utilities are convenience classes to help you read from andwrite/append to files; list files within a folder and other common directoryrelated tasks.

Basic Usage

Ensure the classes are loaded:

use Cake\Filesystem\Folder;
use Cake\Filesystem\File;

Then we can setup a new folder instance:

$dir = new Folder('/path/to/folder');

and search for all .ctp files within that folder using regex:

$files = $dir->find('.*\.ctp');

Now we can loop through the files and read from or write/append to the contents orsimply delete the file:

foreach ($files as $file) {
    $file = new File($dir->pwd() . DS . $file);
    $contents = $file->read();
    // $file->write('I am overwriting the contents of this file');
    // $file->append('I am adding to the bottom of this file.');
    // $file->delete(); // I am deleting this file
    $file->close(); // Be sure to close the file when you're done
}

Folder API

• class Cake\Filesystem\Folder(string $path = false, boolean $create = false, string|boolean $mode = false)

// Create a new folder with 0755 permissions
$dir = new Folder('/path/to/folder', true, 0755);

• property Cake\Filesystem\Folder::$path

• Path of the current folder. Folder::pwd() will return the sameinformation.

• property Cake\Filesystem\Folder::$sort

• Whether or not the list results should be sorted by name.

• property Cake\Filesystem\Folder::$mode

• Mode to be used when creating folders. Defaults to 0755. Does nothing onWindows machines.

• static Cake\Filesystem\Folder::addPathElement(string $path, string $element)

• Returns $path with $element added, with correct slash in-between:

$path = Folder::addPathElement('/a/path/for', 'testing');
// $path equals /a/path/for/testing

$element can also be an array:

$path = Folder::addPathElement('/a/path/for', ['testing', 'another']);
// $path equals /a/path/for/testing/another

• Cake\Filesystem\Folder::cd($path)
• Change directory to $path. Returns false on failure:

$folder = new Folder('/foo');
echo $folder->path; // Prints /foo
$folder->cd('/bar');
echo $folder->path; // Prints /bar
$false = $folder->cd('/non-existent-folder');

• Cake\Filesystem\Folder::chmod(string $path, integer $mode = false, boolean $recursive = true, array $exceptions = [])
• Change the mode on a directory structure recursively. This includeschanging the mode on files as well:

$dir = new Folder();
$dir->chmod('/path/to/folder', 0755, true, ['skip_me.php']);

• Cake\Filesystem\Folder::copy(array|string $options = [])
• Recursively copy a directory. The only parameter $options can eitherbe a path into copy to or an array of options:

$folder1 = new Folder('/path/to/folder1');
$folder1->copy('/path/to/folder2');
// Will put folder1 and all its contents into folder2
 
$folder = new Folder('/path/to/folder');
$folder->copy([
    'to' => '/path/to/new/folder',
    'from' => '/path/to/copy/from', // Will cause a cd() to occur
    'mode' => 0755,
    'skip' => ['skip-me.php', '.git'],
    'scheme' => Folder::SKIP  // Skip directories/files that already exist.
]);

There are 3 supported schemes:

• Folder::SKIP skip copying/moving files & directories that exist in thedestination directory.
• Folder::MERGE merge the source/destination directories. Files in thesource directory will replace files in the target directory. Directorycontents will be merged.
• Folder::OVERWRITE overwrite existing files & directories in the targetdirectory with those in the source directory. If both the target anddestination contain the same subdirectory, the target directory’s contentswill be removed and replaced with the source’s.
  • static Cake\Filesystem\Folder::correctSlashFor(string $path)
  • Returns a correct set of slashes for given $path (‘' forWindows paths and ‘/’ for other paths).

• Cake\Filesystem\Folder::create(string $pathname, integer $mode = false)
• Create a directory structure recursively. Can be used to createdeep path structures like /foo/bar/baz/shoe/horn:

$folder = new Folder();
if ($folder->create('foo' . DS . 'bar' . DS . 'baz' . DS . 'shoe' . DS . 'horn')) {
    // Successfully created the nested folders
}

• Cake\Filesystem\Folder::delete(string $path = null)
• Recursively remove directories if the system allows:

$folder = new Folder('foo');
if ($folder->delete()) {
    // Successfully deleted foo and its nested folders
}

• Cake\Filesystem\Folder::dirsize()

• Returns the size in bytes of this Folder and its contents.

• Cake\Filesystem\Folder::errors()

• Get the error from latest method.

• Cake\Filesystem\Folder::find(string $regexpPattern = '.*', boolean $sort = false)

• Returns an array of all matching files in the current directory:

// Find all .png in your webroot/img/ folder and sort the results
$dir = new Folder(WWW_ROOT . 'img');
$files = $dir->find('.*\.png', true);
/*
Array
(
    [0] => cake.icon.png
    [1] => test-error-icon.png
    [2] => test-fail-icon.png
    [3] => test-pass-icon.png
    [4] => test-skip-icon.png
)
*/

Note

The folder find and findRecursive methods will only find files. If youwould like to get folders and files see Folder::read() orFolder::tree()

• Cake\Filesystem\Folder::findRecursive(string $pattern = '.*', boolean $sort = false)
• Returns an array of all matching files in and below the current directory:

// Recursively find files beginning with test or index
$dir = new Folder(WWW_ROOT);
$files = $dir->findRecursive('(test|index).*');
/*
Array
(
    [0] => /var/www/cake/webroot/index.php
    [1] => /var/www/cake/webroot/test.php
    [2] => /var/www/cake/webroot/img/test-skip-icon.png
    [3] => /var/www/cake/webroot/img/test-fail-icon.png
    [4] => /var/www/cake/webroot/img/test-error-icon.png
    [5] => /var/www/cake/webroot/img/test-pass-icon.png
)
*/

• Cake\Filesystem\Folder::inCakePath(string $path = '')

• Returns true if the file is in a given CakePath.

• Cake\Filesystem\Folder::inPath(string $path = '', boolean $reverse = false)

• Returns true if the file is in the given path:

$Folder = new Folder(WWW_ROOT);
$result = $Folder->inPath(APP);
// $result = false, /var/www/example/src/ is not in /var/www/example/webroot/
 
$result = $Folder->inPath(WWW_ROOT . 'img' . DS, true);
// $result = true, /var/www/example/webroot/img/ is in /var/www/example/webroot/

• static Cake\Filesystem\Folder::isAbsolute(string $path)

• Returns true if the given $path is an absolute path.

• static Cake\Filesystem\Folder::isSlashTerm(string $path)

• Returns true if given $path ends in a slash (i.e. is slash-terminated):

$result = Folder::isSlashTerm('/my/test/path');
// $result = false
$result = Folder::isSlashTerm('/my/test/path/');
// $result = true

• static Cake\Filesystem\Folder::isWindowsPath(string $path)

• Returns true if the given $path is a Windows path.

• Cake\Filesystem\Folder::messages()

• Get the messages from the latest method.

• Cake\Filesystem\Folder::move(array $options)

• Recursive directory move.

• static Cake\Filesystem\Folder::normalizeFullPath(string $path)

• Returns a path with slashes normalized for the operating system.

New in version 3.7.0.

• Cake\Filesystem\Folder::pwd()

• Return current path.

• Cake\Filesystem\Folder::read(boolean $sort = true, array|boolean $exceptions = false, boolean $fullPath = false)

• Returns an array of the contents of the current directory. Thereturned array holds two sub arrays: One of directories and one of files:

$dir = new Folder(WWW_ROOT);
$files = $dir->read(true, ['files', 'index.php']);
/*
Array
(
    [0] => Array // Folders
        (
            [0] => css
            [1] => img
            [2] => js
        )
    [1] => Array // Files
        (
            [0] => .htaccess
            [1] => favicon.ico
            [2] => test.php
        )
)
*/

• Cake\Filesystem\Folder::realpath(string $path)

• Get the real path (taking “..” and such into account).

• static Cake\Filesystem\Folder::slashTerm(string $path)

• Returns $path with added terminating slash (corrected forWindows or other OS).

• Cake\Filesystem\Folder::tree(null|string $path = null, array|boolean $exceptions = true, null|string $type = null)

• Returns an array of nested directories and files in each directory.

File API

• class Cake\Filesystem\File(string $path, boolean $create = false, integer $mode = 755)

// Create a new file with 0644 permissions
$file = new File('/path/to/file.php', true, 0644);

• property Cake\Filesystem\File::$Folder

• The Folder object of the file.

• property Cake\Filesystem\File::$name

• The name of the file with the extension. Differs fromFile::name() which returns the name without the extension.

• property Cake\Filesystem\File::$info

• An array of file info. Use File::info() instead.

• property Cake\Filesystem\File::$handle

• Holds the file handler resource if the file is opened.

• property Cake\Filesystem\File::$lock

• Enable locking for file reading and writing.

• property Cake\Filesystem\File::$path

• The current file’s absolute path.

• Cake\Filesystem\File::append(string $data, boolean $force = false)

• Append the given data string to the current file.

• Cake\Filesystem\File::close()

• Closes the current file if it is opened.

• Cake\Filesystem\File::copy(string $dest, boolean $overwrite = true)

• Copy the file to the absolute path $dest.

• Cake\Filesystem\File::create()

• Creates the file.

• Cake\Filesystem\File::delete()

• Deletes the file.

• Cake\Filesystem\File::executable()

• Returns true if the file is executable.

• Cake\Filesystem\File::exists()

• Returns true if the file exists.

• Cake\Filesystem\File::ext()

• Returns the file extension.

• Cake\Filesystem\File::Folder()

• Returns the current folder.

• Cake\Filesystem\File::group()

• Returns the file’s group, or false in case of an error.

• Cake\Filesystem\File::info()

• Returns the file info.

• Cake\Filesystem\File::lastAccess()

• Returns last access time.

• Cake\Filesystem\File::lastChange()

• Returns last modified time, or false in case of an error.

• Cake\Filesystem\File::md5(integer|boolean $maxsize = 5)

• Get the MD5 Checksum of file with previous check of filesize,or false in case of an error.

• Cake\Filesystem\File::name()

• Returns the file name without extension.

• Cake\Filesystem\File::offset(integer|boolean $offset = false, integer $seek = 0)

• Sets or gets the offset for the currently opened file.

• Cake\Filesystem\File::open(string $mode = 'r', boolean $force = false)

• Opens the current file with the given $mode.

• Cake\Filesystem\File::owner()

• Returns the file’s owner.

• Cake\Filesystem\File::perms()

• Returns the “chmod” (permissions) of the file.

• static Cake\Filesystem\File::prepare(string $data, boolean $forceWindows = false)

• Prepares a ascii string for writing. Converts line endings to thecorrect terminator for the current platform. For Windows “\r\n”will be used, “\n” for all other platforms.

• Cake\Filesystem\File::pwd()

• Returns the full path of the file.

• Cake\Filesystem\File::read(string $bytes = false, string $mode = 'rb', boolean $force = false)

• Return the contents of the current file as a string or return false on failure.

• Cake\Filesystem\File::readable()

• Returns true if the file is readable.

• Cake\Filesystem\File::safe(string $name = null, string $ext = null)

• Makes filename safe for saving.

• Cake\Filesystem\File::size()

• Returns the filesize in bytes.

• Cake\Filesystem\File::writable()

• Returns true if the file is writable.

• Cake\Filesystem\File::write(string $data, string $mode = 'w', boolean$force = false)

• Write given data to the current file.

• Cake\Filesystem\File::mime()

• Get the file’s mimetype, returns false on failure.

• Cake\Filesystem\File::replaceText($search, $replace)

• Replaces text in a file. Returns false on failure and true on success.