Folder & File

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.

Deprecated since version 4.0: The File and Folder classes will be removed in 5.0

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 .php files within that folder using regex:

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

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.

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.