API Stream Wrappers – Week 12

The final week is upon us 🙂 I’ve been spending my time refining and cleaning up the code, fixing grammatical mistakes in the documentation, and other remaining loose end. I took a crack at the wiki documentation to help ease understanding of the plugin and how it fits into the WordPress ecosystem. I’m also working on getting doxygen to whip up some nice documentation which I will eventually put on the GitHub project web site until a more permanent home is found.

Come Monday (the firm pencils down date) I will tag the code and make sure Subversion is in sync. There’s still quite a bit to do before the true benefits of stream wrappers are realized, but that effort is out of the scope of this project and will continue onwards separately 😀

API Stream Wrappers – Week 11

Test coverage is over 90% and done for the most part. There are a handful of edge cases left, but those will be taken care of when I finish making a few planned tweaks. I discovered this week that xdebug sometimes reports closing brackets as unexecuted code, so code coverage will never reach 100% sadly.

I’ve started creating documentation on the GitHub wiki: http://wiki.github.com/jmstacey/wp-stream-wrappers/. It will live there until I can find a more permanent home for it to live. If you have a knack for writing documentation and styling, then shoot me an email or comment below with any tips, suggestions to make the documentation more beneficial than just reading the code (even though the code is well documented if I were to judge :-)).

Download the latest Snapshot.

API Stream Wrappers – Week 10

Ah, there’s nothing like the smell of fresh tests in the morning. I submitted a couple of small hacks for WP Automated tests to add basic code coverage options. After looking through that code though I think it’s safe to say that it needs to be rewritten 😦 Hint hint for those looking into GSoC next year!

You’ve probably already heard the announcement that PHP4 and MySQL4 support will be dropped in the near future. This is fantastic news on multiple levels–one of them being that stream wrappers require PHP5+, so this is good news indeed.

This next week I’m going to finish off as much of the tests as I can and try to workaround the remaining shortcomings in the testing suite. Then I hope to toy around with some demonstration wrappers 🙂

API Stream Wrappers – Week 9

This week I hacked WP Automated Tests to add coverage reports using xdebug and PHPUnit. As of today roughly 75% of the lines of code, or half of the functions and methods, are covered with the unit tests. Of course, code coverage doesn’t mean that everything works just right, but it is very beneficial in increasing confidence in the code and pointing out possible weak areas that need attention.

Coverage Report as of July 21, 2010

Next week I’m going to divert my attention slightly to cleaning up the WP Automated Test modifications and submitting patches for that project. I’ll also be shoring up some of the weaker areas of coverage pointed out by the coverage report.

API Stream Wrappers – Week 8

This week I started doing some serious work with unit testing. I initially wanted to be able to run the tests directly with PHPUnit but discovered that it would be considerably more convenient to have WordPress setup and installed and torn down for each test. So at the moment I’m piggybacking on WordPress Automated Tests. It gets the job done as far as simple testing goes, but several notable features that PHPUnit provides are currently inaccessible such as coverage reports. I’m going to finish up writing the most critical tests for stream wrappers and then briefly look into improving the testing suite to see if coverage reports can be coaxed out without a major overhaul.

Tip: Automated Testing improvements would make a great project for GSoC next year 😉

At the moment the tests demonstrate that the system works top-to-bottom 😀 The registry is fully operational and a preliminary test was written for the new test stream wrapper (test://) that leverages the generic local stream wrapper class that’s included with the plugin. For example, the test proves that mkdir(‘test://dir1’) actually gets rerouted properly to create ‘wp-content/streams_test/dir1’. There’s still a lot remaining to test, especially edge cases [*cough*Windows*cough*], but things are coming together very nicely indeed.

Unit testing stream wrappers plugin mini-guide

Here’s a quick guide if you’re interested in running some of the tests, or even helping out by writing more!

First check out the following

1. http://codex.wordpress.org/User:Hakre/WP_Unit-Tests
2. http://codex.wordpress.org/Automated_Testing

Once you have the mundane prerequisites out of the way you can get to the more exciting tests.

1. Put the stream wrappers plugin in the usual directory. This will probably be something like wp_automated_tests/wordpress/wp-content/plugins/
2. Configure the wp-config.php file in the top-level directory as indicated in the Automated Testing Guide. Define DIR_TESTPLUGINS as follows:
   define('DIR_TESTPLUGINS', './wordpress/wp-content/plugins/wp-stream-wrappers/tests');

To run tests, use a variation of the following command: php wp-test.php -t [Test]

The following Stream wrapper specific tests are currently available:

• WP_Stream_Wrapper_Registry_Test [completed]
• WP_Stream_Test [completed]
• WP_Local_Stream_Wrapper_Base_Test [in progress]
• WP_File_Helpers_Test [in progress]

API Stream Wrappers – Week 7

Development slowed to a glacial pace this week as a result of the 4th and my upcoming GMAT exam. Fortunately, significant headway was made last week, so I’m not significantly behind the timeline. I will be working extra hours over this next weekend to get caught up. My interim goal for this next week is to get a small demonstration functional.

API Stream Wrappers – Week 6

Development of stream wrappers is progressing nicely and on track with the timeline. Today I have a very small treat: visuals.

The following organizational chart shows the current state of the plugin.

The WP Local Stream Wrapper Base class provides an implementation of the wrapper interface class and is capable of manipulating local files. In essence, this base implementation provides functionality equivalent to the file:// wrapper that comes with PHP.

Any wrapper that manipulates local files can simply extend this base class. This means that it only takes a few lines of code to implement a custom wrapper fully capable of manipulating local files [e.g. mysuperdupercoollongwrappername:// (please don’t ever make your wrapper scheme this long)].

Did you know: paths such as /path/to/file.txt use the PHP Filesystem (file://) wrapper?

The chart below is a demonstration of the organization when other community developed stream wrappers are added.

At the present time, only the local:// stream wrapper will be included with the plugin. Other [optional] stream wrappers will be implemented as individual plugins. This method will make it easier to add and remove wrappers at will and find them in the repository.

However, one small stumbling block has been encountered. WordPress does not currently do anything with plugin dependencies. Until this functionality is made available with the core plugin system, each wrapper will have to perform a rudimentary check to assert that the WP Stream Wrappers Plugin is activated before trying to load a wrapper implementation which extends the WP Stream Wrapper Interface. Otherwise, universe ending paradoxes will ensue.

Until next week 🙂

API Stream Wrappers – Week 5

Short update coming from phone while ISP fixes damaged cable…

Everything is falling into place. The wrapper hierarchy is finalized. A generic base class for handling local files and an example wrapper [local://] have been created. File operations will work soon and then the real fun begins 🙂

API Stream Wrappers – Week 4

This was a very productive week… personally. Three weddings and the associated road trips 🙂 Project wise, I have started on the base WordPress stream wrapper interface. This interface will be implemented by all stream wrappers that want to interact with the stream wrappers plugin and is an extension of PHP’s example stream wrapper class.

One item of particular interest is that PHP’s fopen() function only supports URIs in the form of “scheme://target”. This despite the fact that RFC 3986 states that a URI’s scheme component delimiter is in general “:” and not “://”. For the sake of consistency the WordPress stream wrappers plugin will only accept URIs in full form (i.e. “scheme://target” rather than “scheme:target”). Here’s a rather dated PHP bug report of the problem if this kind of stuff interests you.

I’m shuffling around some of the items on the timeline so that development can proceed more smoothly. Primarily, I’m going to create a generic stream wrapper for the local filesystem and get it out of the way now. This wrapper will be bundled with the core stream wrapper plugin. It will serve as an example implementation for developers of other stream wrappers (more on that later) and provide a convenient method of building tests.

API Stream Wrappers – Week 3

This week has been significantly more productive that the last two. I’ve broken my status update into the different efforts that are currently ongoing.

WP_Stream_Wrapper_Registry

The core of the WP stream wrapper registry has been implemented. This registry keeps track of the scheme and implementation class of each registered wrapper. The WP registry provides supplemental functionality that PHP’s native registry does not provide. An example of the new functionality added is the ability to ask “what wrapper class is responsible for handling this URI or scheme?” The File API will depend on this kind of information to work around current limitations (i.e. bugs) in PHP’s stream wrapper support. Further work on the registry is blocked until WP_Stream_Wrapper_Interface is completed.

WP_Stream_Wrapper_Interface

This interface will lay the ground work for what all WordPress wrappers must implement in order to be registered.

WP File API

Most stream wrapper functionality will work out of the box. For example, PHP will know what to do if you call fread() with a stream URI. Unfortunately, a handful of standard PHP functions have bugs with stream wrappers and do not work as intended. These limitations are easily overcome by providing replacement functions. These functions will become a part of a File API that is WordPress specific. Next week I will detail how this API and WP_Filesystem_* relate.

Code repositories

I setup GitHub mirrors of the Subversion code repositories incase I need to leverage Git’s superior merge capabilities.
GitHub: wp-stream-wrappers
GitHub: wp-stream-wrapper-test