README

👁 Virtual File System

👁 Master branch build status
👁 Published version
👁 PHP ~5.4
👁 MIT Licensed

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.