C/C++:

#define ADMIN     0
#define MODERATOR 1
#define EDITOR    2

// ... same thing, but less typing...
enum { ADMIN, MODERATOR, EDITOR };

// ... regardless, now you can do ...
int myRole = ADMIN;

As mentioned in my older blog post, there’s no such native enum type or function in PHP, but you can make clever use of array_flip(), apc_define_constants() and apc_load_constants() to ultimately get the same effect.

I finished that old post wanting more, though, namely the ability to specify a namespace into which to define these enumerated constants. This was back in 2008, and I had no clue at the time how namespaces would be implemented in PHP. This has been a reality ever since PHP 5.3 came out, and so I decided to re-tool my previous approach.

To reiterate the problem: I want to specify nothing more than a set of strings, and end up with enumerated constants, with the option of putting them all in an arbitrary namespace to avoid name collisions.

BEHOLD! my_apc_enum() using PHP 5.4’s wonderful new short array syntax:

<?php
    /**
     * Try loading a set of constants from APC, otherwise
     * define them and store them into APC.
     */
    $key       = 'roles';
    $constants = ['ADMIN','MODERATOR','EDITOR'];

    my_apc_enum($key, $constants);

    echo "Admin: "     . ADMIN;     // Admin: 0
    echo "Moderator: " . MODERATOR; // Moderator: 1
    echo "Editor: "    . EDITOR;    // Editor: 2

    /**
     * OR you can put them all in a namespace
     */
    $key       = 'blogRoles';
    $constants = ['ADMIN','MODERATOR','EDITOR'];
    $namespace = 'blog';

    my_apc_enum($key, $constants, $namespace);

    echo "Admin: "     . blog\ADMIN;     // Admin: 0
    echo "Moderator: " . blog\MODERATOR; // Moderator: 1
    echo "Editor: "    . blog\EDITOR;    // Editor: 2

Another neat way to quickly see all constants you’ve defined, whether explicitly using define() one constant at a time, or using apc_define_constants(), is to use get_defined_constants():

<?php
    // array dereferencing! if you have PHP 5.4 ...
    print_r(get_defined_constants(true)['user']);

    // PHP 5.3 and below, you gotta do ...
    $constants = get_defined_constants(true);
    print_r($constants['user']);

Anyway, here’s how my_apc_enum() is implemented:

<?php
function my_apc_enum($key, $constants, $namespace = null) {

    // try loading the constants from APC
    if (!apc_load_constants($key)) {
    
        // was a namespace specified?
        if (!empty($namespace)) {
	    	
            // yep! prepend the namespace onto each constant name
            foreach ($constants as &$c) {
                $c = $namespace . '\\' . $c;
            }
        }

        // make APC define them all
        apc_define_constants($key, array_flip($constants));

        // APC cache miss :-(
        return false;
    }

    // APC cache hit :-)
    return true;
}

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 makes it easier to sort of move those functions out of the line of fire, but they’re still on the battlefield. 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:

<?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 considering that for a bit, I remembered that PHP 5.3 introduced closures. So instead of the request script looking like this:

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

I could do this:

<?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, called $method_chains. 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:

 
function comb_handle($http_method, $closure)
{
    /**
     *  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($http_method)][] = $closure;
}

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:

/* /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:

array(1) {
  ["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:

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

feels cleaner (though weirder) than:

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

Might as well start getting used to using namespaces though. They’ll be getting much more common over the next couple of years.

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:

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

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

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

<?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. (someday!)
     */
    $opt = array();
    comb_init($opt);
 
    // find includes, run REQUEST_METHOD function, eg, 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 called index.php:

<h1>hello, world!</h1>

That will do exactly what you think it does: a big bold howdy. As will this:

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

And actually, this will too:

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

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

<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), a common practice is to explicitly include them in each template that uses them, like:

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

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

/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 accessed by authenticated users, your /account/prepend.php script may look like:

<?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, but 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 on this approach.

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

<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"
        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
9. 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)
10. 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:

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

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

<?php
    define('ADMIN',     0);
    define('MODERATOR', 1);
    define('EDITOR',    2);

but that isn’t exactly succinct. I’d rather have something like this:

<?php
    enum('ADMIN', 'MODERATOR', 'EDITOR');
    // ADMIN == 0 
    // MODERATOR == 1 
    // etc.

Of course, that won’t work. enum() doesn’t exist in PHP. You can kind of mimic the enumerated values with arrays like so:

<?php
    $roles = array(
        'ADMIN'     => 0,
        'MODERATOR' => 1,
        'EDITOR'    => 2,
    );

but having to specify those values is tedious. There’s an easy trick to get around that though:

<?php
    $roles = array(
        'ADMIN',
        'MODERATOR',
        'EDITOR',
    );

    /*
    Array
    (
        [0] => 'ADMIN'
        [1] => 'MODERATOR'
        [2] => 'EDITOR'
    )
    */
 
    $roles = array_flip($roles);
 
    /*
    Array
    (
        [ADMIN]     => 0
        [EDITOR]    => 1
        [MODERATOR] => 2
    )
    */
 

Which is cool! But not cool enough, because I want constants, not just array values. Which is cleaner?

if ($role == $roles['ADMIN']) // ew  :(
if ($role == ADMIN)           // ahh :)

So a bit more digging, and I found that APC can turn an array into a bunch of constants in one fell swoop!

<?php
    /**
     * Try loading the constants from APC
     */
    if (!apc_load_constants('roles'))
    {
        /**
         * they aren't in APC, so make 'em and define 'em
         */
        $roles = array_flip(array(
            'ADMIN',
            'EDITOR',
            'MODERATOR'
        ));
 
        apc_define_constants('roles', $roles);
    }
 
    /**
     * Now we've got enumerated constants!
     *  ADMIN     == 0
     *  MODERATOR == 1
     *  EDITOR    == 2
     */

Obviously you need APC to make this work. One great thing about using apc_load_constants() is that you might get a modest speed boost because you don’t have to define() all of your constants every time the script runs. Another benefit is that you can load up your array of roles (or whatever your constants are, e.g., permissions, etc.) from a database or other dynamic source, and convert them into global constants with one function call.

Now what would be even cooler is if you could tell apc_load_constants() to load the constants into a specific namespace, maybe something like:

<?php
    apc_load_constants('roles', true, 'drew');
 
    echo "ADMIN's value: " . drew::ADMIN;

How cool would that be? Though that kind of namespace madness will need to wait until PHP 5.3 I assume.

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

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

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

# 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

<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

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

<?php
    $page = isset($_GET['page']) ? (int) $_GET['page']: 1;
    $size = 10;
    $offset = ($page - 1) * $size;
 
    $db = new mysqli("localhost", "drew", "mypass", "db");
 
    $sql = "SELECT username FROM user LIMIT $offset, $size;"
         . "SELECT COUNT(*) FROM user";
 
    $users = array();
    $total = 0;
 
    if ($db->multi_query($sql) && $res = $db->store_result())
    {
        // fetch this page of user records
        while (list($name) = $res->fetch_row())
        {
            $users[] = $name;
        }
 
        // fetch the TOTAL number of users
        $db->next_result();
        list($total) = $db->store_result()->fetch_row();
    }
 
    $pages = ceil($total/$size);
 
    echo "Total Users: $total<br>";
    echo "Total Pages: $pages<br>";
    echo "Current Page: $page<br><br>";
 
    foreach ($users as $u) echo "$u<br>";
 
    if ($page > 1) 
        echo '<a href="?page=', $page-1, '">&laquo; Prev</a>';
 
    if ($page > 1 && $page < $pages) 
        echo " | ";
 
    if ($page < $pages) 
        echo '<a href="?page=', $page+1, '">Next &raquo;</a>';

<?php
    // ... change this:
    $sql = "SELECT username FROM user LIMIT $offset, $size;"
         . "SELECT COUNT(*) FROM user";
 
    // ... to this:
    $sql = "SELECT SQL_CALC_FOUND_ROWS username FROM user LIMIT $offset, $size;"
         . "SELECT FOUND_ROWS()";