Output Handlers Instead of Views

We'll have as many output handlers as we have supported output formats. The joy of having all the controllers return the data to index.php is that we can then add common output handling to all the data. In our example system, we can remove that ugly print_r from index.php and instead detect which output format is needed and load the relevant view. My code looks like this:

    $view_name = ucfirst($request->format) . 'View';
    if(class_exists($view_name)) {
        $view = new $view_name();
        $view->render($result);
    }

The most simple example is a JsonView which looks like this:

 
class JsonView extends ApiView {
    public function render($content) {
        header('Content-Type: application/json; charset=utf8');
        echo json_encode($content);
        return true;
    }
}

As you can see here, it's pretty simple! We send the Content-Type header first to let the consumer know what's in the response, then we just encode the JSON and echo it out.
To support other formats, you might loop over your array (remember it might be nested – things usually get recursive at this point for something like an XML format) and transform it into the new format. Between two PHP systems, it might be simpler to support serialised PHP as a format as it is a little more verbose than the JSON.

I also like to support HTML as an output format - for example the joind.in API does this; just go to http://api.joind.in with your browser and it will realise you're a web browser and return you the HTML version. Joind.in is open source and since I wrote its RESTful API, it looks a lot like this one! You can see the HTML output handler at: https://github.com/joindin/joind.in/blob/master/src/api-v2/views/HtmlView.php

One format that I often get asked about is JSONP – so that other sites can make calls to the API from JavaScript and get around the cross-domain policy. The way that I've implemented this in the past is to check for a parameter called "callback" with a request for JSON format, and if I get it, then just wrap the function around the response I would normally send. I blogged about it here and again, this feature is in joind.in's codebase if you want to take a look.

Along with the data from the controller, it can also be useful to add some additional information to your output handlers, such as a count of how many top-level records were returned, and sometimes some pagination (I think I could write a whole other post about hypermedia and pagination - if you want it, leave me a comment). This additional functionality should be added in the parent ApiView class - this just has a few helper functions which the various output formats can use if they want to. Having it all central means that the responses will be very consistent across all the requests made to this service, and between formats. Consistency is absolutely the key to a good API so more shared functionality is always good.

There you have it, one functioning RESTful (ish! we skated over a few issues here, read the comments on all the posts in the series) server. You can test it by calling your service from cURL or writing a script to consume it from PHP instead. Since this was a simple tutorial there are some areas where I'd have liked to have gone in to more detail but it is already quite long-winded, so I'll stop there and if I get any good questions in the comments, I may add some followup posts!

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

Get the Server Running

The server runs when you pass the -S switch to PHP on the command line. I had actually compiled PHP 5.4 alongside my existing PHP 5.3 installation, using instructions from an earlier post, and I just specified the full path to the version of PHP I wanted to run). You then supply the server name and port number:

php -S localhost:8080

This gives some initial output, and then information about each request as it comes in:

PHP 5.4.0RC7-dev Development Server started at Sun Jan 29 16:40:49 2012
Listening on localhost:8080
Document root is /home/lorna/test
Press Ctrl-C to quit.
[Sun Jan 29 16:40:55 2012] 127.0.0.1:46713 [200]: /
[Sun Jan 29 16:40:55 2012] 127.0.0.1:46714 [404]: /favicon.ico - No such file or directory

By default, the current directory is your webroot and you can now request whatever files are here, and run PHP in the usual way. You can also edit and save those files and re-request them without restarting the server, just as you would with a normal webserver (something I love about PHP).

The port number can be absolutely anything that you're not already using, I've seen examples with 8080, 8000 and even 1337 - you can use whatever you like. If you pick a port that something else is using, you'll see an error Failed to listen on localhost:8080 (reason: Address already in use)

Changing the DocRoot

If you want to run the server from one place and point it at a document root in another location, simply use the -t flag, followed by the path to the new docroot:

php -S localhost:8080 -t /var/www/awesomecode

Bear in mind that the webserver will run as the user you run this command as, so that user will need to have access to those files. Webservers such as apache often run as other users, but this one will probably run as you.

Routing Requests Like Apache Rewrite

One immediate feature that I was looking for was the ability to redirect all incoming requests to index.php, which I usually do with an .htaccess file. This webserver doesn't support those (although my good friend Josh has created something pretty close) but it does support a routing file. There's a great example in the manual of doing this which I used for reference. You create a file routing.php in the same directory and this becomes your front controller, looking like this:

   if (file_exists(__DIR__ . '/' . $_SERVER['REQUEST_URI'])) {
     return false; // serve the requested resource as-is.
   } else {
     include_once 'index.php';
   }

(this code taken entirely from this internals post as linked from the user contributed notes. It works like a charm but I can't take the credit for it!)

This allows you to serve any files which are access by path in the usual way, but then redirect all other requests through to index.php. It's such a common use case and I'm very pleased so see the examples already in the manual.

Changing the Host Name

You don't have to call your server localhost; in fact, you might choose to give it another name and access it from other machines. To do this, simply add the new server name into /etc/hosts (or the equivalent for your system) and then start the server with the new name (I use my computer's name)

php -S taygete:8080

This means that you can set up the same alias for another user and they can access your server - very neat!

Notes About the PHP Web Server

This makes a very neat quick way of throwing up a test site for a particular document root without any need to reconfigure apache or set up anything else. I'm using it to try out a few PHP 5.4 features without switching versions of PHP in and out of apache, and it works really well for that. It is only recommended as a development tool however, and isn't intended for production use. That said, it's a nice addition to the ever-impressive toolset of PHP and I'm happy to have it.

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

Routing to Controllers

In this setup, we'll have models, controllers and ... output handlers. It's not really a view, because all we will do is transform the data to a given output format. More on that later on - for now we will return the data we fetch in the controller back to index.php, and dump it out so we can inspect it.

For RESTful routing, each thing in the system is considered as a resource, and it has a unique resource identifier (or URI) to represent it. In this example system, we have users and groups. Each resource belongs to a collection, which is the level above the resource – I usually think of files being in directories when I think of resources belonging to collections.

So for an incoming GET request to /users, we will return a list of users as this is the collection. Within our application, this means calling the getAction() on the UsersController, so index.php now looks like this:

// route the request to the right place
$controller_name = ucfirst($url_elements[1]) . 'Controller';
if (class_exists($controller_name)) {
    $controller = new $controller_name();
    $action_name = strtolower($verb) . 'Action';
    $result = $controller->$action_name();
    print_r($result);
}

At this point, you'll write a controller and model that will look hauntingly familiar from all the other MVC systems you've ever written! Before we do that though, let's talk about architecture and autoloading.

Designing and Loading Classes

Working with classes gets much easier if you put them in reliable places and call them reliable names. If you do, you can autoload them and avoid all those tedious require() statements. My directory structure looks like this:

.
├── controllers
│   ├── MyController.php
│   └── UsersController.php
├── index.php
└── models

The users controller is in the controllers directory, and it inherits from a shared parent controller called MyController. I have no idea what will go into here, but from experience, I recommend that both models and controllers should inherit from a shared parent - as will our output handlers (because we don't have views) later on. You can see that the controllers are reliably found in the controllers directory, called something ending in *Controller.php. This makes it simple to add to an autoload rule: here's mine, which lives at the top of index.php:

spl_autoload_register('apiAutoload');
function apiAutoload($classname)
{
    if (preg_match('/[a-zA-Z]+Controller$/', $classname)) {
        include __DIR__ . '/controllers/' . $classname . '.php';
        return true;
    } elseif (preg_match('/[a-zA-Z]+Model$/', $classname)) {
        include __DIR__ . '/models/' . $classname . '.php';
        return true;
    } elseif (preg_match('/[a-zA-Z]+View$/', $classname)) {
        include __DIR__ . '/views/' . $classname . '.php';
        return true;
    }
}

Hopefully this is simple enough to follow; if the classname ends in "Controller", look in the controllers directory; if it ends in "Model" look in the ... you get the picture. Using very predictable naming and an autoload means that PHP will always find our classes easily (and we'll find them too when we are maintaining the system).

The RESTful Controller

This section is the part where you already know all you need to know! At least, if you've used MVC before, and you've ever written a controller, then the controller in your RESTful application will look a lot like the one in any other! It will talk to the model to fetch data, get everything in order and then pass it all on to a view.

In a RESTful system, the view is replaced by an output handler, so our controller will get everything assembled into an array and return it instead. Our controllers deal with a variety of HTTP verbs, but will also need to parse out nested records. Here's a super-simple example:

class UsersController extends MyController
{
    public function getAction($request) {
        if(isset($request->url_elements[2])) {
            $user_id = (int)$request->url_elements[2];
            if(isset($request->url_elements[3])) {
                switch($request->url_elements[3]) {
                case 'friends':
                    $data["message"] = "user " . $user_id . "has many friends";
                    break;
                default:
                    // do nothing, this is not a supported action
                    break;
            } else {
                $data["message"] = "here is the info for user " . $user_id;
            }
        } else {
            $data["message"] = "you want a list of users";
        }
        return $data;
    }
 
    public function postAction($request) {
        $data = $request->parameters;
        $data['message'] = "This data was submitted";
        return $data;
    }
}

In the getAction() we show some handling of requesting specifc resources and elements within those as well as just the collection; there is a very simple postAction() shown here too and the postAction() and deleteAction() would follow the same themes. You would only declare all of these if you want to actually support those actions over your API. For example, you might choose not to allow edit or delete of records, depending on your application.

At the moment, you have a working system, although all it does is print_r() the data it finds. The next installment of the tutorial will deal with output handlers and how to send well-formatted data in a RESTful response.

Edit: You can read the third entry in the series here.

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

In the first part of this (probably) 3-part series, we'll begin with the basics. It might seem boring, but the most important thing to get right with REST is parsing all the various elements of the HTTP request and responding accordingly. I've put in code samples from from a small-scale toy project I created to make me think about the steps involved (should I put the code somewhere so you can see it? Let me know). Without further ado, let's dive in and begin by sending all requests through one bootstrap script:

Send Everything to index.php

The first thing we need to do when we serve a RESTful response is the same as the first thing we do when we serve any other web page: figure out what the user actually wanted and how to deliver that.

To support the "pretty URLs" that we see in RESTful services (actually REST is way more complicated than that, but if I start talking about that as well, you'll still be reading in 3 hours' time! Wikipedia has rather a good explanation), we'll add a .htaccess file to our directory which redirects all the requests to index.php. My .htaccess file therefore looks like this:

    RewriteEngine On
    RewriteBase /

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php/$1 [L]

This assumes you're using apache with mod_rewrite; the same thing can be achieved with other webservers. With this in place, all requests to the service will arrive into the top of index.php – exactly the same way as most of the MVC (model-view-controller) frameworks work. In fact, this whole RESTful service is going to be very MVC in style, because it makes sense to me to build things this way.

That said there are definitely other options; I've also worked with Slim, which is a microframework. This is neat as it lets you register a combination of URL and verb, and specify a callback that should be triggered when a matching request comes in. It's lightweight and fast ... again, probably a post in itself if I start talking about it.

Figure Out What Was Requested

There are a few things we will want to know about what we have received here:

• The URL of the request
• The method (GET, POST, PUT or DELETE) of the request
• Any data that arrived with it

Let's begin by looking at the first two elements; the code for these are common to all requests so we'll put it in index.php as all requests come here in the first instance. I'm going to store all the details about the request in a Request object, which also has the functionality needed to parse all that information. Here are the first few lines of that object:

class Request {
    public $url_elements;
    public $verb;
    public $parameters;
 
    public function __construct() {
        $this->verb = $_SERVER['REQUEST_METHOD'];
        $this->url_elements = explode('/', $_SERVER['PATH_INFO']);

We use the $_SERVER variable to pull information about the incoming request; the method is in $_SERVER['REQUEST_METHOD']. The URL comes from $_SERVER['PATH_INFO'] and we can split it into it's various parts using explode(). From these parts, we'll see what the user requested and we'll work out how to route the request.

Incoming Data

To parse the incoming data, we'll need different approaches depending on what kind of request it was and what format the data is in. We'll check the verb that was used, however for requests with a body (POST and PUT requests) we will also check the Content-Type header. Bear in mind also that we will want to capture any URL parameters for POST, PUT and DELETE requests as well as for GET requests.

The parameters that arrive on the URL are relevant regardless of which verb was used; we'll always process these. The script to do so is fairly straightforward, but do look out for parse_str() which writes into a variable you pass in by reference. Once we've got that, we can deal with the body of the request, if there is one. POST and PUT requests can have bodies with them, in which case we need to work out what format that data is in. The example here supports both JSON and a standard form post, and we could add more cases to handle a wider selection of Content-Type headers by adding additional cases. Here's the remainder of Request::__construct() and the method in this class for reading incoming variables:

        $this->parseIncomingParams();
        // initialise json as default format
        $this->format = 'json';
        if(isset($this->parameters['format'])) {
            $this->format = $this->parameters['format'];
        }
        return true;
    }
 
    public function parseIncomingParams() {
        $parameters = array();
 
        // first of all, pull the GET vars
        if (isset($_SERVER['QUERY_STRING'])) {
            parse_str($_SERVER['QUERY_STRING'], $parameters);
        }
 
        // now how about PUT/POST bodies? These override what we got from GET
        $body = file_get_contents("php://input");
        $content_type = false;
        if(isset($_SERVER['CONTENT_TYPE'])) {
            $content_type = $_SERVER['CONTENT_TYPE'];
        }
        switch($content_type) {
            case "application/json":
                $body_params = json_decode($body);
                if($body_params) {
                    foreach($body_params as $param_name => $param_value) {
                        $parameters[$param_name] = $param_value;
                    }
                }
                $this->format = "json";
                break;
            case "application/x-www-form-urlencoded":
                parse_str($body, $postvars);
                foreach($postvars as $field => $value) {
                    $parameters[$field] = $value;
 
                }
                $this->format = "html";
                break;
            default:
                // we could parse other supported formats here
                break;
        }
        $this->parameters = $parameters;
    }

The php://input is the incoming stream to PHP. For a "normal" web application we usually just use $_POST, which has already parsed this stream and decoded the form fields that were sent with the request. For handling JSON data, PUT requests, and anything else that isn't a form POST, we need to parse the stream itself as shown here.

We also set the format property of the Request object - this is the format that we will send the output in. You might have all kinds of logic to work out what that is, but for simplicity, we'll default to JSON.

At this point, we have the data and the request details all understood, and we are in a position to route into the controller and start writing the actual functionality – at last! I'll be writing about the routing, autoloading, and controllers in the next installment.

Edit: You can read the next part here.

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

In a nutshell, you use ON for most things, but USING is a handy shorthand for the situation where the column names are the same.

Consider this example dataset:

mysql> select * from pets;
+---------+---------+--------+-----------+
| pets_id | animal  | name   | owners_id |
+---------+---------+--------+-----------+
|       1 | fox     | Rusty  |         2 |
|       2 | cat     | Fluffy |         2 |
|       3 | cat     | Smudge |         3 |
|       4 | cat     | Toffee |         3 |
|       5 | dog     | Pig    |         3 |
|       6 | hamster | Henry  |         1 |
|       7 | dog     | Honey  |         1 |
+---------+---------+--------+-----------+
7 rows in set (0.00 sec)

mysql> select * from owners;
+-----------+-------+
| owners_id | name  |
+-----------+-------+
|         1 | Susie |
|         2 | Sally |
|         3 | Sarah |
+-----------+-------+
3 rows in set (0.00 sec)

To find out who has which pets, we would join the two tables together like this:

mysql> select owners.name as owner, pets.name as pet, pets.animal
    -> from owners join pets on (pets.owners_id = owners.owners_id);
+-------+--------+---------+
| owner | pet    | animal  |
+-------+--------+---------+
| Sally | Rusty  | fox     |
| Sally | Fluffy | cat     |
| Sarah | Smudge | cat     |
| Sarah | Toffee | cat     |
| Sarah | Pig    | dog     |
| Susie | Henry  | hamster |
| Susie | Honey  | dog     |
+-------+--------+---------+
7 rows in set (0.00 sec)

The example above uses the ON keyword, but since the columns we use to join are called owners_id in both tables, then we can instead put in USING as a shorthand.

mysql> select owners.name as owner, pets.name as pet, pets.animal
    -> from owners join pets using (owners_id);
+-------+--------+---------+
| owner | pet    | animal  |
+-------+--------+---------+
| Sally | Rusty  | fox     |
| Sally | Fluffy | cat     |
| Sarah | Smudge | cat     |
| Sarah | Toffee | cat     |
| Sarah | Pig    | dog     |
| Susie | Henry  | hamster |
| Susie | Honey  | dog     |
+-------+--------+---------+
7 rows in set (0.00 sec)

OK so it's a super-simple tip but until you see the different approaches laid out side-by-side, it can be confusing. This USING trick is why you will often see fields named, for example, "user_id" when they are in the "users" table - then the shorthand can be used any time you join this user_id to any other user_id column.

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

The question is: as a developer, how do you know which of these products (I get about one tempting enquiry a month from what sounds like a real person who isn't building a social network) is a good bet?

For my own products, that's easy. I know what I want to build and while it's tough to be customer, project manager and developer all on my own, I can at least give it a shot. I am self-employed and my products get time scheduled in just like all my other projects do - well, unless there's more interesting paying work to be had, in which case they tend to slide!

But what about those other excellent business people, who understand their market, have a great idea for a product, and are confident they can bring in enough paying clients to make the whole thing balance within a couple of years? They should be able to launch their products too - but of course they need some technical skills on their team to do so.

For me, as a developer, I would love to get involved in some new ventures. I enjoy building things that other people need, and as a freelancer I'm flexible enough to take on some side projects that won't pay me back directly. I've been approached by perfectly sane-sounding local people who already run viable businesses and are looking to offer software products alongside those. They know their market, their domain, and they know what they want. So far, I've got enough work of my own that I haven't been sure enough to take the risk when it came past ... but will I ever know when to jump in and get involved?

What are your thoughts? Have you joined in building something new with people you haven't worked with before? On what kind of basis? Are these kind of projects ever worth picking up? Perhaps more interestingly, have you been burned and if so, what would you say were the warning signs now you have some hindsight?

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

• First: register your domain
• Log in to your registrar's control panel and add an A record*
• That's it! In about 24 hours, you'll be able to shorten with your domain

* or a CNAME if you want to use a subdomain of an existing domain.

Bit.ly has excellent instructions here: lrnja.net/bitlydomain

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane

As with most linux command line utilities, it does only one thing and it does it very well. In this case, it shows the file structure. For my work-in-progress project (which handily only has a few files so has fairly short output), it does this:

$ tree .
.
├── controllers
│   ├── MyController.php
│   └── UsersController.php
├── index.php
├── models
└── views

3 directories, 3 files

The . that was passed here is the name of the directory to generate the tree for; the dot means to use the current directory. You can also pass switches limiting the depth of the listing, showing full paths to each file or directory, and omitting the indentations - as well as a large number of other options that seem less useful!

I use the tree command to put into blog posts, talk slides, and so on - I think it's clear and easy to read (especially because the toolchain I'm using for slides at the moment make most screenshots look decidedly chewed!), and also just to remind myself where all the various pieces of a project can be found.

Lorna is an independent web development consultant, writer and trainer, open source project lead and community evangelist. This post was originally published at LornaJane