fidry/filesystem

Symfony Filesystem with a few more utilities.

2.0.0-beta.0 2025-11-09 19:56 UTC

Requires

• php: ^8.3
• symfony/filesystem: ^6.4 || ^7.0
• symfony/finder: ^6.4 || ^7.0

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.4
• ergebnis/composer-normalize: ^2.28
• infection/infection: >=0.26
• phpunit/phpunit: ^12

BSD-3-Clause

• Théo Fidry

• filesystem

README

This is a tiny wrapper around the Symfony filesystem. It provides a FileSystem interface and a few more utilities.

FileSystemTestCase

An example of PHPUnit test:

<?php declare(strict_types=1);

namespace App;

use Fidry\FileSystem\FS;
use Fidry\FileSystem\Test\FileSystemTestCase;
use PHPUnit\Framework\Attributes\CoversClass;
use Symfony\Component\Finder\Finder;
use function getenv;
use function is_string;

final class MyAppFileSystemTest extends FileSystemTestCase
{
    // This method needs to be implemented by your test or base filesystem test class.
    public static function getTmpDirNamespace(): string
    {
        // This is to make it thread safe with Infection. If you are not using
        // infection or do not need thread safety, this can return a constant
        // string, e.g. your project/library name.
        $threadId = getenv('TEST_TOKEN');

        if (!is_string($threadId)) {
            $threadId = '';
        }

        return 'MyApp'.$threadId;
    }

    public function test_it_works(): void
    {
        // This file is dumped into a temporary directory. Here,
        // something like '/private/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/MyApp/MyAppFileSystemTest10000'
        // on OSX.
        FS::dumpFile('file1', '');
        
        $files = Finder::create()
            ->files()
            ->in($this->tmp);

        self::assertSame(['file1'], $this->normalizePaths($files));
    }
}

SplFileInfo utilities

The Symfony Finder SplFileInfo distinguish itself from \SplFileInfo in two ways:

• Files found by a finder are relative to the root directory. Hence, the relative path and pathname.
• The ::getContents() method.

Prior to Symfony 7.1, the ::getContents() method was very useful. But now the method Filesystem::readfile() is available. Note that this method was backported in this library.

However, a lot of applications may be using the Symfony Finder SplFileInfo because of it still. Whilst for the source code it makes little difference, for tests it is more annoying as it is more complicated to create a fake Symfony Finder SplFileInfo object. You will have to create a mock, which may be more or less verbose depending on how much of the SplFileInfo API is used.

To help to fill in the gap, this library provides two utilities.

SplFileInfoFactory

SplFileInfoFactory allows to easily create a real Symfony Finder SplFileInfo instance without using a Finder:

use PHPUnit\Framework\TestCase;

class DemoTest extends TestCase {

    function test_it_allows_to_compare_finder_splfileinfo_files(): void
    {
        $actual = $myService->getFileInfo();
        
        $expected = SplFileInfoFactory::fromPath('/path/to/expected', __DIR__);

        self::assertEquals($expected, $actual);
    }
}

SplFileInfoBuilder

SplFileInfoBuilder allows to easily create a fake SplFileInfo instance. It is often simpler than using a mock:

- private function createSplFileInfoMock(string $file): SplFileInfo&MockObject
+ private function createSplFileInfo(string $file): SplFileInfo
{
-    $splFileInfoMock = $this->createMock(SplFileInfo::class);
-    $splFileInfoMock->method('__toString')->willReturn($file);
-    $splFileInfoMock->method('getFilename')->willReturn($file);
-    $splFileInfoMock->method('getRealPath')->willReturn($file);
-    $splFileInfoMock->method('getContents')->willReturn(
-        file_exists($file) ? file_get_contents($file) : 'content',
-    );
-
-    return $splFileInfoMock;
+    return SplFileInfoBuilder::withTestData()
+        ->withFile($file)
+        ->withContents(
+            file_exists($file) ? file_get_contents($file) : 'content',
+        )
+        ->build();
}

ReadOnlyFileSystem

// Write operations will throw a `DomainException` exception.
new ReadOnlyFileSystem(failOnWrite: true);

// Write operations will do nothing. Methods that return a path, e.g.
// `::tempnam()` will return an empty string.
new ReadOnlyFileSystem(failOnWrite: false);

FS

A FS static class for when you are not interested of using dependency injection for your filesystem layer or for usage within tests.

FS::touch('file');

// instead of
(new NativeFileSystem)->touch('file');

Contributing

GNU Make is your friend. Try make or make help!.