README

The Themosis filesystem component is a wrapper around PHP filesystem functions.

The library provides a Filesystem interface as well as a concrete LocalFilesystem implementation.

The LocalFilesystem class can only be used to manage “local” files. If you need to deal with remote files, you will need to provide your own implementation of the Filesystem interface.

Installation

Install the library using Composer:

composer require themosis/filesystem

Usage

If you’re using this package to manage files in your application. We recommend to reference the Filesystem interface in your code instead of the concrete implementation.

Only pass one of the package implementation filesystem class when instantiating a client object that requires a Filesystem instance in order to work.

For example:

<?php

use Themosis\Components\Filesystem\Filesystem;
use Themosis\Components\Filesystem\LocalFilesystem;

//Instead of writing this class declaration...
class Application
{
    public function __construct(
        private LocalFilesystem $filesystem,
    ) {}
}

// Write this instead...
class Application
{
    public function __construct(
        private Filesystem $filesystem,
    ) {}
}

// When instantiating your client application:
$app = new Application(
    filesystem: new LocalFilesystem(),
);

Find below the available methods on a Filesystem instance to help you manage application files.

You can also find additional information for each concrete implementation:

LocalFilesystem

Read file content

You can read the content of any file by passing its path to the read():

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$content = $filesystem->read('/path/to/file.txt');

The local filesystem implementation is using the PHP file_get_contents() function.

The implementation is also doing some checks before and after reading the content.

For example, the method is first checking if the file exists before reading it. If the file does not exist, the method will throw a FileDoesNotExist exception.

After accessing the content, the method is checking to see if the content is actually readable. If the content is somehow corrupted, the method will throw a ReadFileException exception.

Write file content

You can wrtite content to any file by calling the write() method. Pass the path to the file as first parameter and the content as the second parameter:

use Themosis\Components\Filesystem\LocalFilesystem;

$hello = 'Hello World!';

$filesystem = new LocalFilesystem();
$filesystem->write('/path/to/file.txt' , $hello');

The local filesystem implementation is using the PHP file_put_contents() function.

If the filesystem cannot write the content on the given file, it will throw a WriteFileException exception.

Require PHP file

This is PHP specific. You can require any PHP file using the filesystem require() or requireOnce() methods.

Each one of them is leveraging the core PHP function of its name with the added option where you can pass and expose variables to the included PHP file.

First example below is just including a PHP file:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();
$filesystem->require(__DIR__ . '/includes/file-a.php');

The methods behave just like their core siblings. If the included file is returning data, it will be returned as well by the filesystem require methods:

// File A stored inside project /includes/file-a.php
<?php

return [
    'hello' => 'World!',
];

// Main file requires File A
use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();
$data = $filesystem->require(__DIR__ . '/includes/file-a.php');

In above code example, the $data variable is containing the array returned by the required file.

Passing data

When you require a file using the filesystem, you can pass data to the included file by providing an array of key/value pairs as a second parameter:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();
$filesystem->require(__DIR__ . '/includes/file-b.php', [
    'hello' => 'World!',
]);

// File B stored inside project /includes/file-b.php
<head>
    <title><?= $hello ?></title>
</head>

The `File B` in above code example, is containing HTML content and echoes the $hello variable that was passed in the require() filesystem method as a second parameter.

The API is the same when using the requireOnce() method. Watchout the returned value though.

File exists

The filesystem exposes the exists() method to let you check if a file exists:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

if ( $filesystem->exists('/path/to/file.txt')) {
    // Do something...
}

It also provides the opposite method doesNotExist() for better convenience:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

if ( $filesystem->doesNotExist('/path/to/file.txt')) {
    // Do something...
}

Check path is a file

You can verify if the given path is targeting a file using the isFile() method:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

if ( $filesystem->isFile('/path/to/file.txt')) {
    // Do something...
}

Check path is a directory

You can verify if the given path is targeting a directory using the isDirectory() method:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

if ($filesystem->isDirectory('/path/to/dir')) {
    // Do something...
}

Check path is a symlink

You can verify if the given path is targeting a symbolic link using the isLink() method:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

if ($filesystem->isLink('/path/to/symlink')) {
    // Do something...
}

Create links

You can create both hard and symbolic links using the hardlink() and symlink() methods.

Create an hard link

Use the hardlink() method to create an hard link. The first argument is the “original” path and the second argument is the “target” path, name of the link:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesytem->hardlink('/path/to/file', '/path/to/targetname');

Create a symbolic link

Use the symlink() method to create a symbolic link. Just like the hardlink method, first argument is the path to the “original” element (file, directory), and the second argument is the path to the “target” which represents the link in the filesystem:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesytem->symlink('/path/to/file', '/path/to/targetname');

Create a directory

You can create new directories by calling the makeDirectory() method:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesystem->makeDirectory('/path/to/new/directory');

If directory already exists, an exception is thrown.

You can also create a nested directory. If your directory path contains parent directories that do not yet exist, those directories are also created.

By default, the LocalFilesystem will set chmod permissions on the new directory to 777, which provides full access to it.

Set directory permissions

When creating a new directory, you can pass a Permissions parameter to limit the access to it:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesystem->makeDirectory('/path/to/new/directory', new PosixPermissions(
    ownerBits: 7,
    groupBits: 5,
    othersBits: 5,
));

Permissions can be defined into your project even if running under Windows. The permissions are ignored when the application runs on Windows.

The LocalFilesystem implementation is using the PHP mkdir() function under the hood. For details on which permissions bits to define, check documentation for the system chmod command.

Delete a link

You can delete a link, hard or symbolic, using the deleteLink() method:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesystem->deleteLink('/path/to/link');

Delete a file

In order to delete a file, call the deleteFile() method and pass the file path as the only argument:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesystem->deleteFile('/path/to/file.php');

Delete a directory

The Filesystem interface provides the deleteDirectory() method to delete directories. By default, you can only delete a directory if, and only if, it is empty. The method has two parameters:

A string representing the directory path.
A boolean value to delete directory and its content recursively. Default value is false.

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesystem->deleteDirectory('/path/to/empty/directory');

The above code snippet deletes the directory if it is empty.

Recursively delete a directory

If you are sure that you want to delete a directory and all its content, you can pass true as the second argument to the deleteDirectory() method like so:

<?php

use Themosis\Components\Filesystem\LocalFilesystem;

$filesystem = new LocalFilesystem();

$filesystem->deleteDirectory('/path/to/directory', recursive: true);

LocalFilesystem

The LocalFilesystem class is one implementation of the Filesystem interface. The class is leveraging core PHP functions to handle file related actions. As its name indicates, this class should only be used to manage a “local” filesystem (current application server,…).

Errors

When working with the LocalFilesystem instance, any error is automatically converted to a FilesystemException. This way, you have the possibility to wrap any filesystem operation between a try catch block and easily handle the issue.

<?php

// Code...
try {
    $filesystem->makeDirectory('/path/to/dir');
} catch (FilesystemException $exception) {
    // Retry or log the error...
}

themosis / filesystem

Maintainers

Details