What are stream wrappers?

PHP 4.3.0 introduced the idea of streams. The PHP manual has a perfect explanation:

Streams were introduced with PHP 4.3.0 as a way of generalizing file, network, data compression, and other operations which share a common set of functions and uses. In its simplest definition, a stream is a resource object which exhibits streamable behavior. That is, it can be read from or written to in a linear fashion, and may be able to fseek() to an arbitrary locations within the stream.

Streams are identified by a particular scheme in the URI. For example, with http://someurl the scheme is 'http' and when no scheme is provided like in /file.php, the scheme is defaulted to 'file' and is expected to be a file in the filesystem (thus file:///file.php would mean the same thing).

Stream wrappers are bits of code that tell PHP how to handle certain schemes. The interesting thing is that you can create your own custom stream wrappers written in PHP with little effort.

For example, you may have done file_get_contents('file.txt'); before. But say you wanted to have the same ease of use but with data from a different source. You could create a custom stream wrapper to get data from wherever you want and use all of the normal PHP functions as usual: file_get_contents('mystream://whatever');.

Almost any function that works on files will work with custom stream wrappers. That includes fopen, fwrite, fseek, is_readable, is_writable, stat, unlink and more. In essence you can create a virtual filesystem in your applications.

Why create custom stream wrappers?

So why in the world would you want to create custom stream wrappers? Basically it comes down to decoupling filesystem-coupled interfaces from the filesystem (or any stream, for that matter). That is, make software think it's talking to files when it's talking to your custom PHP class. It's all about abstraction!

You could also use stream wrappers to simplify an interface, though this is less common. If you are using stream wrappers to simplify an interface, you can just as easily create a normal facade to simplify the interface and leave streams out of it.

For example

I wanted to use a newish PHP templating engine called Dwoo for an upcoming project. The problem was it expects files everywhere. Template files were read from the filesystem and compiled to the filesystem, and caches were written to the filesystem. There was no easy way to change this.

For this particular project I need to read templates from a string (loaded from an arbitrary source decided at runtime), and I can't use the filesystem for caches, I need to use memcached. The reason being that the application will be run in a cluster. Using shared disks is not practical with this many machines, and disk IO would eventually become a bottleneck. True, we could use RAM disks, but it's a lot easier and portable to manage the data layer from our application instead of pushing it to the OS.

Using custom stream wrappers I created two new schemes for 'tpl://' (for reading) and 'tplc://' (for writing compiled templates). I was able to fill the requirements for the project while still using the awesome templating engine with little modification. The library still thinks it's reading and writing to files but behind the scenes it's reading from a cache of template sources and writing to memcached. Perfect!

Creating custom stream wrappers

To create your own custom stream wrappers you need to write a class that implements a set of methods. After you write the class, you can register it with stream_wrapper_register. Refer to that manual page for details on the methods you need.

The only problem I encountered was how to get my custom stream working with is_readable() and is_writable(). The trick is to implement the 'url_stat' method and set the 'mode' correctly. The mode is a number that represents what type of file the file is (file or directory etc) and the file permissions -- the usual chmod values. Here's a code snippet that accurately defines how the number should add up:

$dir = 040000;
$file = 0100000;

// Now you can add any permissions you want using the usual chmod octal notation:
$file += 0777; // A file that is readable
$dir += 0222; // A directory that is writable

About Zend Framework

The Zend Framework is a free (BSD-like license) PHP framework. It contains components to tackle many common problems including authentication, cacheing, mail, sessions, and of course MVC.

ZF is simple. It is a "use at will" framework, meaning you can take specific components and use them wherever you want. You can, for example, take just the Mail component and stick it into your already existing PHP application. This decoupled architecture is contrary to some other frameworks (including symfony or CakePHP to certain extents) where you are forced into using a single paradigm.

This framework is written for PHP5 only, so it is not encumbered by the limitations of PHP4. It is written using the best OOP principals, is thoroughly tested, and has a marvelous community of maintainers that keep it up to date.

Zend Framework versus other frameworks (symfony, CakePHP etc)

Typically when you think of a framework, you envision a completely developed codebase that includes its own of configuration, its own conventions, and specific programming paradigms. Many frameworks including symfony, CakePHP, Code Igniter and Ruby's Rails, follow this kind of thinking.

Zend Framework is a collection of loosely coupled components. As mentioned earlier, you can use any one of the components separately without running into any problems. Even so, the components still work very well together (for example, Zend_Auth can seamlessly use Zend_Session for persistence).

You need to do a bit more work to use ZF initially. ZF is not all tied together, so if you want to use MVC (for example) then you have to create your own bootstrap, and create your own directory structure etc. When you download ZF it's simply a directory that contains the library files, you're the one who has to initialize and use everything. Compare this to symfony (or many others) where everything is ready to go after you edit a couple configuration lines.

I prefer ZF because I feel like I have more control. I am not tied into any one paradigm, I don't need to play around with configuration files and I can mix and match my code to my hearts content.

Please note that I am not belittling the other frameworks, I am just trying to explain what sets ZF apart. If you read some of my previous posts, you'll see I'm also an advocate of symfony.

The Parts

MVC with Zend Framework is quite easy. Here's a brief overview of each part and how they relate to each other.

1. Front Controller

Most people will use a Front Controller. Using a Front Controller means that all requests come through a central starting point. Usually a single index.php will instantiate the front controller object and handle all incoming requests to your site. The file is referred to as a "bootstrap" file, and will contain code to initialize other things in your system too (for example, loading configuration settings).

If you've been developing on the web for a while, you've probably seen lots of scripts that have many entry points. For example, you might have index.php, login.php, article.php etc. Most of the time you also have a global.php file that is included at the top of each script. When you have all these entry points, it can quickly become hard to manage and you also start to get a bunch of code duplication.

A Front Controller solves this. Instead of physical files on the disk defining how a request should be handled, the request itself is entered through the Front Controller and then analyzed to see what should be done with it.

2. The Request Object

Each request made has a corresponding Request object. This object wraps up the entire request environment. For example, the default HTTP environment contains things like request parameters from GET and POST. The Request object also contains which controller and action should be called upon.

3. The Router

The Router is what actually inspects the incoming request and decides which Controller and Action should be called up. For example, it will look at a request of /login and decide that the Login Controller should handle the request, and the Index Action should be called.

ZF comes with a default router, so you don't need to change anything unless you want special behavior. By default, the incoming URL is analyzed and the parts are mapped to specific controllers and actions: /:controller/:action. If they are not provided at all, then they are assumed to be 'index'.

3. The Dispatcher

Dispatching is the process of looking at the requested controller and action, and actually including the correct Controller file, instantiating it, and calling on the action. The Dispatcher is in a loop. That means you can run as many controllers and actions as you like.

Again, ZF comes with a default dispatcher that sets down some naming conventions that we'll explore in a bit.

4. The Controller

Finally there is your actual controller. A controller handles a specific part of your app (for example, working with articles) and can have multiple actions (for example, listing articles, viewing a single article, viewing a printable version etc).

The Process

A request is handled like so:

1. A web request is made to a single entry point (usually an index.php file)
2. The entry point creates a Front Controller and runs it
3. The Front Controller creates a Request object that wraps up the environment. At this point there is no controller or action set.
4. The Front Controller uses a Router to inspect the request to figure out which controller and action should be called upon. It sets these values in the Request object.
5. The Front Controller starts the Dispatcher loop which includes the correct Controller source file, instantiates it, and runs the correct Action.
6. A Controller does what it does. It can handle forms, get database info, render HTML etc.
7. Any Controller can also modify the Request object and set a different Controller or Action, so the Dispatch loop is run again. If no change is made, then the Dispatch loop ends and the result is served to the user

You can get a visual representation of the process by viewing this image.

Let's Get Started

The File Structure

I like to separate my files into two parts. One part for the actual application files (controllers, libs, views, functions etc) and then public files that the user needs access to (javascript, css, images etc).

For the sake of simplicity, I also like to package ZF with my app. If you have a shared directory where you place libraries (PEAR, for example), then you of course don't need to include it with your own files.

Here's the structure I use:

• root
  • /client
    • /css
    • /images
    • /js
  • /appfiles
    • /application
      • /controllers
      • /views
        • /scripts
    • /lib
      • /Zend
  • /.htaccess
  • /index.php

This also makes it easy to split up the appfiles from the public files. For example, may people like to place the application source files outside of the document root on the webserver.

The /appfiles/application directory contains all of your controller and view files. We'll talk about the naming convention the default Dispatcher expects in a sec.

The /appfiles/lib directory is where I personally like to keep the Zend Framwork files.

You can of course have any other directories you'd like. On one of my recent projects I had /appfiles/functions and /appfiles/classes for some various custom code files.

Rewrite URLs

To create friendly URL's like /login or /article/view, you need a way to rewrite all URL's to go through the main index.php file. If you are using an Apache webserver and htaccess is a viable option, then the following simple code snippet should work fine for you:

RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php

If you are on a different server, there are other ways to rewrite URLs.

Note that you can still use ZF's MVC components without rewriting URL's. Refer to the documentation for info on how to do this.

Create Bootstrap

The bootstrap file is the "single entry point" I've been talking about. It contains the code that launches the Front Controller. In this case, our bootstrap file is index.php.

Here's the code for a simple bootstrap file:

<?php

#------------------------------
# Get the paths set
#------------------------------

define('ROOT', realpath(dirname(__FILE__) . '/appfiles'));
set_include_path('.' . PATH_SEPARATOR . ROOT . PATH_SEPARATOR . ROOT.'/lib');

#------------------------------
# Register the Zend autolaoder
#------------------------------

require_once(ROOT . '/lib/Zend/Loader.php');
Zend_Loader::registerAutoload();

#------------------------------
# Dispatch
#------------------------------

Zend_Controller_Front::run(ROOT . '/application/controllers');

Line 7 defines the ROOT constant to be the full path to the appfiles/ directory. If you were to move the appfiles/ directory somewhere else, you'd want to edit this line so the path stays correct.

Line 8 sets the PHP include path so that the Zend files are all included without any problems. We need this line because we are distributing ZF with the project, we need to tell PHP where to look for the files when we include them.

Line 15 and 16 include Zend_Loader and register it's autoload functionality. PHP5 introduced the ability to autoload classes. Whenever a class is used but has not been defined, PHP will try and find the file and include it for you. This saves you from having to manually write all of the require_once()'s you would normally write under PHP4.

Line 23 fires off the Front Controller which starts up your whole application. As a parameter you need to pass the path to your controller files which in our case is /appfiles/application/controllers.

If you run this now (http://yoursite.com/path/to/project/), you'll see an exception because ZF can't find your controller file to handle the request. So let's write it.

Controllers and Actions

What are Controllers? Actions?

Lets get this question out of the way for those who are new to this kind of website architecture. A Controller is a class that handles the business logic of a given part of your website. It fetches data from a datasource, interacts with output, and then passes any calculations to the View to be displayed to the user (usually as HTML). Some examples of Controllers might be: LoginController, ArticleController and SearchController. Before you might have had files like login.php, article.php and search.php -- now you have classes that control all of this behavior.

Each Controller has a set of Actions, which is just a method you define within the Controller class. An Action is something specific the Controller needs to do. Using our examples listed before, this might be processing a login, displaying an article or performing a search. Before you might have used a variable in the URL to determine what needed to be done. For example, "article.php?do=display" now becomes the ArticleController with the 'display' Action.

Naming Conventions

So you know that controllers are classes, and actions are methods in the controllers. Now the only thing left to cover is how ZF knows which file to load, and which method to call.

You defined the location of the controller files when you called Zend_Controller_Front::run() in the bootstrap. In our example, it is /appfiles/application/controllers.

The Dispatcher (explained above) is responsible for loading the appropriate files, instantiating the correct class, and then calling the correct method. The default Dispatcher that comes with ZF uses a naming convention so you can add controllers and actions easily (instead of say, creating a configuration file that defines it all).

There are two very simple rules:

• All controllers need to be called SomethingController where "Something" can be whatever you want. The class source code needs to be in a file called "SomethingController.php".
• All actions need to be called someAction() where "some" is anything you want.

The default Router and Dispatcher will route a URL /something/some to the SomethingController and the someAction() action. (Meaning: Remember that the default URLs are /:controller/:action).

If a controller is not specified, then the 'index' controller (IndexController class) will be assumed. If an action is not specified, then the 'index' action is assumed (indexAction() method).

Just to hammer it into your head, let's have a few examples of how some possible URLs might be loaded using the default Router and Dispatcher:

• /: IndexController class, indexAction() method
• /login: LoginController class, indexAction() method
• /login/lostpass: LoginController class, lostpassAction() method
• /article/new: ArticleController class, newAction() method

You can also use hyphens in your URL's if you use camelCase in the naming of controllers or actions:

• /download/message-attachment: DownloadController class, messageAttachmentAction() method
• /sign-up/confirm-email: SignUpController class, confirmEmailAction() method

Views

What are Views?

A View is the thing that you give back to the user after they request something. Usually this is an HTML page, but it can be other things like XML or RSS feeds, file downloads etc.

File Locations

Controllers will try to render a view script automatically. It will search for view scripts in /views/scripts/ in the directory above the controller directory (for us that means /appfiles/applications/views/scripts/). Each controller is expected to have a directory of its own, and each action is expected to have a .phtml file that is the actual PHP script to render. For example, LoginController's indexAction() will have a view in views/scripts/login/index.phtml.

View Files

The default view scripts in ZF are plain old PHP. You can add a different templating system if you'd like (like Smarty), but for simplicity, this article will use the default.

In the controller you can set variables to be available to the view, so you can do all of the usual stuff you'd expect like looping, formatting etc.

An Example Page

Time for a really simple example page that demonstrates everything you've just read.

First step is creating a new controller. This controller will be located at: /appfiles/application/controllers/IndexController.php with the following code:

<?php

class IndexController extends Zend_Controller_Action {
    public function indexAction() {

        $this->view->name = "Christopher";

    }
}

Next we need to create a view script to render the HTML page. The view script will be located at: /appfiles/application/views/scripts/index/index.phtml with the following code:

<h1>Hi, <?php echo $this->name; ?></h1>

Now if you run this in your browser, you'll get a simple page that displays a name. So what is going on here?

The Controller

The IndexController is a class the extends Zend_Controller_Action. All of your controllers must extend this base class (or a child of this base class -- you can create your own if you needed to). And on line 4 we have defined the indexAction() method to handle the default index action.

By defining both the index controller with an index action, we now have a default page do display whenever there was no URL supplied (remember that the dispatcher assumes 'index' if no controller or index was supplied).

On line 6 you'll notice we are assigning a name to a variable $this->view->name. This is how you pass values to your view script. You can assign any values. The view script is just PHP remember, so it doesn't matter if you assign arrays, objects, integers or strings.

The View

The view in our case is very simple. I just wanted to highlight how we use the variables assigned in the controller. All values assigned in the controller are available as $this->varname.

What about Models?

I haven't discussed anything about the models in this article. That's because the model in ZF's MVC can be just about anything.

A model is an object, or a system of objects, that represent some sort of data. Most often models are objects that represent specific database records, or database tables. For example, if you have a "user" table then you'd also have a "User" object to represent records from the table. You might also have a "UserTable" object to make finding records easier (sometimes called "peer objects"). So you might have classes with methods like User::setPassword() and UserTable::findUserByEmail(). This technique of mapping a table to objects is the ActiveRecord pattern.

You can code these objects yourself, but usually some sort of ORM (Object-relational mapping) tool/library is used. Two of the most popular are Doctrine and Popel (I suggest Doctrine). With these libraries, you define the structure of your database and the rest of the work is done for you. That is, the means of satisfying relationships and filling data objects with actual data form the database is done by the library rather then by hand. In the case of Doctrine, actual SQL is abstracted into so-called "DQL" (Doctrine Query Language) to make your programs 100% portable.

The point of a model is to create a separation between the data-tier and the logic-tier in your application. For example, your application's "change password" controller shouldn't need to know the low-level details of how a password is changed (the hashing, salting etc). That kind of thing should be coded into the model.

Finished

That's all there is to it. Click here to download the sample files used in this article (note that you need to add your own Zend library to the /appfiles/lib directory).

Next article I will go over some more advanced techniques including subclassing the front controller, action controllers, creating plugins and creating helpers.

The Basics

Let's start with just displaying the content on the screen in a table. Throughout this post I am going to be using a table called 'users' with fields for an ID, a first name, last name and email address. Here's some basic code that will just output these details into a (very long) table:

<?php
	$res = mysql_query("
		SELECT *
		FROM users
	");
?>
<table cellspacing="1" cellpadding="0" width="100%">
	<thead>
		<th>ID</th>
		<th>First Name</th>
		<th>Last Name</th>
		<th>Email</th>
	</thead>
	<tbody>
		<?php while ($user = mysql_fetch_assoc($res)): ?>
			<tr>
				<td><?php echo $user['id']; ?></td>
				<td><?php echo $user['first']; ?></td>
				<td><?php echo $user['last']; ?></td>
				<td><?php echo $user['email']; ?></td>
			</tr>
		<?php endwhile; ?>
	</tbody>
</table>

This is a pretty simple piece of code. We run a MySQL query to fetch all the users in the system -- we've all done that before, right? Of course the problem is when there are just too many users to list all at once. In the case of my example database, there are 200 records.

Introducing: LIMIT

A feature of any SQL database (that follows standards, anyway) is the ability to tell the server where to start returning rows from, and how many rows to return. Let's first modify the query a bit so it looks like this:

$res = mysql_query("
	SELECT *
	FROM users
	LIMIT 5
");

The LIMIT 5 makes the database return a maximum of 5 rows. So instead of returning all 200 of the rows in my example database, only the first 5 are returned -- that would be users with ID's 1-5.

In addition to just limiting the number of rows to return, you can also provide an offset. The offset is how many rows to skip before returning the result set. For example, let's modify the query one more time:

$res = mysql_query("
	SELECT *
	FROM users
	LIMIT 10, 5
");

The first number is the offset, and the second number is the row count. LIMIT 10, 5 means "Get 5 rows starting after the 10th row". In other words, rows 11-15.

So the magic behind pagination is this LIMIT clause. The rest of the work is just some basic PHP to display a page selector, and a bit of math to get the offset and row count from the page number.

The PHP Side Of Things...

Before we start, let's outline what information we need available:

• The number of rows to display per page. This is usually just a configuration setting. We'll hard code this value directly into our script.
• The current page the user is viewing. This is simple, it's just the users current page or '1' if they have no page. We'll pass this along in the query string.
• The number of total rows the user can view. We need this number so we can calculate how many pages we will have to show in the page selector.
• The total number of pages.
• The offset to plug into the LIMIT clause, based on the values for per-page and the current page.

The only "hard parts" are getting the number of total rows, calculating how many pages are required to show them all, and calculating the offset for use in the LIMIT clause. Here's how I did it:

$per_page = 10;
$cur_page = isset($_REQUEST['p']) ? (int)$_REQUEST['p'] : 1;

$res = mysql_query("
	SELECT COUNT(*)
	FROM users
");
$num_rows = mysql_result($res, 0, 0);

$total_pages = ceil($num_rows / $per_page);

if ($cur_page <1 || $cur_page> $total_pages) {
	$cur_page = 1;
}

$offset = (($cur_page - 1) * $per_page);

Now that we have the code, let's go over it:

• First we set $per_page to a hard-coded value. In this case, it is 10. In the future you might want to make this user-configurable, but for now lets keep it simple.
• Next is getting the current page by setting it to the 'p' incoming variable (for example, index.php?p=10). If there is no 'p' variable, then default to the first page. Also note that I have casted the value to an integer, we don't want the user messing around with the query string and providing some string.
• Then we get the total amount of rows in the database. A simple COUNT(*) gives us the number we're after. After running the query it's just a matter of sticking the count into the variable $num_rows. Note that if you introduce some kind of searching into your scripts, the same WHERE and JOIN clauses will need to be present in this query as well as your search query. $num_rows is meant to contain the number of total rows that the user will want to view, not just the total number of rows in the table.
• To get the total number of pages, we use some simple math. The number of pages will be the total number of rows divided by the number of rows per page. Note the use of the ceil() function here. We want to round up the number to ensure that even a page with only 3 rows will still be viewable.
• Then we do a check to make sure $cur_page is correct. It needs to be at least 1, and at most $total_pages. This check is here to ensure the user doesn't try something like 99999999999.
• Finally, we calculate $offset that will be used in the LIMIT clause of our query. The offset is simply $cur_page minus 1, multiplied by the number of rows per page. We have to subtract 1 from the current page, otherwise it would always be a page ahead.

Now that we have the numbers, we can alter our data-getting query and plug them into the LIMIT clause:

$res = mysql_query("
	SELECT *
	FROM users
	LIMIT $offset, $per_page
");

Tada! We're all done! Well, that part at least. The only part left is to generate the links to the other pages.

Generating The Page Links

There are several different styles of page links. I prefer the kind that have a first/last and prev/next links to the side of the actual page links, and the current page should be surrounded by 5 pages to the left/right. For example, if I'm on page 15, there will be links to pages 9-14 on the left and pages 16-20 on the right. This is the style that I'm going to demonstrate here.

Undoubtedly there are numerous ways to generate such a navigation. Here's how I did it:

<?php
	$page_pad = 5;

	$min_page = max(1, $cur_page - $page_pad);
	$max_page = min($total_pages, $cur_page + $page_pad);

	$show_prev = $cur_page> 1 ? $cur_page - 1 : false;
	$show_next = $cur_page <$total_pages ? $cur_page + 1 : false;
?>
<div class="page_nav">
	<ul>
		<li><a href="?p=1">&laquo; First</a></li>
		<?php if ($show_prev): ?><li><a href="?p=<?php echo $show_prev; ?>">&lt;Prev</a></li><?php endif; ?>

		<?php for ($page = $min_page; $page <= $max_page; $page++): ?>
		<li <?php if ($page == $cur_page): ?>class="cur_page"<?php endif; ?>><a href="?p=<?php echo $page; ?>"><?php echo $page; ?></a></li>
		<?php endfor; ?>

		<?php if ($show_next): ?><li><a href="?p=<?php echo $show_next; ?>">Next&gt;</a></li><?php endif; ?>
		<li><a href="?p=<?php echo $total_pages; ?>">Last &raquo;</a></li>
	</ul>
</div>

• First we set a $page_pad setting that is used to determine how many pages to either side of the current page should be shown. I think 5 is an appropriate number.
• Next we need to determine the minimum and maximum page numbers that will be shown, based on the current page and how many pages to pad it with. We can't simply do the current page minus the padding for the minimum or the current page plus the padding for the maximum. This would make for the possibility of negative pages being displayed (for example, page 1 minus 5 padding) and pages that are over the total pages. To solve this issue we can use the min() and max() functions to make sure the $min_page and $max_page never go over the acceptable values.
• Then we just need some simple logic to determine if the previous and next pages should be display, and if so, what their page numbers are.
• The next bit is outputting the HTML for all the paged links

There you have it! Pretty simple, isn't it?

Conclusion

I hope I've helped some new programmer out there with this post. I had just gotten tired of so many people asking me how to add pagination to their apps and not having any definitive source to point them to. Not exactly the most advanced stuff, but still something I though needed to be covered.

You can download the full source code here. The package contains a PHP file, a CSS file and an SQL file that contains the test 'users' table and its data. The result looks like this: