Introduction to Web services with PHP

By: Krystal L. L.

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 (!).

Have you ever wanted to enrich your site with
information from Google, Amazon, eBay, or one of the many other sites
that provide web services through SOAP? In this tutorial, I will be
demonstrating how to use the SOAP package from PEAR to query Google's
extensive database. This tutorial assumes that you are using PHP 4 or
higher and PEAR::SOAP 0.8.1, and requires basic familiarity with PHP
(including a little object-oriented programming).