This is part 3 of my article about writing a restful service server. If you haven’t already, you might like to read part 1 (covering the core library and grabbing the information we need from the incoming request) and part 2 (covering the service handler itself) before reading this section. This part covers the Response object that I used to return the data to the user in the correct format.

XML Response Object

Exactly what output you want from your service completely depends on the specification and what you are actually trying to do. I wrote a really simple response wrapper that responds with an outline tag containing a status, and then either the content or some error details. Here’s my response class:

class Response {

    public function output() {
        header('Content-type: text/xml');
        echo '';
        echo "\n";
        echo '';
        echo "\n";

        foreach($this as $prop_key => $prop_value) {
            if(!is_array($prop_value)) {
                echo '<'.$prop_key.'>';
                echo $prop_value;
                echo '';
                echo "\n";
            } else {
                echo '<'.$prop_key.'>';
                echo "\n";
                foreach($prop_value as $array_key => $array_value) {
                    echo '<'.$array_key.'>';
                    echo $array_value;
                    echo '';
                    echo "\n";
                }
                echo '';
                echo "\n";
            }
        }
        echo "\n";
    }
}

This could be more elegant and thorough, but its kind of an outline of what I did. Firstly set the content header, then the main tag. Then it loops through all the properties set against the response object and just writes them out as XML. Its very limited but at least its short enough to read easily! There is also an error response that gets called and returns the error type and message, setting the response status to “error” rather than “ok”.

REST Service in PHP

So there you have the ingredients for a REST server in PHP. I’m sure this isn’t the only way to solve this problem, but this is how I did it and I hope it helps someone. If you’ve got any questions, feel free to comment below – and if you do use this for a project, I’d love to hear from you :)

This is part 2 of my rest service writing article. In part 1 we saw the library which holds the functionality we will be using, and we also handled the incoming request and captured all the data we’ll be using.

The REST Service

This is not really tricky but we’re pulling together lots of ideas at this point. So we have already got the incoming request data, and we’ve intialised an object with that data. We have a reference to the object which contains all the functionality we want. And we need to work out which of the library functions we should call, and then transform that data into a good format to return to the user. Let’s start with the handle() function:

    public function handle() {
        $urlParts = parse_url($this->url);
        // substring from 1 to avoid leading slash
        $this->_pathParts = split('/', substr($urlParts['path'], 1));

        // glue the first part of the path to the upper case request method to make a unique function name, e.g. usersGET
        $method = $this->_pathParts[0] . strtoupper($this->method);

        try {
            // now call the method in this class that wraps the one we actually want
            $this->$method();
            $this->response->output();
            return true;
        } catch (Service_Exception_Abstract $e) {
            $this->response->errorOutput($e);
        } catch (Exception $e) {
            die('An Unexpected Error Has Occurred');
        }
        return false;
    }

The rest of this class contains the functions, such as userGET, which call the real worker functions from the library class we originally created. The functions in this section look something like this, and they throw exceptions if anything goes wrong – you can see these being caught in the handle() method posted above:

    protected function userGET() {
        $this->response->user = $this->library->getUserDetails($this->getVars['user_id']);
        return true;
    }

I also use a magic __call() method to return sensible error messages if a user tries to call something that doesn’t exist (this was particularly helpful in development where not everything was there from the start!).

You can see here I’m using setting properties on the response object, but you could also just XML-ify and echo the output here if you wanted to. By using the response object however I am abstracting the XML transformation stuff and moving it to somewhere else so that it can be tested independently and even replaced as needed.

I’ll write about the response class and how that works in the third installment.

Wrapping an Existing Class

The main functionality of the service was written in a class that had no awareness that it was a service – this is a similar approach to the one I described when I wrote about the PHP Soap Server – start with a normal functioning class and write some unit tests for it. The example I’m using today looks like this (my real version actually connects to the database and stuff but this is a nice mock of passing in a number and getting back an array):

class Library {
    public function getUserDetails($user_id) {
        $details = array(
            "user_id" => $user_id,
            "name" => 'Joe Bloggs',
            "email" => '[email protected]');
        return $details;
    }
}

In the soap article, you can see that wrapping a class takes just a few lines – for REST more code is required, but the idea is completely the same. In actual fact we started out with this as a soap service but then it was switched to rest – I only had to re-write the wrapper stuff and not any of the core functionality. Using the wrapper approach would also allow services to be published in multiple ways with the same underlying codebase.

Incoming Requests – Intialising the Wrapper

First of all I wrote a .htaccess file to direct all requests to the one controller file – so that all the different URLs would be handled in the same way.

As the requests came into here, I grabbed the data I needed and initialised the service class, something like this:

$service = new Rest_Service();
// instantiate the main functional class and pass to service
$library = new Library();
$service->setLibrary($library);
// create a response object and pass to service
$response = new Response();
$service->setResponse($response);

// set up some useful variables
$service->url = $_SERVER['REQUEST_URI'];
$service->method = $_SERVER['REQUEST_METHOD'];
$service->getArgs = $_GET;
$service->postArgs = $_POST;
parse_str(file_get_contents('php://input'), $service->putArgs);
parse_str(file_get_contents('php://input'), $service->deleteArgs);

$service->handle();

The variables are all read here and passed in to help decouple the systems – doing it this way allows us to initialise the Service with different incoming variables and/or a different library which can be really useful when testing, as it allows isolation of individual components. The syntax for getting the put and delete data is an interesting one, I wrote about this already in my post on accessing incoming PUT data from PHP, there are some helpful comments on that post as well.

To be continued … later parts will cover the service itself and the response format used.

PHP doesn’t have a built-in way to do this, and at first I was a little confused as to how I could reach this information. It turns out that this can be read from the incoming stream to PHP, php://input.

file_get_contents("php://input");

The above line provided me with a query string similar to what you might see on the URL with a GET request. key/value pairs separated by question marks. I was rescued from attempting to parse this monster with a regex by someone pointing out to me that parse_str() is intended for this purpose (seriously, I write a lot of PHP, I don’t know how I miss these things but its always fun when I do “discover” them) – it takes a query string and parses out the variables. Look out for a major health warning on str_parse() – by default it will create all the variables all over your local scope!! Pass in the second parameter though and it will put them in there as an associatvive array instead – I’d strongly recommend this approach and I’ve used it here with my $post_vars variable.

parse_str(file_get_contents("php://input"),$post_vars);

This loads the variable $post_vars with the associative array of variables just like you’d expect to see from a GET request.

Simple Example

Its a bit of a contrived example but it shows use of the REQUEST_METHOD setting from the $_SERVER variable to figure out when we need to grab the post vars. Firstly, here’s the script:

if($_SERVER['REQUEST_METHOD'] == 'GET') {
    echo "this is a get request\n";
    echo $_GET['fruit']." is the fruit\n";
    echo "I want ".$_GET['quantity']." of them\n\n";
} elseif($_SERVER['REQUEST_METHOD'] == 'PUT') {
    echo "this is a put request\n";
    parse_str(file_get_contents("php://input"),$post_vars);
    echo $post_vars['fruit']." is the fruit\n";
    echo "I want ".$post_vars['quantity']." of them\n\n";
}

And here’s what happened when I request the same script using two different HTTP verbs. I’m using cURL to show the example simply because I think it shows it best.

Via GET:

curl "http://localhost/rest_fruit.php?quantity=2&fruit=plum"
this is a get request
plum is the fruit
I want 2 of them

Via PUT:

curl -X PUT http://localhost/rest_fruit.php -d fruit=orange -d quantity=4
this is a put request
orange is the fruit
I want 4 of them

Purists will tell me that I shouldn’t be returning data from a PUT request, and they’d be right! But this does show how to access the incoming variables and detect which verb was being used. If you’re going to write a REST service then the correct naming of resources and the correct response to each resource being accessed in various ways is really important, but its a story I’ll save for another day. If you use this, or perhaps you access the variables another way, then do post a comment – there aren’t a lot of resources available on this topic for PHP.