adlawson/php-vfs

Virtual File System

VFS (Virtual File System)

VFS is a virtual file system for PHP built using the stream wrapper API. Streams are exposed just as typical file:// or http:// streams are to PHP's built-in functions and keywords like fopen and require. This implementation attempts to stay true to the typical streams, including triggering warnings and handling edge cases appropriately.

It can be installed in whichever way you prefer, but I recommend Composer.

{
    "require": {
        "adlawson/vfs": "*"
    }
}

Documentation

After creating and mounting the file system, you have the option of manipulating the virtual file system either via PHP's built-in functions, the VFS interfaces, or interfaces provided by another file system library.

<?php
use Vfs\FileSystem;
use Vfs\Node\Directory;
use Vfs\Node\File;

// Create and mount the file system
$fs = FileSystem::factory('vfs://');
$fs->mount();

// Add `/foo` and `/foo/bar.txt`
$foo = new Directory(['bar.txt' => new File('Hello, World!')]);
$fs->get('/')->add('foo', $foo);

// Get contents of `/foo/bar.txt`
$fs->get('/foo/bar.txt')->getContent(); // Hello, World!
file_get_contents('vfs://foo/bar.txt'); // Hello, World!

// Add `/foo/bar` and `/foo/bar/baz.php`
mkdir('vfs://foo/bar');
file_put_contents('vfs://foo/bar.php', '<?php echo "Hello, World!";');

// Require `/foo/bar.php`
require 'vfs://foo/baz.php';

// Works with any other file system library too
$symfony = new Symfony\Component\Filesystem\Filesystem();
$symfony->mkdir('vfs://foo/bar/baz');
$laravel = new Illuminate\Filesystem();
$laravel->isDirectory('vfs://foo/bar/baz'); //true

// Triggers PHP warnings on error just like typical streams
rename('vfs://path/to/nowhere', 'vfs://path/to/somewhere');
// PHP Warning: rename(vfs://path/to/nowhere,vfs://path/to/somewhere): No such file or directory in /srv/index.php on line 1; triggered in /srv/src/Logger/PhpErrorLogger.php on line 32

Example use cases

If you need to ask what you'd use a virtual file system for, you probably don't need one, but just in case, I've compiled a small list of examples:

• Testing file system libraries without writing to disc
• Runtime evaluation without eval (via write and require)
• ...we need some more!

Todo

Current tasks are listed on the github issues page, but some are listed here for reference:

• Symlinks
• File locks
• Permissions/ACL

Contributing

Contributions are accepted via Pull Request, but passing unit tests must be included before it will be considered for merge.

$ curl -O https://raw.githubusercontent.com/adlawson/vagrantfiles/master/php/Vagrantfile
$ vagrant up
$ vagrant ssh
...

$ cd /srv
$ composer install
$ vendor/bin/phpunit

License

The content of this library is released under the MIT License by Andrew Lawson.
You can find a copy of this license in LICENSE or at http://opensource.org/licenses/mit.

php-vfs's Issues

Handle open mode (and modifier) not always considered

Some of the time, especially when opening a file/directory handle, the open mode is taken into account (w vs w+ vs xt etc). The mode and modifier both need to be taken into account when reading/writing/deleting handles.

File locking

It's not currently possible to create file locks with flock (or by any other means for that matter). This needs to be sorted.

Gif

Where is that awesome gif from?

Implement symlinks

Some of the work is already in place to support symlinks (LinkInterface for example) but the concrete implementation isn't yet defined.

Add tests (passing or otherwise) to cover virtual SQLite DBs

There's some uncertainty as to whether PHPs PDO or SQLite, etc drivers support streams other than the default sqlite:/

Add changelog

Changes at this stage are sometimes quite large. Good thing is that not many people use this library so I can get away with it for now but I should really add a useful changelog.

PHP function is_dir() does not work with vfs.php

Seems like is_dir() does not work with a virtual directory. My guess is something is not completely correct with the value of $directory->getMode(), but I'm not sure.

Test case to reproduce the issue

<?php

namespace Vfs;

use Vfs\Node\Directory;
use Vfs\Node\File;

class PHPFileFunctionsTest extends \PHPUnit_Framework_TestCase
{
    const SCHEME = 'foobar://';

    /**
     * @var FileSystem
     */
    private $fs;

    public function setUp()
    {
        $fs = FileSystem::factory( self::SCHEME );

        $someDir = new Directory( array( 'file' => new File( 'foobar' ) ) );

        $fs->get( '/' )->add( 'some_dir', $someDir );

        $this->fs = $fs;
    }

    public function tearDown()
    {
        $this->fs->unmount();

        unset( $this->fs );
    }

    public function testFileGetContentsWorks()
    {
        $path = self::SCHEME . 'some_dir/file';

        $this->assertEquals( 'foobar', file_get_contents( $path ) );
    }

    public function testIsDirWorks()
    {
        $path = self::SCHEME . 'some_dir';

        $this->assertTrue( is_dir( $path ) );
    }
}

Output from running PHPUnit:

There was 1 failure:

1) Vfs\PHPFileFunctionsTest::testIsDirWorks
Failed asserting that false is true.

/home/vagrant/src/github/vfs.php/test/unit/PHPFileFunctionsTest.php:46

FAILURES!
Tests: 163, Assertions: 379, Failures: 1.

`is_readable` returns false

Trying basic code from example, but is_readable() returns false, while file_get_contents() returns contents without problems. I assume this is because it's stream and looks like is_readable() returns false for streams.

Any idea/workaround for this?

Can VFS be used as sandbox FS for a shell like app?

Is it possible to use this as file system for JSON-RPC where client is command line app in a browser? Or this FS vanish when the script end. Is it possilbe to save reference to VFS in a $_SESSION?

File permissions / ACL

Files (and directories) are all currently created with 0777 type permissions (see src/Stream/FileHandle.php#L30).