Revision: Tue, 02 Nov 2021 18:17:51 GMT

Files and Directories

The framework provides a simple component to work with the filesystem. The component is available in all of the application bundles.

Directory Registry

Most of the spiral components rely on the directory registry instead of hard-coded paths. The registry represented using Spiral\Boot\DirectoriesInterface.

You can configure application specific directories in the app entry point (app.php):

$app = \App\App::init([
    'root'      => __DIR__,
    'customDir' => __DIR__ . '/custom'

Or using the Bootloader:

namespace App\Bootloader;

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Boot\DirectoriesInterface;

class AppBootloader extends Bootloader
    public function boot(DirectoriesInterface $directories)
            $directories->get('root') . '/custom'

To access the directory paths:

namespace App\Controller;

use Spiral\Boot\DirectoriesInterface;

class HomeController
    public function index(DirectoriesInterface $dirs)


You can also use the short function directory inside your config files. Note, this function does not work outside of the framework as it relies on the global container scope.


Use the Spiral\Files\FilesInterface component to work with the filesystem:

namespace App\Controller;

use Spiral\Files\FilesInterface;

class HomeController
    public function index(FilesInterface $files)
        // get all files from root directory recursively

You can also access this instance using prototyped property files:

namespace App\Controller;

use Spiral\Prototype\Traits\PrototypeTrait;

class HomeController
    use PrototypeTrait;

    public function index()
        dump($this->files->exists(__FILE__)); // true

Create Directory

To ensure that given directory exists use method ensureDirectory, the second argument accepts the access permission:

namespace App\Controller;

use Spiral\Boot\DirectoriesInterface;
use Spiral\Files\FilesInterface;
use Spiral\Prototype\Traits\PrototypeTrait;

class HomeController
    use PrototypeTrait;

    public function index(DirectoriesInterface $dirs)
            FilesInterface::READONLY // or FilesInterface::RUNTIME for editable dirs and files

To check if directory exists:


Delete Directory

To delete directory and its content:


To delete directory content only:

$files->deleteDirectory('custom', true);

File Stats

To check if file exists:

dump($files->exists(__FILE__)); // bool

To get file creation/update time:

dump($files->time(__FILE__)); // unix timestamp

To get file MD5:


To get filename extension:

dump($files->extension(__FILE__)); // without leading "."

To check if path is file:


To get file size:



To get file/directory permissions:

dump($files->getPermissions(__FILE__)); // int

To set file permissions:

$files->setPermissions(__FILE__, 0777)

Use constants to control file mode:

Constant Value
FilesInterface::READONLY 644
FilesInterface::RUNTIME 666

Move and Copy

To copy file from one path to another:

$files->copy('old-path', 'new-path');

To move file:

$files->move('old-path', 'new-path');

Temporary Files

To issue temporary filename:


To issue temporary filename with a specific extension:


To issue temporary filename in a specific location:

dump($files->tempFilename('php', __DIR__));

Read and Write operations

The component provides multiple methods to operate with file content in an atomic way (without acquiring the file resource):

Write/Create file

To write the content to the file (exclusive lock):

$files->write('filename', 'data');

To write/create file and ensure proper access mode:

$files->write('filename', 'data', 0777);

To check and automatically create the file directory:

$files->write('filename', 'data', 0777, true);

Make sure to handle Spiral\Files\Exception\WriteErrorException if the file can is not writable.

Append Content

To append file content:

$files->append('filename', 'data');

To append and ensure file mode:

$files->append('filename', 'data', 0777);

To append/create file and ensure that target directory exists:

$files->append('filename', 'data', 0777, true);


To touch the file and create it if missing:


To touch file and ensure file mode:

$files->touch('filename', 0777);

Read the file

To read file content:


Make sure to handle Spiral\Files\Exception\FileNotFoundException when files not found.

Edit this page