vfsStream

Today we released vfsStream 0.11.1 which contains an important bugfix for usages of mkdir(). Until 0.11.1 calls to mkdir() with vfsStream URLs replace already existing directories or files, instead of returning false and trigger a warning. This has been fixed with 0.11.1. Thanks to Julien Fontanet for reporting the issue.

As always you can get the new release via our pear channel.

Some minutes ago vfsStream 0.11.0 was released with several bug fixes and new features. Unfortunately this introduces a BC break to the vfsStream::create() method introduced with 0.10.0. While in 0.10.0 it completely replaced the directory structure this is not the case any more. It now only adds the given structure to an existing structure, either to the directory given with the second parameter, or to the root directory without removing any other childs of the root directory. If you want to replace the whole directory tree you can use the vfsStream::setup() method which now has a third parameter. See create complex directory structures documentation for code examples.

Another new feature is the possibility to import a file system structure from disc into vfsStream. This way you can emulate an existing file structure in vfsStream without having to recreate it from scratch. See copy from file system documentation for more details.

Additionally, three bugs were fixed: unlink() does not remove non-empty directory any more, vfsStreamDirectory::hasChild() now doesn't give false positives for nested paths (patch provided by Andrew Coulton), and opening a file for reading only doesn't update the modification time any more (initial patch provided by Ludovic Chabant).

Thanks to all contributors and issue reporters for their help to improve vfsStream.

As always you can get the new release via our pear channel.

Today vfsStream 0.10.1 has been released, containing two bug fixes. The first was a problem with the vfsStream::create() functionality introduced with 0.10.0, where using numeric directories failed because of implicit type conversions (in PHP) and explicit type checks (in vfsStream). Thanks to Mathieu Kooiman for finding this issue and providing a patch.

The other fix is a mix of a documentation and type hinting fix: now you can only use directories as root instance - before it was allowed to add files as vfsStream root with with vfsStreamWrapper::setRoot(), however this failed latest when trying to access other files with a directory name. Starting with 0.10.1 you can not add files as root any more, and this was also used to change the return type documentation so you can get better auto completion when retrieving a directory object with vfsStreamWrapper::getRoot(). Thanks to Dmitry Kabanov for reporting this issue.

As always you can get the new release via our pear channel.

Not even ten days after the release of vfsStream 0.9.0 today the fresh version 0.10.0 hits the streets, containing various improvements to make your life with vfsStream much easier. Especially when you want to create more than just two or three files it's really noisy to create the directory structure. To ease this vfsStream now provides a vfsStream::create() method which accepts an array and builds the directory structure from it. See create complex directory structures for more details.

Another improvement is that vfsStream now supports flock() meaning that you can call flock() with a vfsStream file url and afterwards check the file instance whether the lock was set correctly. Another requested feature was the possibility to print out directory structures, but I had the idea of providing even more possibilities on what you could do when inspecting the directory structure. For a more detailed view on what this new feature provides check the wiki page about Visitors.

Also this release introduces a BC break. As announced with 0.9.0 the then deprecated method vfsStreamContent::setFilemtime() was removed now - please use fsStreamContent::lastModified() instead.

In order to ensure better compatibility between PHP 5.2 and 5.3 calling support for stream_set_blocking(), stream_set_timeout() and stream_set_write_buffer() on 5.3 was added. However calls with these functions always return false and do not have any influence on vfsStream, which is rather because concrete usage scenarios are a bit unclear at the moment. If you have any ideas or feature requests on how vfsStream should treat such calls feel free to add your comments on issue #15.

You can get the new release via our pear channel.

Today the new 0.9.0 release of vfsStream was shipped to our PEAR channel. This release ships with a new feature that allows (unit) test scenarios which make use of file access time and file attribute modification time. While there is no restriction on usage of the file access time, support for file attribute modification time is still quite limited due to the fact that PHP's stream wrapper do not support changing file attributes via chmod(), chown() and chgrp(). However, this might change with PHP 5.4 but this is some month away from today.

Another issue fixed (well, kind of) is the problem that calls to stream_select() with vfsStream-URLs did not cause problems with PHP 5.2 but with 5.3 - this release makes sure that vfsStream behaves the same under both versions. Unfortunately it continues that stream_select() does not work with vfsStream-URLs as the only possible implementation of the stream_cast() method was to return false. Actually it is expected to return the underlying resource, but there is no such resource in vfsStream, and returning resources pointing to data:// scheme URLs does not work either.

More changes are the deprecation of the vfsStreamAbstractContent::setFilemtime() method in favor of vfsStreamAbstractContent::lastModified(), which means the aforementioned is scheduled to be removed with the next minor release (most likely 0.10.0). You should change your code accordingly if you make use of this method. Last but not least there was a bug that not all given URLs were resolved correctly, leading to the problem that in the second parameter of rename() and in mkdir() no dots could be used, which is fixed now.

You can get the new release via our pear channel.

By the way, did you notice that development of vfsStream has moved to Github?

With the release of vfsStream 0.8.0 the status is now beta instead of alpha as it was before. New features include a umask simulation which allows you to set a umask for vfsStream URLs which is then applied for new directories and files, except if you explicitly set the permissions of a file or directory using the vfsStream API. To be backward compatible and easier to use the default umask is 0000 - so if you are not interested in using this feature just don't use it and everything stays at it is.

Another new feature is the support of .. in URLs, provided via patch by Guislain Duthieuw, which means you can now have constructs like vfs://root/path/../otherpath which is mapped to vfs://root/otherpath. However, realpath() still doesn't work - there is no way to make this work with how realpath() is currently implemented in PHP itself.

Besides this two bugs have been fixed, one where it was impossible until now to access a child of a directory via the vfsStream API if the child name is contained in the parent's name. The other one was an incomplete error message when you tried to access non-existing files on the root level.

You can get the new release via our pear channel.

As promised in my talk about vfsStream at the International PHP Conference Spring Edition last week (see slides on slideshare) I released vfsStream 0.7.0 today. This release features two additions: an improvement for support of file permissions resulting from a bug fix, and an API improvement for simpler setups of test cases using vfsStream.

The improved file permissions support now respects file permissions when you access files and/or directories. Until now it was possible to write into a non-writable file or to read from a non-readable file. This is not possible any more, vfsStream enforces file permissions now in every situation. This allows you to create tests to check how your application responds if it does not have correct file permissions on a directory, for example. Please test this change, I'm not sure I got it completely right.

With the API improvement it becomes much simpler to write the setup method for test cases using vfsStream. Before 0.7.0 you had to write something like this:
vfsStreamWrapper::register(); vfsStreamWrapper::setRoot(vfsStream::newDirectory('root'));

Starting with 0.7.0 this can be simplified into a single method call:
vfsStream::setup();
Still you can have all the flexibility you need. The vfsStream::setup() has the same arguments as vfsStream::newDirectory(), namely name and permissions for the new directory, defaulting to 'root' and 0777. Additionally, the method returns the newly created root directory so that you can use it to do further adjustments as required.

If you like the new additions get the new release.

Seldom in a life of a developer it comes to the point where a bug can be fixed by a feature addition. This February, it happend to vfsStream. A user reported a bug where overwriting an existing vfsStream file with new but smaller content replaced only portions of the file, leaving the rest in place instead of truncating the old content before writing the fresh content. After some investigation it turned out the best fix for the problem was to implement the long scheduled feature issue 7. Thought, said, done. So today I shipped vfsStream 0.6.0 including complete support for for $mode param when opening files.

While I was at it, I added support for the $options param as well, it now evaluates whether STREAM_REPORT_ERRORS is set and acts accordingly when opening a file.

Unfortunately there are bad news as well. Due to another issue I found out that ext/zip does not work with vfsStream, and that there is no way to add support for it in vfsStream. Maybe if someone with slightly more C skills than me (which are equal to zero) might want to look into this problem for a better explanation, as I can only assume that it's due to ext/zip not supporting userland stream wrappers.

If you like the new additions get the new release.

Today I shipped vfsStream 0.5.0 which brings a new feature thanks to the efforts of Benoit Aubuchon: vfsStream now supports the rename() functionality which allows you to write test cases using vfsStream for methods that rename files. Another patch of him was to change the stat() call to respect the STREAM_URL_STAT_QUIET flag.

One more new feature is the added support for . as current directory alias so that vfs://foo/. resolves to vfs://foo - this allows to use file_exists($dir . '/.') as workaround for the failing is_executable() call on directories, as described in the comments to the is_executable() documentation in the PHP manual. Of course this raises the question if vfsStream will support .. as well - if somebody takes the time to create a patch I will incorporate this. I did not look into this issue further, but I guess it might involve recursion and a more advanced parsing of the vfs URL to make it work properly, as there might be cases like vfs://foo/bar/baz/../../dummy.

So grab the release and make use of the new features, if you like to.

Some minutes ago I released vfsStream 0.4.0, introducing support for file modes, owners and groups. While I planned to implement this at least since a year it took me three tries to get it implemented, and while implementing this I stumbled about some issues which can not be solved by vfsStream. Major problem is that the PHP functions chmod(), chown() and chgrp() do not work with vfsStream URLs due to limitations imposed by PHP (or possibly by underlying C, not sure). The stream wrapper API has no support to enable setting file modes, owner or group of a userland stream implementation. This means the usage of file mode support is limited and can not be applied to create tests for classes using one of the three functions. However, it is still possible to use file modes for testing correct usage of is_readable(), is_writable() and is_executable(). Another usage scenario is to make sure directories created with mkdir() receive the correct file mode, see the file mode example. I'm sure users will come up with other usage scenarios I did not even thought of.

Beside this new feature the release contains a bugfix for vfsStreamDirectory::addChild() to make sure adding another child of the same name as an existing child replaces this existing child, and a fix to return correct results for stat() calls. Grab the release via it's pear channel pear.php-tools.net and try it out. I suspect the file mode support may contain bugs because I did not have the time to use it in other projects, but after all, it is still in alpha stage.

The current issue of the german PHP magazine features an article about vfsStream. On three pages Mike Wittje (I hope this is the correct Mike, just guessed ) describes how vfsStream can be used to simplify and improve unit tests for classes utilizing the file system and file system functions. Thanks to Mike for writing the article, helping to spread the word about vfsStream.

Over the weekend I'm going to test vfsStream with PHP 5.3 and try to fix any issues which pop up. I already received a patch by mail which is said to fix an issue with is_readable() (not tested yet), so it seems reasonable there will be a new release within the upcoming days.

Nearly about a year passed since the last release of vfsStream, and some bugs were found by users of vfsStream. This was quite a surprise for me since I did not expect that anybody would use it.
This evening I fixed another bug reported some days ago, and since a patch for another bug was submitted and committed about half a year ago I decided to release version 0.3.2 tonight, so these are the changes:

- added support for trailing slashes on directories in vfsStream urls, patch provided by Gabriel Birke
- fixed bug #4: vfsstream can only be read once, reported by Christoph Bloemer
- enabled multiple iterations at the same time over the same directory

A big thank you to the bug reporters for their help to improve vfsStream. This should give me some motivation to go for 0.4.0 and implement support for file modes, at least being able to store and read them - full file mode support will be a hell of a work, not sure if it is worth the effort.

Against my intent of starting to work on file modes for 0.3.0 I decided that it is time to get an own repository for vfsStream in order to maintain it independently from Stubbles, which was the perfect reason to open a new project on Google Code. I will see if this proves to be a good solution for day to day development.

The movement also marked the reason to try PHPUnit because I wanted to make use of its code coverage and its software metrics features. Especially the last one showed me a bunch of points that required refactoring before starting something big like supporting file modes. During refactoring some improvements made it into the code which justified a new release: vfsStream now supports rmdir(), and I made some API changes. I dropped vfsStreamDirectory::ceate() in favor of vfsStream::newDirectory() to be equivalent to vfsStream::newFile(). Additionally there is a new vfsStreamContent::at() method now, which allows to write code like this:
$parentDir = vfsStream::newDirectory('newdir')->at(vfsStreamWrapper::getRoot()); $file = vfsStream::newFile('file.txt')->withContent('foo') ->lastModified(time() - 86400) ->at($parentDir);

So far I'm very satisfied with the software analysis features of PHPUnit that I'm thinking very hard about saying good bye to SimpleTest in my other projects. Given the current state of SimpleTest's development I do not expect to get similar features in SimpleTest any time soon, and unfortunately I do not have the time to contribute to SimpleTest even if it would be a lot of fun I guess.

Having done more work on vfsStream I felt it is time to do the next release before starting to work on the next big issue™. The new 0.2.0 release focuses on API improvements as well as support for differentiating between directories and files. API improvements are a new vfsStream::url() method to assist in creating correct vfsStream urls. Up until now you had to write something like
$url = vfsStreamWrapper::PROTOCOL . '://path/to/file.txt';
which is kind of ugly and unhandy to type. Now you can do
$url = vfsStream::url('path/to/file.txt'); which should be easier and less to type.
Another API improvement is the new vfsStream::newFile() method to be able to do
$file = vfsStream::newFile("foo.txt")->withContent("bar");
Following an advice by David Zülke I changed vfsStreamWrapper::register() to reset the directory root to null.

Additionally vfsStream now supports is_dir(), is_file() and is_readable(). However there is still a small drawback to is_readable(), as long as file mode is not supported existing pathes will lead to true, and non-existing pathes to false. Currently all files and directories always have 0777 as file mode. As I require support for file modes now this will be part of the 0.3.0 release.

Another thing I found during the last days is that realpath() seems only to work with real files, but not with any other URL types. That's a bit sad because it means one can not use this function if one wants to test its file operations with vfsStream.

Some minutes ago I released the first version of vfsStream. vfsStream is a stream wrapper for a virtual file system that may be helpful in unit tests to mock the real file system. It can be used with any unit test framework, like PHPUnit or SimpleTest.

The first idea for this came up when I prepared my talk about stream wrappers for the PHP conference in Frankfurt-Mörfelden earlier this year (slides still available). Everybody knows that you should not use real databases in unit tests, so why should one use the real file system? Of course you can create an IO abstraction layer, but PHP offers such easy access to file contents via its file_get_content() and file_put_content() functions as well as with its other file system functions that it would be a bit overdone to create such a layer just for testing purposes. Additionally there are stream wrappers which allow you to create your own protocol and use it with exactly this file functions.

This was the point where I started thinking about it, so hacked together a first version as a prove-of-concept. Because it worked like a charm I started to use it in my own unit tests, which already saved me some time and problems. Today I decided it is time to release this as open source to the public to see if other people like the idea and have a use for it, therefore I did some refactorings, and did a first release. Unfortunately not everything works by now: It is currently not possible to rename a file or directory, and it is not possible to remove directories. Additionally file modes are completely ignored. The main reason for this is that I did not need one of this features until now. Feel free to send patches, wait until I have a need for it or beg me to implement them.