CHAPTER 8 – XML with PHP 5 – PHP’s SOAP Extension

PHP 5 also comes with a SOAP extension ext/soap, which has even more features than PEAR::SOAP, and is written in C instead of PEAR::SOAP, which is written in PHP. With this extension, we're going to implement the same examples as in the "PEAR::SOAP" section to show you the differences between the two packages. You need to enable the SOAP exten- sion with the PHP configure option --enable-soap or just uncomment the cor- rect line in your php.ini file in case you're using a Windows version of PHP. The SOAP extension also supports WSDL (pronounced as "wizdel"), an XML vocabulary used to describe Web Services. With this WSDL file, the extension knows certain aspects such as the endpoint, procedures, and mes- sage types with which you can connect to an end point. Google's Web API SDK package (which you can download at http://www.google.com/apis/down- load.html) includes such a WSDL description file, but we cannot republish this WSDL file here, of course. What we can do is show you an example on how to use it: #!/usr/local/bin/php <?php /* Read the search string from the command line */ if ($argc != 2) { echo "usage: ./google.php searchstringnn"; exit(); } $query = $argv[1];

/* Defining the 'license' key */ $key = 'b/Wq+3hQFHILurTSX6USaub3VeRGsdSg';

/* Defining maximum number of results and starting index */ $maxResults = 3; $start = 0;

/* Setup the other parameters */ $filter = FALSE; $restrict = ''; $safeSearch = FALSE; $lr = ''; $ie = ''; $oe = '';

/* Make the call */ $client = new SoapClient('GoogleSearch.wsdl'); $res = $client->doGoogleSearch( $key, $query, $start, $maxResults, $filter, $restrict, $safeSearch, $lr, $ie, $oe );

/* Display results */ foreach ($res->resultElements as $result) { echo html_entity_decode( strip_tags("{$result->title}n({$result->URL})nn") ); echo wordwrap(html_entity_decode(strip_tags($result ->snippet))); echo "nn----------------------------nn"; } ?> As you compare this script with the one we used for PEAR::SOAP, you see that calling a SOAP method with WSDL is much easier--it's only two lines! SOAP Server Developing a SOAP server and its accompanying WSDL file is not that hard, either; the largest problem is creating the WSDL description file. The WSDL file is not included here, but can be found in the examples archive belonging to this book. Here is the code for the server: <?php class ExampleService {

function hello ($name) { if (strlen($name)) { return "Hi {$name}!"; } else { throw new SoapFault("Server", "No name :(."); } } } It's basically just a normal PHP class, the only difference being the Soap- Fault exception which is the SOAP way of returning errors. We'll see in the cli- ent code how to handle this: $server = new SoapServer("example.wsdl"); $server->setClass("ExampleService"); $server->handle(); ?> This connects the class that is providing the method with help of the WDSL file to the SOAP server. The handle() method takes care of processing the information when a client requests a method call. SOAP Client The client looks like this: <?php $s = new SoapClient('example.wsdl');

try { echo $s->hello('Derick'), "n"; This first call is correct, as we supply a parameter to the function: echo $s->hello(), "n"; This one will throw the SOAP fault exception because the name parame- ter will be empty: } catch (SoapFault $e) { echo $e->faultcode, ' ', $e->faultstring, "n"; } ?> If we don't catch this exception, the script will die with a fatal error. Now, it will show this when executed: Hi Derick! SOAP-ENV:Server No name :(.

SUMMARY XML was designed mainly for use in exchanging information across systems. XML has its own terminology that describes the structure of XML documents. The information is enclosed in tags that identify the information in a struc- tured manner. To receive the actual information from XML documents in order to use it, you must parse the documents. PHP provides two mainstream pars- ers that you can use: SAX (Simple API for XML), which parses each element in the document as it comes to it, and DOM (Document Object Model), which cre- ates a hierarchical tree in memory containing the structure of the entire docu- ment and then parses it all at once. PHP 5 also provides an easier extension for parsing simple XML documents: SimpleXML. PEAR provides packages useful for parsing in specific situations or for specific purposes.

Often, you want to convert the XML document into a document with a different format, such as an HTML document or a text file. The standard method for converting XML is XSLT. XSLT uses stylesheets to convert docu- ments, with specific templates for converting each element in the XML docu- ment. XSLT translation in PHP is provided by the XSLT extension. For applications on different systems to communicate, you need to use a protocol that both systems understand. XML files are ASCII files, which pro- vide a standard format that systems understand. Two standard solutions for application communication are available in PHP: XML-RPC, which allows a client to execute methods on a server, and SOAP, which specifies a format for exchanging data across systems. Both are similar client-server protocols. How- ever, SOAP is a more complex, broader protocol with more potential future applications.