Add readme

README.md

@@ -0,0 +1,104 @@
+# VFS (Virtual File System)
+
+<img src="http://media.giphy.com/media/d6Unw9Ke0vCFO/giphy.gif" alt="Virtual File System" align="right" width=310/>
+
+**Master build:** [![Master branch build status][travis-master]][travis]<br/>
+**Requires:** `PHP >= 5.4 || HHVM >= 3.0`
+
+**VFS** is a virtual file system for PHP built using the stream wrapper API.
+Steams 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][packagist].
+```json
+{
+    "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
+<?php
+use Vfs\FileSystem;
+use Vfs\Node\Directory;
+use Vfs\Node\File;
+
+// Create and mount the file system
+$fs = FileSystem::factory('vfs://');
+
+// 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][gh-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.
+```bash
+$ 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**.<br/> You can find a copy of this license in
+[`LICENSE`][license] or at http://opensource.org/licenses/mit.
+
+<!-- Project links -->
+[travis]: https://travis-ci.org/adlawson/vfs.php
+[travis-master]: https://travis-ci.org/adlawson/vfs.php.png?branch=master
+[packagist]: https://packagist.org/packages/adlawson/vfs
+[gh-issues]: https://github.com/adlawson/vfs.php/issues
+
+<!-- Files -->
+[license]: /LICENSE