One of the problems with naming request handlers to match the incoming request method, e.g., GET, POST, PUT, DELETE, is that there’s an obvious potential for accidentally re-declaring that function. At this point in time, there are no pre-existing functions in PHP core that are named get(), post(), put(), delete(), head(), options(), trace(), or connect()…but that’s no guarantee that there won’t be in the future, or in a 3rd party extension/library that you may be using.

To get around that potential name collision, I could do a few things:

• Have a fixed prefix for those functions, e.g., doget(), dopost(), etc
• Have a user specified prefix that defaults to “”. So you could write your app with get(), post(), etc, or specify “do” in the init and use doget(), dopost(), or maybe specify “_” and use _get(), _post(), etc.
• Require the requested script to define a specific class with static methods for those HTTP verbs (with or without prefixes).

I wasn’t really satisfied with any of these options though. Prefixing the function names makes it less likely that a fatal function redeclaration would occur down the line, but technically it’s not impossible. That’s where the dynamic prefixing comes in…it make sit easier to sort of move those functions out of the line of fire, but they’re still in harms way. I’d rather extract them from combat altogether, so to speak.

The cleaner solution of those three options, IMO, would be to define a single class in every single one of the requested scripts. Something like:

1
2
3
4
5
6
7
8

<?php
class comb_handler 
{
    public static function get()    { ... }
    public static function post()   { ... }
    public static function put()    { ... }
    public static function delete() { ... }
}

Then Comb would just check to see of the requested method exists, and run it if so. While that would pretty much solve the function name collision problem, it feels very hackish to me. You’d essentially be using a class for nothing more than its namespace. After a bit of brainstorming I remembered that PHP 5.3 introduced closures. So instead of the request script looking like this:

1
2
3
4
5

<?php
function get()
{
    echo "hi";
}

I could do this:

1
2
3
4
5

<?php
comb_handle('get', function()
{
    echo "hi";
});

What I like about this approach is that instead of defining a specific request handler, I can define a bunch of them as closures and have comb_handle() just stick them all in an array. Then when it comes time to run the request methods, I can just loop over that array of closures and run them one after another. comb_handle() would look something like:

1
2
3
4
5
6
7
8
9
10
11
12

 
function comb_handle($method, $function)
{
    /**
     *  if comb were an extension, this variable would 
     *  only be accessible within the extension itself.
     *
     * $method is one of GET, POST, PUT, DELETE, XHR
     */
    global $method_chains;
    $method_chains[strtolower($method)][] = $function;
}

So imagine a GET request comes in for /session/login.php. The following scripts would get included (if they all exist):

/prepend.php
/session/prepend.php
/session/login.php
/session/append.php
/append.php

In each of those scripts, you can define handlers for any request method you want. To illustrate this, you could do the following in each of the scripts above:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

/* /prepend.php */
<?php
comb_handle('get', function() {
    echo "one! ";
});
 
/* /session/prepend.php */
<?php
comb_handle('get', function() {
    echo "two! ";
});
 
/* /session/login.php */
<?php
comb_handle('get', function() {
    echo "three! ";
});
 
/* /session/append.php */
<?php
comb_handle('get', function() {
    echo "four! ";
});
 
/* /append.php */
<?php
comb_handle('get', function() {
    echo "five! ";
});

Then after Comb includes those scripts the $method_chains array will look like:

1
2
3
4
5
6
7
8
9

array(2) {
  ["get"]=> array(5) {
    [0]=> object(Closure)#1 (0) {}
    [1]=> object(Closure)#2 (0) {}
    [2]=> object(Closure)#3 (0) {}
    [3]=> object(Closure)#4 (0) {}
    [4]=> object(Closure)#5 (0) {}
  }
}

Comb would simply do a foreach over $method_chains['get'] calling each closure, and you’d see this in your browser:

one! two! three! four! five!

So that’s the direction I’m heading now. That obviously means that Comb will require PHP 5.3 from this point forward, but another advantage of doing so is using namespaces to clean up these ugly comb_* prefixed functions. Some folks might not agree, but to me, this:

1
2
3
4

<?php
use comb as c;
c\handle('get', function() {});
c\handle('post', function() {});

…feels cleaner (though weirder) than:

1
2
3

<?php
comb_handle('get', function() {});
comb_handle('post', function() {});

Might as well start getting used to using namespaces though. I believe they’ll be getting much more common over the next year or two.

I wrote up a quick summary of all the comb_* functions. Check it out:

Comb Function Reference »

I think this is the third time I’ve re-tooled the guts of Comb. The main idea is still the same, but the default behavior is a little different, and it’s not object-oriented at all. My goal in doing it this totally procedural way is to make it possible to build it as a PHP extension, thus configuring its default behavior via httpd.conf, .htaccess, or php.ini. Not that making it an extension means that I can’t use objects…I just didn’t really feel the need at this point. Unsurprisingly, I may change my mind later :-/

Setup & Configuration

Comb still runs using the same overall lifecycle process as before, and at this point you still need to auto_prepend_file that bootstrap script. So your vhost would look pretty basic:

1
2
3
4
5
6
7
8
9

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /sites/example.com/www
 
    <Directory /sites/example.com/www>
        Options -Indexes, FollowSymLinks
        AllowOverride All
    </Directory>
</VirtualHost>

/sites/example.com/www/.htaccess would contain:

1

php_value auto_prepend_file "/sites/example.com/bootstrap.php"

… and /sites/example.com/bootstrap.php looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?php
    // comb_* functions are all defined in here...
    require '/www/example.com/comb.php';
 
    // set config values via php 
    // ...or in .htaccess using php_value, if comb was built as an extension
    $opt = array();
    comb_init($opt);
 
    // find includes, run REQUEST_METHOD function, e.g., get(), post()
    comb_run();
 
    // render templates if enabled
    comb_render();
 
    // send headers, flush buffer
    comb_send();

That first comb.php that’s being included is the library itself, and would ideally just get loaded as an extension. Even this bootstrap script would be written into the extension and run implicitly if it’s enabled for the vhost. But until I get brave enough to learn how in the world to translate this stuff into C, it’s going to have to exist in PHPland.

Application code

So now we write a “web application” that runs on Comb. I’ll create the following file in the document root (/sites/example.com/www), called index.php:

1

<h1>hello, world!</h1>

That will do exactly what you think it does, as will both of these:

1
2

<?php
    echo "<h1>hello, world!</h1>";

1
2
3
4
5

<?php
function get()
{
    echo "<h1>hello, world!</h1>";
}

And this is where it gets interesting; that get() function was defined, but I obviously didn’t call it explicitly. That’s done automatically in the comb_run() function. If a function exists that matches the incoming request method, it’ll get called, otherwise any output that’s sent will either get buffered and plugged into a template during rendering (if buffering is enabled), or immediately sent back to the client (if buffering is disabled).

Templating

Templating is also automatic. You can change index.php to be:

1
2
3
4
5
6

<?php
function get()
{
    // assign a var to be extracted into the template
    comb_set('title', 'hello, world!');
}

…then create a new file beside it in the document root called index.tpl.php:

1

<h1><?=$title?></h1>

That template file gets detected automatically in the comb_render() function, basically by looking for a file whose name is {script_basename}{template_extension}. The default template extension is set to .tpl.php but that’s configurable, so you can set it to .tpl or .phtml or whatever you’re accustomed to.

For shared templates (e.g., header & footer) the most common practice is to explicitly include them in each template that uses them, like:

1
2
3
4
5

<?php include "header.tpl.php"; ?>
 
<h1><?=$title?></h1>
 
<?php include "footer.tpl.php"; ?>

…which makes you end up with a lot of code duplication if you have many templates using that header/footer combo. I’m personally fond of the layout approach, i.e., a single wrapper template that plugs the wrapped content into place. To accomplish that, output buffering is pretty critical, and there has to be some mechanism in place in the layout template to grab the contents of the buffer. For that, there’s the comb_buffer() function. It’s used like so, in a new template file (also in the document root) called layout.tpl.php:

1
2
3
4
5
6
7
8
9

<html>
<body>
Header stuff
 
<div><?php echo comb_buffer(); ?></div>
 
Footer stuff
</body>
</html>

This will take the output rendered by index.tpl.php and drop it into that div. No need to include anything within the requested template. The comb_render() function not only auto-detects the requested template based off the requested script’s basename, but it also auto-detects the layout. If {layout_name}{template_extension} doesn’t exist (both configurable, “layout” and “.tpl.php” are the defaults), it simply won’t get wrapped.

Directory-Based Filtering

One of my primary goals with Comb is to keep the application simple by relying on as much web server work as I reasonably can. Organizing the application in simple, reasonably-named directories makes this very easy, because there’s no need for an explicit dispatch method that 1) parses the request URI, 2) processes user-defined routes to find a matching controller/handler, 3) instantiates and runs the controller/handler.

To get around this explicit routing/dispatching, Comb simply looks for any prepend or append files in each directory leading down to the requested script. In other words, a request for /account/index.php will actually end up running the following scripts in this order, if they exist:

1
2
3
4
5

/prepend.php
/account/prepend.php
/account/index.php
/account/append.php
/append.php

I’ll refer to this as the execution chain. The prepend and append filenames are also configurable. This enables you to organize your code in such a way that any scripts that require common pre- or post-filtering can simply be placed in the same directory. For example, if the /account directory can only be acessed by authenticated users, your /account/prepend.php script may look like:

1
2
3
4
5
6

<?php
    // assume $user was created in /prepend.php
    if ( !$user->isLoggedIn ) 
    {
        comb_redirect('/login.php');
    }

The comb_redirect() function does three things: 1) adds a Location: header pointing to the specified URL to the internal headers array, 2) halts the execution chain, and 3) turns off rendering. This causes none of the proceeding script in the execution chain to get included, so the comb_run() function will return to the bootstrap script. When comb_render() gets called, it first checks to see if rendering is enabled…it’s not anymore thanks to comb_halt(), so it returns to the bootstrap immediately. Then comb_send() is called, which first sends out any user-specified headers (e.g., Location), then checks to see if rendering is enabled. If so it flushes the buffer…but it’s not enabled, so comb_send() thus returns and the lifecycle is complete.

That’s a crash course in what I’ve got so far. There’s a bit more that I’ll cover in my next post, but in the mean time if you’ve got any feedback on this approach, please let me know…I’m interested to hear other folks’ opinions.

I’ve been using Comb, my experimental PHP framework, for a couple of super-secret projects over the past few months (on those sporadic occasions when I actually write code), and it’s been evolving pretty dramatically. So much so that very little of the original code still exists. I’m still calling it “Comb” though, because the underlying idea is still the same. It’s too time consuming to describe the reasons why I changed each part, so suffice it to say the changes are essentially organizational. Instead I’ll just jump into explaining it from the ground up as it exists now.

To begin with, here’s the now-simplified Apache VirtualHost container that I’m using:

1
2
3
4
5
6
7
8
9
10
11

<VirtualHost *:80>
    ServerName      example.com
    DocumentRoot    /vhosts/example.com/www
    ErrorDocument   404 /404.php
 
    <Directory "/vhosts/example.com/www">
        AllowOverride All
        php_value include_path ".:/vhosts/example.com/www/lib:/vhosts/lib"
        php_value auto_prepend_file /vhosts/example.com/www/comb.php
    </Directory>
</VirtualHost>

The first four lines should be pretty self-explanatory, but for the rest:

7. Allow the full use of .htaccess files, e.g., for rewrite rules, etc
8. Set PHP’s include_path to the current working dir (when parsing templates), the application’s lib dir (for app-specific classes), and the system lib dir (for shared classes)
9. Prepend comb.php in the document root to every requested PHP script.

This Apache configuration ensures that every requested script will first run the site’s comb.php script, which is a very simple, application-agnostic bootstrap script, meaning it’s basically the same for every app that I build. In fact I could just have one copy of it in a central directory and prepend it from there, but I’d lose some potential flexibility that way. Though that could probably be coded around. Anyway, here’s where things get interesting… comb.php looks like this:

1
2
3
4
5
6
7

<?php
    require '/www/include/load.php';
    spl_autoload_register('load');
 
    $comb = new util_comb();
    $comb->run();
    $comb->send();

My standard autoloader is pretty simplistic; it just converts “util_comb” into “util/comb.php” and tries to include it based on the include_path set in the vhost container.

The util_comb class encapsulates all the crucial routing and response rendering logic. The constructor parses the request URI into its segments and loops over them looking for any files called prepend.php and append.php. If they exist, they’re added into an array that I refer to as the inclusion list. To visualize this, imagine a request for /user/profile.php?name=drew. The vhost will start by running comb.php, and the following scripts will get added to the inclusion list if they exist:

/prepend.php
/user/prepend.php
/user/profile.php
/user/append.php
/append.php

…in that order. The idea is to sort of mimic the way Apache finds and parses .htaccess files that are (possibly) in each subdirectory.

The next method that’s called, $comb->run(), simply loops over the inclusion list and include()s each one of them.

Finally, $comb->send() is called, in which the response is created and sent. This is where template rendering or redirecting takes place.

My next few blog entries will go into the details of the inclusion list, how I’ve set up template rendering, and how to get clean/friendly URLs working.

I’ve been using Comb with a few more projects recently. The main point of Comb is to structure the code in such a way that the request handlers get accessed directly via Apache, as opposed to rewriting the entire URL, and making PHP dynamically include or instantiate a request handling class (i.e. Action, Command, etc).

For example, you might have a registration form that is accessed like this (pseudo-HTTP):

1
2
3
4
5

# display the registration page...
GET  /register.php
 
# registration form submits to...
POST /proc_register.php

I personally hate that naming convention because it reminds me of how I wrote code 5 years ago, and it’s just plain ugly.

Here’s a cleaner, friendlier approach that I’d rather use:

1
2
3
4
5

# display the registration page...
GET  /register
 
# registration form submits to...
POST /register

Yep, that’s a postback. And yep, there’s no .php extension used to access it, so some URL rewriting will be in order. I’ll add the following code into my virtualhost container in the Apache config:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# turn on the voodoo
RewriteEngine On
 
# if the incoming request has one of these extensions, 
# just serve up the file without rewriting anything
RewriteRule     /*\.(php|html|css|js|jpe?g)$ - [NC,L]
 
# just a little shortcut to make it easier to deal with 
# case-sensitivity
RewriteMap      lc      int:tolower
 
# make clean/friendly URLs work
# e.g., turn this:  GET /register
#       into this:  GET /register_get.php
# 
# and turn this: POST /register
#     into this: POST /register_post.php
#
RewriteRule  /(.*)  /$1_${lc:%{REQUEST_METHOD}}.php [NC,QSA,L]

After restarting Apache, I’ll create these two files to make sure the rewrite is working properly:

register_get.php

1
2
3
4
5
6
7
8
9
10

<html>
<body>
 
  <form method="post">
    Username: <input type="text" name="username" /><br />
    <input type="submit" />
  </form>
 
</body>
</html>

Note the form tag on line #4, it’s simply <form method="post"> without the expected action="/register" attribute. By leaving the action attribute absent or blank, the browser will simply submit the form back to the current address, i.e., a post-back.

Luckily our rewrite rule will see that the incoming request is a POST instead of a GET, so it’ll route the request into a different script:

register_post.php

1
2
3
4

<?php
    echo "posting registration form...";
    var_dump($_POST);
?>

Nothing magical happening in there, but the point is that mod_rewrite can be used to run different scripts based on the %{REQUEST_METHOD} variable, so you can organize the scripts according to the action being performed. It would even route PUT, HEAD, and DELETE requests to /register_put.php, /register_head.php, and /register_delete.php, respectively…assuming the HTTP client was capable of sending those requests (e.g., AJAX).

I’ve decided to give a name to this barebones framework that I’ve been playing with for the past couple of months. I’m calling it Comb. Unfortunately it takes a long time to fully explain the thinking behind the name. Similar to Camber, however, the jist of it is simplicity; think “get the tangles out of my code”. Plus comb is a lot faster to say and type than MVCish-framework-based-on-autoprependfile-and-output-buffering.

My plan is to build the simplest web app framework that I can. I’m by no means an expert, and I don’t anticipate that this will end up being the best/fastest/most-convenient framework that will lay waste to the Zend Framework, or Symfony, or Kohana (or the mystical Redline! no link…it’s too mystical). I just want to start from the ground-up by making very few assumptions, and without ripping “inspiration” from the latest and greatest RAD framework. I want to end up with a simple base of code that I don’t have to learn how to love, and that can evolve with me without getting in the way. Basically this is all about me, but you can feel free to use it as well if it makes enough sense.

I’ve got a few projects in mind that I’m planning on being powered by Comb. The first is my Code Examples site, which will serve two purposes: it’ll be a place to host demos of basic code for the blog entries I write, and it’ll be a testbed for integrating new features into the framework. And yes, the code that runs the examples site is Comb itself. The other projects will be revealed in time…

I often get the impression that there’s too much unnecessary complexity in the approaches to MVC that are currently in use in PHP, primarily with regard to request handlers and controllers. I’m even guilty of it myself with my ironic attempt at object-oriented simplicity, Camber. So when the mood strikes me, I’ll poke around in forums and articles and look for novel approaches to these problems.

A few years ago, Harry Fuecks posted an entry on his wiki-in-progress regarding PHP and the Front Controller design pattern. I’ve stumbled across this entry a few times before, but I always left it for dead, thinking it was just too simplistic. But recently I decided to try picking up where he left off at the end of his entry to see for myself how far the technique could be taken.

It’s nothing new really. The idea is to use auto_prepend_file and auto_append_file to control the global aspects of your application. For those who are unaware, these two directives allow you to specify scripts that you want to run just before and just after every requested PHP script, either on a per-directory basis, or throughout your entire virtualhost. For example, assume you’ve got a simple personal web site with a page called contact.php that looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php 
    require 'prepend.php'; 
?>
 
<h1>Contact Me!</h1>
<form action="/send_email.php" method="post">
  Send me a message: <input type="text" name="msg" />
  <input type="submit" />
</form>
 
<?php
    require 'append.php';
?>

And for the sake of clarification, prepend.php contains this fragmented HTML as the page header:

1
2
3

<html>
<head><title>My Site!</title></head>
<body>

…and append.php has the rest of the fragment for the footer:

1
2

</body>
</html>

This “header/content/footer” approach should be familiar to every web developer in the universe since it’s often the first time-saving pattern that beginning developers learn. You can do this a little bit cleaner though; instead of explicitly requiring the header and footer, you could simply change your site’s virtualhost container to have these two directives (assuming /path/to/www is your site’s document root):

1
2
3
4

<Directory ".">
    php_value auto_prepend_file /path/to/www/prepend.php
    php_value auto_append_file  /path/to/www/append.php
</Directory>

…and your contact.php file can be trimmed down to just the contact-specific stuff:

1
2
3
4
5

<h1>Contact Me!</h1>
<form action="/send_email.php" method="post">
  Send me a message: <input type="text" name="msg" />
  <input type="submit" />
</form>

This is definitely a better idea than having to require the prepend & append (i.e., header & footer) scripts at the top and bottom of every single script in your web site, but you quickly run into problems when you try to do anything complex. For instance, what happens when a visitor fills out that contact form and submits it to send_email.php:

1
2
3
4
5

<?php
    $msg= isset($_POST['msg']) ? $_POST['msg']: 'i got nothin';
    mail('drew@example.com', 'Some Subject', $msg);
    header('Location: /thanks.php');
?>

This form processing script shouldn’t send any output, other than that header at the end telling the browser to bounce on over to the “thanks” page. The problem here is that prepend.php script is sending output for the top portion of the page, and append.php is closing up all the HTML. That is not only wasteful but also potentially troublesome, especially if that top portion of the page, e.g., the title tag, has to be altered depending on what occurs in the script. You can save a bit of trouble by putting an exit; as the last line of send_email.php to keep append.php from running, but that’s ignoring the fundamental problem…no HTML should be sent at all for this particular request.

The obvious way around this, as Harry points out, is to use Output Buffering. With that in mind, I came up with this:

prepend.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php
    // set some default control values used by append.php
    $app = array(
        'render' => true,
        'redirect_url' => '',
        'template_dir' => '/path/to/www/templates/',
        'layout' => 'layout.tpl'
    );
 
    // start output buffering
    ob_start();
 
    // move into the template dir to make calls to 
    // require() cleaner
    chdir($app['template_dir']);
?>

append.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php
    if ($app['render'])
    {
        // we're rendering, so grab whatever is in the buffer
        $content = ob_get_clean();
        require $app['layout'];
    }
    else
    {
        // screw rendering, erase whatever is in the buffer
        ob_end_clean();
 
        // ...and hopefully we have someplace to redirect to
        header('Location: ' . $app['redirect_url']);
    }
?>

The idea here is to use prepend.php as nothing more than an initialization script. You’d start up the output buffer, maybe start the session, connect to your database, etc. Once this script is done, the requested script (e.g., contact.php) does it’s thing (e.g., displays the contact form).

The interesting stuff really happens in append.php though. First of all, it checks to see if the $app['render'] flag is still set to true. If it is, then the output buffer gets “cleaned” meaning anything that has been echoed is dumped into a string variable, i.e. $content. We then include the specified layout template and everything ends up getting assembled into the same page we originally had.

So contact.php stays the same, but we take all the html that used to be split between the original header and footer scripts, and we combine them into the layout template,layout.tpl which specifies where that previously-buffered-output should be placed:

1
2
3
4
5
6

<html>
<head><title>My Site!</title></head>
<body>
<?=$content?>
</body>
</html>

Now how about sending that email message? All we’ve got to do is modify send_email.php so that it informs append.php to not bother sending any output:

1
2
3
4
5
6
7
8
9
10
11

<?php
    $msg= isset($_POST['msg']) ? $_POST['msg']: 'i got nothin';
    mail('drew@example.com', 'Some Subject', $msg);
 
    // no need to render any HTML
    $app['render'] = false;
 
    // ...but we need to redirect the visitor here, so that 
    // we can properly thank them for sending their message
    $app['redirect_url'] = '/thanks.php'
?>

That should solve the most basic request handling problems, but this is hardly what anybody would call MVC. Where’s the separation between View and Controller? For that matter, where is the Controller itself supposed to reside? How might clean URLs be implemented, e.g., http://example.com/profile/drew? And why do I always ignore the Model?

My answers come in the form of a little bit of discipline, a bucket full of simplicity, and smidgen of reliance on mod_rewrite’s voodoo. But that’s an entry for another day.