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.

Over the past few months I’ve been adding code to this previously unnamed LAMP framework, but I’ve honestly been reluctant to call it a framework. That’s what it is though, so instead of constantly referring to it as “my little minimalist pseudo-framework”, I decided to give the thing a name. I’ve been mulling it over for several months now, and finally settled on Camber as the name. I wanted to be sure that it was easy enough to remember, but also meaningful to the overall goal of the project. According to Google:

Camber: The curvature of a structural member for the purpose of offsetting the deflection when loads are applied.

Camber is not a complex idea, nor is it difficult to implement where it’s needed. It’s used in many everyday load-bearing applications; the wheels of a car, the shape of skis and snowboards, the bottom of a bridge, the shape of a wing. The performance of each of these is greatly enhanced – if not utterly dependent – on something as simple as the underlying negative curvature.

Sounds like a pretty good description of a web application framework, eh?

Unfortunately, I’ve been really slack about keeping this here blog up to date with the actual code I’ve been writing. I have a tendency to drone on and on about each concept of the system, so I think I need to take smaller bites. One post per day maybe, with no more than 2 or 3 snippets of code.

So, picking up from where I left off in Step 3, cleaning up the server-side, we’ve now got a simple HTML form that sends a clean request into the server, and a nice little Request class to make the incoming data easy to work with. To jog your memory, the form looks like:

1
2
3
4
5
6

<form action="/session" method="post">
  <input type="hidden" name="method" value="put" />
  Username: <input type="text" name="username" /><br />  
  Password: <input type="password" name="password" /><br />  
  <input type="submit" value="Login..." />  
</form>

When the form gets submitted, index.php creates a new Request object to encapsulate all the request data. But once the Request is all set up, then what? My goal here is to log the user into their account, or if I read the HTTP request the way I intended it to be interpreted, I want to…

Put a session on the server with the specified username and password.

Well, the most straightforward way to do this would be to just stick all the input-sanitizing, database-connecting, user-authenticating logic directly after the Request object is born, making index.php look something like this:

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<?php
    include 'Request.php';
 
    /**
     * create the request
     */
    $req = new Request();
 
    /**
     * pull the necessary data out of the request
     * i.e., 
     *  username=drew&password=qwerty
     *
     * In real life, error checking and validation would be a good idea here
     */
    $username = $req->params['username'];
    $password = $req->params['password'];
 
    /** 
     * Connect to the db and see if the username/password combo is valid
     * I like mysqli: http://www.php.net/mysqli
     */
    $db = new MySQLi('localhost', 'dbuser', 'securepassword', 'dbname');
 
    $sql = 'SELECT UserID FROM Users WHERE Username = ? AND Password = MD5(?)';
    if ($stmt = $db->prepare($sql))
    {
        $stmt->bind_param('ss', $username, $password);
        $stmt->execute();
        $stmt->bind_result($userID);
        $stmt->fetch();
 
        if ($userID == 0)
        {
            die("access denied, try again.");
        }
        else
        {
            die("access granted! userid: $userid");
        }
 
        $stmt->close();
    }
 
?>

Hopefully it is obvious to you that putting all that code smack in the middle of the site’s one-and-only index.php would suck really badly. Afterall, index.php has to handle every single request. The only reasonable way to go about this is to have some sort of dynamically loaded request-examining code. I’ll have to decide on some standard way to look at every request, and depending on the method, path, and parameters, load up some request-specific logic on the fly. Something to this affect:

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

<?php
 
    include 'Request.php';
    include 'RequestHandler.php';
 
    $request = new Request();
 
    /**
     * Create this magical object that "handles" the given $request object
     */
    $handler = new RequestHandler($request);
 
    /**
     * Tell the RequestHandler to do the dirty work
     */
    $handler->run();
 
?>

This would get the clutter out of index.php and into the RequestHandler object. Of course, the RequestHandler is a black box at this point, but the idea is to use that class in such a way as to load up and run the request-specific logic, i.e., form validation, database querying, and of course output.

Step 5 will consider what exactly the RequestHandler needs to do, and how we might need to modify our currently bare-bones index.php bootstrap.

Once I had my virtual host set up to route all requests into a single script, I then had to figure out what to do with each request. I knew that the essential request information was available in the $_SERVER autoglobal, but I wanted a cleaner way of dealing with the request. So I put together a very simple Request class, which I saved in the document root as Request.php:

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

<?php 
class Request 
{ 
    public $method; 
    public $url; 
    public $parameters = array();  
    public function __construct() 
    { 
        $this->method = $_SERVER['REQUEST_METHOD']; 
        $this->url = $_SERVER['SCRIPT_URI']; 
        $this->parameters = $_REQUEST; 
    } 
} 
?>

I then altered index.php to contain the following:

1
2
3
4
5
6
7
8
9
10

<?php
    include 'Request.php';
 
    $req = new Request();   
 
    echo "Method: {$req->method} <br />";
    echo "URL: {$req->url} <br />";
    echo "Parameters: <code>" . print_r($req->parameters, true) . "</code>";
 
?>

To give it a test run, I pointed my browser to http://dev.cholmon.com/some/fake/path?name=drew&gender=male and it showed me:

1
2
3
4
5
6
7
8

Method: GET
Path: /some/fake/path
Params:  
Array  
(  
    [name] => drew  
    [gender] => male 
)

This is exactly what I was expecting. So I decided to try it with my RESTful login form from Step 2. I saved that HTML code:

1
2
3
4
5

<form action="/session" method="put">
  Username <input type="text" name="username" />  
  Password <input type="password" name="password" />
  <input type="submit" value="Login..." />  
</form>

…into the document root as login.html, but then I remembered that Apache wasn’t going to serve that file properly because of my RewriteRules. I had a rule in the vhost container that let images, css, and js files get served up as-is, so I just added “html” as another file extension. In other words, this:

RewriteRule /\w+\.(css|js|gif|png|jpe?g)$ – [NC,L]

Became this:

RewriteRule /\w+\.(html|css|js|gif|png|jpe?g)$ – [NC,L]

I made the change and restarted Apache, then I hit http://dev.cholmon.com/login.html and got the little login form as expected. When I tried submitting the form, however, I noticed a slight problem. The page displayed everything properly except for the request method:

1
2
3
4
5
6
7
8

Method: GET
Path: /session  
Params:  
Array  
(  
    [username] => drew  
    [password] => mypass  
)

Where did that GET come from? I specified “put” as the method in my form element, so how did that get translated into a “get”? I decided to try a few other tests; if PUT became GET, what would DELETE become? I changed login.html to use method="delete" in the form element, but I got the exact same result when I submitted the form. What about method="omgwtf"? No good, it displayed as GET again. What about just leaving the method attribute out of the form element altogether? You guessed it…GET. The only way I could make the thing show up any different is if I put method="post" in the form. So I came to the conclusion that my browser only knows how to send GET and POST requests. After a bit of googling, I also came to the conclusion that I am probably one of the last web developers to realize this little limitation.

GET and PUT are only the “RU” of CRUD though, and I want the whole thing. So I had to figure out some way to force my request method through. So I rigged up the form with the most obvious solution:

1
2
3
4
5
6

<form action="/session" method="post">
  <input type="hidden" name="method" value="put" />
  Username: <input type="text" name="username" /><br />  
  Password: <input type="password" name="password" /><br />  
  <input type="submit" value="Login..." />  
</form>

Basically the idea is to wrap any PUT or DELETE requests inside a POST request by specifying a hidden “method” parameter that effectively overrides the form’s “method” parameter. I just had to modify the Request class to do that overriding inside the constructor. After a few minutes I came up with:

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

<?php
class Request
{  
    public $method;  
    public $url;  
    public $parameters = array();    
 
    public function __construct()  
    {  
        $this->url = $_SERVER['SCRIPT_URI'];  
        $this->parameters = $_REQUEST;  
        $method = strtoupper($_SERVER['REQUEST_METHOD']);  
 
        if ($method == 'POST' && isset($this->parameters['method']))  
        {  
            $tunneledMethod = strtoupper($this->parameters['method']);  
            if (strtoupper($tunneledMethod == 'DELETE' || $tunneledMethod != 'PUT')  
            {  
                $method = $tunneledMethod;  
            }  
        }  
        else if ($method != 'PUT' && $method != 'DELETE')  
        {  
            $method = 'GET';  
        }  
        $this->method = $method;  
    }  
}  
?>

I then went back and refreshed my new, slightly hacked login.html, and upon submitting it I was relieved to be presented with:

1
2
3
4
5
6
7
8

Method: PUT
Path: /session
Params:  
Array  
(  
    [username] => drew  
    [password] => mypass  
)

I had successfully tunneled my intended request method inside of a POST request, and while the constructor for my little Request class became a good bit uglier, I couldn’t care much less. That’s a small price to pay for what will hopefully be a cleaner way to build my PHP apps.

Of course, the hard part is deciding how to actually use those three crucial pieces of information about the request to do anything meaningful. I know that I want to create a new session with the supplied username and password, but I’d be insane to put that exact application logic directly in index.php. Instead, I need a generic way to look at the request’s path and determine what resource is being requested. Is a user trying to login? Does an article need to be deleted? Does a blog entry need to be updated? Does a list of books need to be displayed?

In Step 4, I’ll introduce the Controller class and explain how it looks at the guts of the incoming request and decides what to do accordingly.

So why am I bothering with “clean” URLs? For several reasons really. For one thing, they look nicer than un-clean URLs. I would much rather get rid of something like, this:

http://www.example.com/forumDisplay.php?fid=17

and instead use something like this:

http://www.example.com/forum/general

But aesthetics aside, why should I bother? My reason is inspired by Roy Fielding’s REST. I won’t try to get into the guts of it here, partly because there’s alot to it, and partly because my grasp of it is far from complete. Regardless, what I’ve taken from my brief introduction to it is a resolution to build applications from a resource-centric point of view, as opposed to a functional, process-centric point of view. Instead of building a collection of scripts that expect data to be passed in so that they can spit data out, I decided to try to build a system of resources that can be manipulated.

In order to manipulate a resource, three essential pieces of information are requried:

1. The location of the resource in question (the URL)
2. The type of manipulation to be performed on the resource (HTTP method…PUT, GET, POST, DELETE)
3. The data needed to perform the manipulation (request parameters)

One thing I noticed at this point was that the request method could essentially take the place of the action parameter I’ve seen being passed around in so many frameworks (and which I’m guilty of having used in the past). With any resource in mind (e.g., user object, news article, forum thread, photo album, etc), PUT, GET, POST, and DELETE can do pretty much anything you need…or at least imply your intention to do pretty much anything.

Also, those four major request methods map pretty conveniently to CRUD:

• PUT == CREATE
• GET == READ
• POST == UPDATE
• DELETE == DELETE

I figured a good place to start trying to implement something like this would be structuring the URLs in such a way that they look like nouns. So an old school login form may have looked like:

1
2
3
4
5

<form action="/login.php" method="post">
  Username <input type="text" name="username" /><br />
  Password <input type="password" name="password" /><br /> 
  <input type="submit" value="Login..." />
</form>

The problem with that code (RESTfully clean URLs in mind) is the action and the method. The form is POSTing the username and password to login.php. But is login.php really the resource that I want to POST to? If I replace the word POST with the word UPDATE, it makes a little bit less sense. I’m not updating login.php itself. That script doesn’t represent a resource of any kind…it’s just a procedure, a machine that takes data in one side and spits data out the other.

So I took a step back and thought about what I was actually trying to accomplish. I wanted to authenticate a user; check their username and password against the database, and if it matched a valid user record then stick their information in the session for use throughout their visit.

In other words, my goal was to create an authenticated user session. Since “create” maps to the PUT method, I decided to change the form around to look like this:

1
2
3
4
5

<form action="/session" method="put">
  Username <input type="text" name="username" /><br />
  Password <input type="password" name="password" /><br /> 
  <input type="submit" value="Login..." /> 
</form>

My intention was to provide the following information to the web server:

• Location of the resource: /session
• Operation to be performed on the resource: PUT (i.e., create)
• Additional information needed to operate on the resource: username and password

It seemed a good bit more logical this way. Instead of telling the web server, “here’s a username and password that I want the login script to process”, I told the web server, “I want to create a new session based off of this username and password“.

The tricky part was actually writing the code to interpret the request in such a way that this actually happened like I wanted. Step 3 is coming up next. In it I’ll explain my inital approach to solving my RESTlessness, and some unexpected problems I ran into along the way.

Using clean URLs with Apache is fairly simple with mod_rewrite’s help. I’d be the first to admit that rewrite rules can be as ridiculously complicated as they are powerful, but plenty of people have already admitted this. Luckily, what I’m trying to accomplish is not very difficult, mod_rewrite-wise. Taking a forum as an example, you might see URLs like:

• http://www.example.com/ – site’s main page
• http://www.example.com/forum – list of forums
• http://www.example.com/forum/general – list all threads in general forum
• http://www.example.com/forum/general/some_arbitrary_topic – list all posts in some_arbitrary_topic thread

To handle URLs similar to this, I set up the virtual host container to simply rewrite every request through a single PHP script, which I’ll lovingly call index.php. To start off, it just looks like this:

1
2
3

<code>
<?php print_r($_SERVER); ?>
</code>

Pretty basic and useless. It just dumps out everything about the request and the server environment in an easy-to-read manner. But we have to tell Apache to use index.php for everything, so the virtual host container in Apache’s config file looks like this:

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

<VirtualHost *:80>
    ServerName      dev.cholmon.com 
    DocumentRoot    /www/vhosts/cholmon.com/dev/
 
    RewriteEngine   On 
    RewriteRule     /*\.(css|js|gif|png|jpe?g)$ - [NC,L] 
    RewriteRule     ^/* /index.php
 
    <Directory "/www/vhosts/cholmon.com/dev/">
                AllowOverride None 
                Order allow,deny 
                Allow from all 
     </Directory>
</VirtualHost>

(To read up on configuring virtual hosts and figuring out mod_rewrite, check out http://httpd.apache.org/docs/2.2/)

Those three rewrite directives accomplish the following:

1. RewriteEngine On: tells apache to expect some rewrite rules
2. RewriteRule /*\.(css|js|gif|png|jpe?g)$ - [NC,L]: don’t rewrite images, stylesheets, or javascripts.
3. RewriteRule ^/* /index.php: any other request should just run index.php

So, for instance, if you type http://dev.cholmon.com/some/made/up/path?this=that&foor=bar into your browser’s address bar, the request would get sent into index.php and you’d see the following (pay particular attention to the bolded parts):

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

Array 
( 
    [SCRIPT_URL] => /some/made/up/path 
    [SCRIPT_URI] => http://dev.cholmon.com/some/made/up/path 
    [HTTP_ACCEPT] => image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash, application/vnd.ms-excel, application/vnd.ms-powerpoint, application/msword, */* 
    [HTTP_ACCEPT_LANGUAGE] => en-us 
    [HTTP_UA_CPU] => x86 
    [HTTP_ACCEPT_ENCODING] => gzip, deflate 
    [HTTP_USER_AGENT] => Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; .NET CLR 1.1.4322; .NET CLR 2.0.50727; InfoPath.1) 
    [HTTP_HOST] => dev.cholmon.com 
    [HTTP_CONNECTION] => Keep-Alive 
    [PATH] => /mono/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/bin/X11:/usr/local/sbin:/usr/local/bin 
    [SERVER_SIGNATURE] =>
    [SERVER_SOFTWARE] => Apache/2.2.0 (Unix) mod_ssl/2.2.0 OpenSSL/0.9.7e DAV/2 PHP/5.2.0 mod_transform/0.6.0 mod_mono/1.1.13.5 
    [SERVER_NAME] => dev.cholmon.com 
    [SERVER_ADDR] => 65.111.167.214 
    [SERVER_PORT] => 80 
    [REMOTE_ADDR] => 65.4.76.89 
    [DOCUMENT_ROOT] => /www/vhosts/cholmon.com/dev/ 
    [SERVER_ADMIN] => [no address given] 
    [SCRIPT_FILENAME] => /www/vhosts/cholmon.com/dev/index.php 
    [REMOTE_PORT] => 57503 
    [GATEWAY_INTERFACE] => CGI/1.1 
    [SERVER_PROTOCOL] => HTTP/1.1 
    [REQUEST_METHOD] => GET 
    [QUERY_STRING] => this=that&foor=bar 
    [REQUEST_URI] => /some/made/up/path?this=that&foor=bar 
    [SCRIPT_NAME] => /some/made/up/path
    [PHP_SELF] => /some/made/up/path 
    [REQUEST_TIME] => 1169876370 
)

At this point, the main parts of the request that I’m interested in are:

• The method (GET)
• The script name (/some/made/up/path)
• The query string (this=that&foor=bar)

Step 2 will be up here in the next day or so.  In it, I’ll modify index.php so that it parses those three pieces of information and decides what to do with the request. OMG STAY TUNED LOL!!!

I’ve lost count of the number of times I’ve created a blog and started off posting stuff to it, only to get slack and let the thing fester for months and, inevitably, deleted it. This particular time I’ve got a decent reason that I think will help me keep the thing going. I’ve been working on a project – some might call it a framework – to make building web applications in PHP a little more tolerable. I’ve built half-assed frameworks before for the guts of various web sites, but I seem to have a bad habit of falling into a deep dark state of despair with my code. It’s like I work through the Gee, this is fun and new and interesting! phase and too quickly get to the Lord, this wasn’t such a good idea, when will this be over? phase…and I make that transition before the project gets any where near being complete.

So I decided to try starting from scratch. Here’s what I wanted to accomplish:

• Very close proximity to HTTP. I hesitate say RESTful because that’s a pretty high benchmark, but that’s sort of the idea. 
• Implicit support for clean URLs. Heck, make them required.
• Built-in, pure PHP templating. I want to reap all the benefits of APC without having to compile my own made-up template language to PHP.
• Barebones. My overall goal is just finding a decent way to organize all the code, so I’m ignoring things like I18N, PHP4 compatability, and support for shared hosting environments.

I’ve got some basic code working, but I’m not really pleased with all of it so it’s very much experimental.  I’ll try to relate my thought process in as logical a manner as I can muster over the next few days in an attempt to explain the thing.