Note that both Google's service and PEAR::SOAP are technically still in beta, so you might encounter the odd bug from time to time. There are other SOAP client libraries available, including the PHP5 SOAP extension and NuSOAP, and while implementation details are different the basic theory is the same as presented here.



Setting up the PEAR SOAP module

Before we can start using SOAP, we had better make sure both PEAR itself and the SOAP module are available. The PEAR package manager is installed by default with PHP 4.3.0 and later, but if you are using an earlier version or it is missing on your system check out the PEAR manual for instructions.

Once you have the package manager installed, you will need to download the SOAP package. On most systems, you can just enter pear install SOAP into a console window. At least, that's the theory. Unless there is a stable release of SOAP available, you will get the message No release with state equal to: 'stable' found for 'SOAP'. Try pear install SOAP-beta to get the most current version of the package at the time of writing, even though it is in beta, or tell PEAR to accept beta versions without complaint by typing pear config-set preferred_state beta.

You may also get one or more messages starting with requires package, followed by Dependencies failed. In this case, try the pear install command again but add the dependencies on the command line. For example, if PEAR complained that the Net_DIME package is missing, try using pear install Net_DIME SOAP instead.

Getting a license key

Once you have installed the SOAP module, the next step is to download the Google Web APIs developers' kit and register to get a license key. This key allows you to make up to 1000 SOAP queries a day free of charge. Visit Google Web APIs (http://www.google.co.uk/apis/) and follow the instructions on the site.

Unzip the developers' kit and put it in a convenient place. It only contains samples for accessing the service with .NET and Java, but most of the documentation applies equally to calling Google from PHP.

Decoding the WSDL file

In the developer's kit main directory you will find a WSDL file called GoogleSearch.wsdl, which you can open in a text editor or XML browser. This file defines exactly what services we can call using SOAP, though the Google documentation is probably easier to read!

However, we can also see what the SOAP module makes of this file. Create a new PHP page and enter the following.


require_once'SOAP/Client.php';

$wsdl=new SOAP_WSDL('GoogleSearch.wsdl');

header('Content-Type:text/plain);

echo$wsdl->generateProxyCode();

?>

Place it somewhere on your server along with GoogleSearch.wsdl and access it through your web browser. Assuming everything is working right, you should get a lot of PHP code output. This code is the result of the SOAP_WSDL client class parsing the WSDL file and converting it into PHP functions. This tells us what functions we can call in a rather more readable form than the WSDL document, and is handy particularly if you are using a poorly documented WSDL service.

So how does the code work? Let's go through it step by step:

1. First, we load the SOAP client file. If this gives an error, it probably means SOAP isn't installed properly and you should read the instructions above or the PEAR manual.

2. We then create an instance of the SOAP_WSDL class, based on the GoogleSearch.wsdl file. This is one of the main classes we are going to use throughout this tutorial: it parses the WSDL file and represents it as PHP.

3. Finally, we output the proxy code as plain text. (As you can see from the output, in SOAP the proxy is a class that represents the WSDL calls available as PHP functions.)

Spell-checking with Google

If you've been using Google for a while (and type as erratically as me), you have probably noticed the "Did you mean..." line that appears if you misspell a word in a search. Thanks to the Google web service, we can add this spelling checker to our PHP applications (though to be honest, it would probably be better to use pspell in an actual application). Enter the following code, with your own license key as the first string.


require_once'SOAP/Client.php';

$key = 'Enter your Google APIs key here');

$wsdl = new SOAP_WSDL('GoogleSearch.wsdl');

$googleProxy = $wsdl->gettProxy();

echo $googleProxy->doSpellingSuggestion($key, 'diktionary');

?>

Simple, isn't it? The first line is trivial and the next two are the same as the previous example. The fourth line creates the proxy object based on the code we looked at earlier, so we can make SOAP requests by calling its methods. Finally, we call doSpellingSuggestion and output the result. Access this page in your web browser, and you should see the word 'dictionary' on its own.

You might see 'Object' instead, in which case SOAP has encountered a problem and returned a SOAP_Fault object. We will look into dealing with these faults sometime in the future, but for now check if you have entered your license key correctly and not managed to exhaust your 1000 query per day limit (!).