A PHP Web Services Client by Adam Trachtenberg, coauthor of PHP Cookbook 07/03/2003

Web services allow you to exchange information over HTTP using XML. When you want to find out the weather forecast for New York City, the current stock price of IBM, or the best-selling DVD according to Amazon.com, you can write a short script to gather that data in a format you can easily manipulate. From a developer's perspective, it's as if you're calling a local function that returns a value.

A major advantage of web services is ubiquity across platforms and languages. A PHP script running on Linux can talk to an IIS server on a Windows box using ASP without any communication problems. When the server switches over to Solaris, Apache, and JSP, everything transitions without a glitch.

SOAP is the most popular web services format. It's a W3C standard for passing messages across the network and calling functions on remote computers. This article shows how to create a SOAP client in PHP. The examples below demonstrate how to query Amazon's SOAP server to pull data from their site onto yours. From there, you can include a listing of newly released books on PHP on your web site, gather information about your CD collection, or even make a customized wedding registry site. The options are only limited by your imagination and Amazon's lawyers.

For a more detailed introduction to web services, see Venu Vasudevan's Web Services Primer on XML.com. XML.com also has an article where Don Box deconstructs SOAP, called Inside SOAP.

PHP does not come with a bundled SOAP extension. Before you can begin, you need to download and install files that let you easily integrate SOAP into your applications. There are three major SOAP implementations for PHP: PEAR::SOAP, NuSOAP, and PHP-SOAP. The first two have more features, but they're written in 100% PHP, so they're slowish. (Not slow, mind you, just slowish. They're perfectly fine for medium-traffic sites.) PHP-SOAP, however, is written in C, so it's much faster. That said, in this case, I prefer comprehensiveness and correctness over speed; therefore, I use PEAR::SOAP because it's simple to install and works for me.

If pear, the PEAR package manager, is installed on your machine, run the following command in your shell:

% pear install SOAP

This will download, unzip, and install PEAR::SOAP. Depending on which packages you've yet to install, you may get an dependency error. That means SOAP relies upon another package, like Net_URL, to handle some aspect of its business, but you don't have this package on your machine. If this happens, you'll see a message similar to this:

downloading SOAP-0.7.3.tgz ...
...done: 73,630 bytes
requires package `Net_URL'
SOAP: dependencies failed

Solving the problem is easy. Just enter:

% pear install Net_URL SOAP

Now, pear will first install Net_URL and then SOAP. If a different package name is printed, substitute that name for Net_URL. If pear echoes multiple dependencies, place all of the package names on the command line before SOAP. (Depending upon your configuration, you may need to be the superuser to install PEAR packages.) See PHP's PEAR on Mac OS X or Chapter 21 of PHP Cookbook for additional information on PEAR.

Next, you need to head over to Amazon's web services site to download their developer's kit and apply for a developer's token. The application requires you to agree to a set of legal restrictions, such as not bombarding Amazon's servers with requests or using their data to construct a store that lets you buy things from Barnes and Noble.

Amazon's developer archive contains a series of folders containing example code and applications in a several languages, including PHP, Java, Visual Basic, and even XSL. Right now, you're not going to use any of the files, but they'll come in handy in the future. As Amazon offers many different ways of searching and sends back lots of information, the complete API documentation is a much-needed reference.

Whew! Now that you've completed the set up, you can move on to the fun stuff. As I said in the introduction, with SOAP you can make requests of Amazon.com's database just as if you're calling a local function. You just need to know what function to call and what parameters to pass it. For example, to find all the books published by O'Reilly, you make a ManufacturerSearchRequest(). A KeywordSearchRequest(), on the other hand, is used to find everything written about PHP. (Searches aren't restricted to books, you can search for anything sold on Amazon: music, DVDs, electronics, software, and even kitchen supplies.) A full list is included in the documentation.

In PHP using PEAR::SOAP, here's the code to find all of O'Reilly's books sorted from best-selling to worst-selling:

require_once 'SOAP/Client.php';

$wsdl_url = 
  'http://soap.amazon.com/schemas3/AmazonWebServices.wsdl';
$WSDL     = new SOAP_WSDL($wsdl_url); 
$client   = $WSDL->getProxy(); 

$params   = array(
    'manufacturer' => "O'Reilly",
    'mode'         => 'books',
    'sort'         => '+title',
    'page'         => 1,
    'type'         => 'lite',
    'tag'          => 'trachtenberg-20',
    'devtag'       => 'XXXXXXXXXXXXXX',
);

$books    = $client->ManufacturerSearchRequest($params);

The first line loads in PEAR::SOAP's client classes. This let you make SOAP requests to other servers. If you have trouble loading the files, make sure your include_path contains the folder where PEAR files are stored.

Then, you use WSDL (Web Services Definition Language) to create an object whose methods are the different functions Amazon understands. WSDL is a particularly cool part of web services. Not only does it let you manipulate an object as you would a PHP class, it even knows what parameters each method takes and each parameter's type. Since unlike PHP, SOAP is a strictly typed language; this allows PEAR::SOAP to coerce variables into the appropriate types Amazon expects to receive, without any action on your part.

You first instantiate a new SOAP_WSDL object by passing $wsdl_url, the location of Amazon's WSDL file, to the constructor. Next, SOAP_WSDL::getProxy() is called, and it returns a client object, $client. This is what you use to make SOAP requests.

Now that the object is up and running, there's still the matter of making the actual ManufacturerSearchRequest() query. This method takes a few arguments, which are passed in as an (associative) array. Parameter names are the array's keys, and their values are the, well, array values.