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 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

API Stream Wrappers – Week #2

My typical TextMate+command line workflow was leading to slow and troublesome bug squashing, so this week was spent hammering out xdebug and Eclipse PDT issues to setup a more sophisticated debugging environment. Graduations and memorial day took a bite out of my time, but I still plan to have a chunk of the registry completed by the end of the week which will keep me on schedule.

This next week I will be working the Pomodoro technique into my workday to see if it positively affects my coding sessions.

Hello world! (that greeting will never get old :D)

The proverbial ball is beginning to roll. Earlier this week it was decided to begin implementation as a plugin. Ideally this API will become a part of core, but it doesn’t need to be right now. This route will let us gauge community adoption and review the merits of merging into core at a later date.

The SVN repository has been setup here: http://gsoc.svn.wordpress.org/2010/jmstacey/

I created the basic repository structure and there are two plugin place holders right now. Stream Wrapper API (stream-wrapper-api) will be where the majority of work takes place. Stream Wrapper: Test (stream-wrapper-test) development will begin once the underlying API reaches critical mass and will serve as a test of the API as well as an example wrapper implementation for other wrapper developers.

I will be taking a crash course on PHPUnit this week. I want to leverage unit testing throughout the development process and am striving for near 100% code coverage when all is said and done.

Jon Stacey – Introduction

My name is Jon Stacey–an aspiring tech maven living in Lincoln Nebraska (CDT or UTC -5). I have just wrapped up my fourth and final year of undergraduate studies at Union College where I majored in Computer Information Systems. I will be continuing on to the University of Nebraska, Lincoln for postgraduate studies in Business Administration later this fall.

Project summary: API stream wrappers

Here is the abstract taken from my project proposal:

The goal of this project is to improve the file handling capabilities of WordPress by making PHP’s stream wrapper functionality a part of the File API. PHP stream wrappers allow virtually any type of resource to be represented as a normal file. Stream wrappers will make the implementation details of file management transparent to developers fostering cross plugin interoperability and increasing the flexibility of WordPress.

In other words, my goal is to provide a single API toolkit for WordPress that allows transparent file manipulation across boundaries. For example, a URI such as ‘youtube://pv5zWaTEVkI’ or ‘s3://bucket/file’ can be sent through the same API. Commands such as fopen() will automatically select the correct wrapper implementation to use. The end result being developers don’t need to directly worry about the underlying file handling implementations such as communicating with Amazon S3 [unless they’re writing wrappers 😉 ]. The flexible power of stream wrappers will open many doors down the road.

You may be interested in the revised API stream wrappers scope. The original project proposal can be found here.