Folder & File
The Folder and File utilities are convenience classes to help you read from and
write/append to files; list files within a folder and other common directory
related 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 or
simply 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 same
information.
-
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 on
Windows 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 includes
changing 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 either
be 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 the
destination directory.
Folder::MERGE
merge the source/destination directories. Files in the
source directory will replace files in the target directory. Directory
contents will be merged.
Folder::OVERWRITE
overwrite existing files & directories in the target
directory with those in the source directory. If both the target and
destination contain the same subdirectory, the target directory’s contents
will be removed and replaced with the source’s.
-
static Cake\Filesystem\Folder::correctSlashFor(string $path)
Returns a correct set of slashes for given $path (’\’ for
Windows paths and ‘/’ for other paths).
-
Cake\Filesystem\Folder::create(string $pathname, integer $mode = false)
Create a directory structure recursively. Can be used to create
deep 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 you
would like to get folders and files see Folder::read()
or
Folder::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. The
returned 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 for
Windows 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 from
File::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 the
correct 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.