The Filesystem Component

The Filesystem component provides basic utilities for the filesystem.

Installation

$ composer require symfony/filesystem

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Usage

The Filesystem class is the uniqueendpoint for filesystem operations:

use Symfony\Component\Filesystem\Exception\IOExceptionInterface;
use Symfony\Component\Filesystem\Filesystem;
 
$filesystem = new Filesystem();
 
try {
    $filesystem->mkdir(sys_get_temp_dir().'/'.random_int(0, 1000));
} catch (IOExceptionInterface $exception) {
    echo "An error occurred while creating your directory at ".$exception->getPath();
}

Note

Methods mkdir(),exists(),touch(),remove(),chmod(),chown() andchgrp() can receive astring, an array or any object implementing Traversable asthe target argument.

mkdir

mkdir() creates a directory recursively.On POSIX filesystems, directories are created with a default mode value0777. You can use the second argument to set your own mode:

$filesystem->mkdir('/tmp/photos', 0700);

Note

You can pass an array or any Traversable object as the firstargument.

Note

This function ignores already existing directories.

Note

The directory permissions are affected by the current umask.Set the umask for your webserver, use PHP's umaskfunction or use the chmod function after thedirectory has been created.

exists

exists() checks for thepresence of one or more files or directories and returns false if any ofthem is missing:

// if this absolute directory exists, returns true
$filesystem->exists('/tmp/photos');
 
// if rabbit.jpg exists and bottle.png does not exist, returns false
// non-absolute paths are relative to the directory where the running PHP script is stored
$filesystem->exists(['rabbit.jpg', 'bottle.png']);

Note

You can pass an array or any Traversable object as the firstargument.

copy

copy() makes a copy of asingle file (use mirror() tocopy directories). If the target already exists, the file is copied only if thesource modification date is later than the target. This behavior can be overriddenby the third boolean argument:

// works only if image-ICC has been modified after image.jpg
$filesystem->copy('image-ICC.jpg', 'image.jpg');
 
// image.jpg will be overridden
$filesystem->copy('image-ICC.jpg', 'image.jpg', true);

touch

touch() sets access andmodification time for a file. The current time is used by default. You can setyour own with the second argument. The third argument is the access time:

// sets modification time to the current timestamp
$filesystem->touch('file.txt');
// sets modification time 10 seconds in the future
$filesystem->touch('file.txt', time() + 10);
// sets access time 10 seconds in the past
$filesystem->touch('file.txt', time(), time() - 10);

Note

You can pass an array or any Traversable object as the firstargument.

chown

chown() changes the owner ofa file. The third argument is a boolean recursive option:

// sets the owner of the lolcat video to www-data
$filesystem->chown('lolcat.mp4', 'www-data');
// changes the owner of the video directory recursively
$filesystem->chown('/video', 'www-data', true);

Note

You can pass an array or any Traversable object as the firstargument.

chgrp

chgrp() changes the group ofa file. The third argument is a boolean recursive option:

// sets the group of the lolcat video to nginx
$filesystem->chgrp('lolcat.mp4', 'nginx');
// changes the group of the video directory recursively
$filesystem->chgrp('/video', 'nginx', true);

Note

You can pass an array or any Traversable object as the firstargument.

chmod

chmod() changes the mode orpermissions of a file. The fourth argument is a boolean recursive option:

// sets the mode of the video to 0600
$filesystem->chmod('video.ogg', 0600);
// changes the mod of the src directory recursively
$filesystem->chmod('src', 0700, 0000, true);

Note

You can pass an array or any Traversable object as the firstargument.

remove

remove() deletes files,directories and symlinks:

$filesystem->remove(['symlink', '/path/to/directory', 'activity.log']);

Note

You can pass an array or any Traversable object as the firstargument.

rename

rename() changes the nameof a single file or directory:

// renames a file
$filesystem->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
// renames a directory
$filesystem->rename('/tmp/files', '/path/to/store/files');

symlink

symlink() creates asymbolic link from the target to the destination. If the filesystem does notsupport symbolic links, a third boolean argument is available:

// creates a symbolic link
$filesystem->symlink('/path/to/source', '/path/to/destination');
// duplicates the source directory if the filesystem
// does not support symbolic links
$filesystem->symlink('/path/to/source', '/path/to/destination', true);

readlink

readlink() read links targets.

PHP's readlink() function returns the target of a symbolic link. However, its behavioris completely different under Windows and Unix. On Windows systems, readlink()resolves recursively the children links of a link until a final target is found. OnUnix-based systems readlink() only resolves the next link.

The readlink() method providedby the Filesystem component always behaves in the same way:

// returns the next direct target of the link without considering the existence of the target
$filesystem->readlink('/path/to/link');
 
// returns its absolute fully resolved final version of the target (if there are nested links, they are resolved)
$filesystem->readlink('/path/to/link', true);

Its behavior is the following:

public function readlink($path, $canonicalize = false)

• • When $canonicalize is false:
  • • if $path does not exist or is not a link, it returns null.
    • if $path is a link, it returns the next direct target of the link without considering the existence of the target.
• • When $canonicalize is true:
  • • if $path does not exist, it returns null.
    • if $path exists, it returns its absolute fully resolved final version.

makePathRelative

makePathRelative() takes twoabsolute paths and returns the relative path from the second path to the first one:

// returns '../'
$filesystem->makePathRelative(
    '/var/lib/symfony/src/Symfony/',
    '/var/lib/symfony/src/Symfony/Component'
);
// returns 'videos/'
$filesystem->makePathRelative('/tmp/videos', '/tmp')

mirror

mirror() copies all thecontents of the source directory into the target one (use thecopy() method to copy singlefiles):

$filesystem->mirror('/path/to/source', '/path/to/target');

isAbsolutePath

isAbsolutePath() returnstrue if the given path is absolute, false otherwise:

// returns true
$filesystem->isAbsolutePath('/tmp');
// returns true
$filesystem->isAbsolutePath('c:\\Windows');
// returns false
$filesystem->isAbsolutePath('tmp');
// returns false
$filesystem->isAbsolutePath('../dir');

tempnam

tempnam() creates a temporary file with a unique filename, and returns its path, or throw an exception on failure:

// returns a path like : /tmp/prefix_wyjgtF
$filesystem->tempnam('/tmp', 'prefix_');

dumpFile

dumpFile() saves the givencontents into a file. It does this in an atomic manner: it writes a temporaryfile first and then moves it to the new file location when it's finished.This means that the user will always see either the complete old file orcomplete new file (but never a partially-written file):

$filesystem->dumpFile('file.txt', 'Hello World');

The file.txt file contains Hello World now.

appendToFile

appendToFile() adds newcontents at the end of some file:

$filesystem->appendToFile('logs.txt', 'Email sent to [email protected]');

If either the file or its containing directory doesn't exist, this methodcreates them before appending the contents.

Error Handling

Whenever something wrong happens, an exception implementingExceptionInterface orIOExceptionInterface is thrown.

Note

An IOException isthrown if directory creation fails.