LornaJane

Last night I travelled to the northeast of England to speak to a thriving technical community up there called Supermondays. They contacted me some time ago asking if I could get there to speak one Monday, and last night was the night! It was a very civilised gathering, with sandwiches and cups of tea, and using a lecture theatre at the university for space. As a speaker the best thing about this is that its a space designed for addressing people in, unlike most user groups (and indeed conferences!) where two steps away from the lectern sees you standing in the dark, falling off the stage, or getting projected on to. Last night was a different story with lots of space to wander, slides projected well above me on the wall so everyone could see clearly, and relatively good acoustics despite no amplification.

My talk was entitled "PHP and Web Services: Perfect Partners" - the slides are on slideshare if you want to take a look. There was also a talk about android development by Alex Reid, including a live coding demo which went surprisingly well! Judging by the various events that were plugged and discussed on the night, at the main event and in the pub afterwards, this is a diverse and vibrant technical community - so if you are in the northeast, get along to Supermondays!

This is a quick outline on working with JSON from PHP, which is actually pretty simple to do. This post has some examples on how to do it and what the results should look like. JSON stands for JavaScript Object Notation, and is widely used in many languages (not just JavaScript) for serialisation. It is particularly popular for use in web services.

Writing JSON From PHP

Imagine we have a multidimensional array in PHP that looks something like this:

The output of this script looks like this:

This is pretty typical of a JSON output string - you can see the curly brackets to enclose the whole thing, then some square brackets to show the nesting levels within the key/value formats. JSON is an ideal format for many applications because it is easy to understand and debug, its quite concise, and many languages have built-in support just like PHP.

Reading JSON Data From PHP

Once we've serialised the string, we might want to unserialise it again - and the PHP code for that is every bit as simple as the previous example, except that we use the function json_decode() instead of json_encode(). I've set the output of the previous script as the input to this one:

This decodes the string and then dumps it using print_r() - the output of my script looked like this:

stdClass Object
(
[starter] => Array
(
[0] => prawn cocktail
[1] => soup of the day
)

[main course] => Array
(
[0] => roast chicken
[1] => fish 'n' chips
[2] => macaroni cheese
)

[pudding] => Array
(
[0] => cheesecake
[1] => treacle sponge
)

)

Note that the data isn't identical to how it looked when it went in - JSON can't distinguish between arrays and objects, and doesn't retain information about data types. So its perfect for a web service where we just want to convey the information, but may be too loose for other applications.

The examples here were taken from a talk I give about consuming web services - you can see all the slides on slideshare. If you have any additions or alternatives, leave a comment!

If anyone is able to make it to the PHPNW User Group meet in Manchester next Tuesday 2nd February - I'm the speaker there! I'll be giving a talk entitled "Best Practices for Web Service Design", which covers lots of information about web services and how to write one that your users will love! Details of the event are over on upcoming, you can find out more about the talks, the venue and the group as a whole. If you're able to make it then I'll see you there - its a good crowd :)

I've been doing a lot of work with services and working with them in various ways from PHP. There are a few different ways to do this, PHP has a curl extension which is useful, and if you can add PECL extensions then pecl_http is a better bet but there are a couple of different ways of using it. This post shows all these side-by-side.

POSTing from PHP Curl

This is pretty straightforward once you get your head around the way the PHP curl extension works, combining various flags with setopt() calls. In this example I've got a variable $xml which holds the XML I have prepared to send - I'm going to post the contents of that to flickr's test method.

First we initialised the connection, then we set some options using setopt(). These tell PHP that we are making a post request, and that we are sending some data with it, supplying the data. The CURLOPT_RETURNTRANSFER flag tells curl to give us the output as the return value of curl_exec rather than outputting it. Then we make the call and close the connection - the result is in $response.

POSTing from Pecl_Http

Pecl_Http has two interfaces - one procedural and one object-oriented; we'll start by looking at the former. This is even simpler than in curl, here's the same script translated for pecl_http:

This extension has a method to expressly post a request, and it can optionally accept data to go with it, very simple and easy.

POSTing from Pecl_Http: the OO interface

Finally let's see what the OO verison of the extension looks like. Exactly the same call as both the above examples, but using the alternative interface, means our code looks like this:

This example is quite a bit longer than the previous one, and you might think this indicates that this approach is more complicated. In some senses that is true and its probably overkill for our extremely trivial example. However it is worth mentioning that the pecl_http extension is extremely flexible and powerful, and can handle some cases that the curl extension can't. So even if it looks more complicated here, it can still be an excellent choice to implement.

In Conclusion

That was a very fast round-up of three ways you could make an arbitrary web service call from PHP - hopefully these examples are clear and will help anyone just starting to implement something along these lines.

Over the summer months I wrote a series of posts about designing APIs in general, and web services in particular. This included posts on status codes for web services, error feedback for web services, auth mechanisms for web services, saving state in web services and using version parameters with web services. I thought my series was finished but I thought of something that should have been included - perhaps the series will keep growing as I learn more?

I've worked with a couple of services recently that have a rather excellent feature - a method which calls the service but doesn't do anything useful but simply lets you know the service is alive and well and residing at the location you thought it was. These "heartbeat" methods just allow consumers to check for signs of life, verifying that the service exists.

The heartbeat shouldn't require any particular parameters or any authentication, since formatting data and passing credentials can be a stumbling block for those integrating with a service for the first time or those debugging issues. The heartbeat method can return some known data, perhaps an "I'm here" message, and maybe some version information. Flickr has a nice method flickr.test.echo which will also echo back any parameters that were sent to it - which could be useful for debugging values which don't arrive at the server as you expected.

Another use for a heartbeat method is to allow monitoring systems to call a simple method, needing no credentials, and always get the same response back. Its not uncommon for these monitoring systems to be pointed at a particular page, and for failures to be indicated if the contents of that page changes (because data in the system changes, for example).

So - build a heartbeat service, you might never use it but when you need it, you'll be glad you did!

When I wrote recently about testing web services within Zend Framework, I missed out a really key piece of information! I didn't explain how I was reading the PUT vars in my controller code in the first place - so I'll rectify that omission now.

Its very simple: I have extended Zend_Controller_Action with my own, and all controllers inherit from here. This has a routeAction() which grabs the incoming variables from a PUT request and sets them as parameters within the usual $this->getRequest() scope, then forwards on the request. Here is my class:

So in my controller code, I simply call out to $this->getRequest()->getParam('name') or whatever, and in my tests I can set those parameters as I showed in my other article.

I hope this makes sense, its one of those things I set up once and use a lot (and now I'll be able to refer to how I did it!), if you have any queries, comments, improvements or if this helps you then please leave a comment - I haven't come across anyone else doing anything similar but I know there must be, so let me know!