Drupal 7 Module Development

Chapter 11
Stream wrappers
If you've been writing PHP for very long, you have most likely needed to work with
local or remote files at some point. The following PHP code is a common way to read
a file into a variable that you can do something with:
$contents = ";
$handle = fopen("/var/www/htdocs/images/xyzzy.jpg", "rb");
while (!feof($handle)) {
$contents .= fread($handle, 8192);
}
fclose($handle);
This is pretty straightforward. You get a handle to a local file using fopen() and
read 8 KB chunks of the file using fread() until feof() indicates that you've
reached the end of the file, at which point you fclose() the handle. The contents
of the file are now in the variable $contents. In addition to local files, you can also
access remote files through fopen() like this:
$handle = fopen("http://drupal.org/files/issues/druplicon_2.png",
"rb");
Data that you can access this way is streamable, meaning you can open it, close it,
or seek to an arbitrary place in it. Stream wrappers are an abstraction layer on top
of streams that tell PHP how to handle specific types of data. When using a stream
wrapper, you refer to the file just like a traditional URL—scheme://target. Often
the target will be the path and filename of a file either located locally or remotely, but
as we will see in our sample code, it can be any data that uniquely identifies the data
you are trying to access.
The above examples use two of PHP's built in stream wrappers. The second uses
the http:// wrapper for accessing websites using the http protocol, and the first
uses the file:// wrapper for accessing files on local storage. file:// is the default
scheme when one is not specified, so in this case simply passing the file's path
works fine.
PHP also allows developers to define their own wrappers for schemes that PHP does
not handle out of the box, and the Drupal File API has been built to take advantage
of this. For instance, Drupal defines the private scheme to allow Drupal developers
to interact with files in Drupal's private file system. Let's look at how this works by
creating a scheme to retrieve images from a remote website.
[ 319 ]