Main Page Content
The Pear Soap Implementation
Installing PEAR:SOAP
The Installation of PEAR:SOAP does not require any additional extensions, as the library will make use of the overload extension if it is loaded. The latest version of PEAR::SOAP at the time of this writing was 0.7. The dependencies for this release are listed below:- pcre - PHP Extension: This extension should be compiled in automatically in your PHP libraries/binary. If that is not the case, you need to enable it by passing --enable-pcre (note that this is standard) to configure.
- HTTP_Request- PEAR Package: Should be installed by default. If it's not, install it manually by downloading it from pear.php.net, and copying the files to your PEAR base directory, or use the pear program: pear install HTTP_Request.
- Mail_Mime- PEAR Package: Install manually or with pear: pear install Mail_Mime.
- Net_Dime- PEAR Package: Install manually, or with pear: pear install Net_Dime.
- Net_Url- PEAR Package: Should be installed by default. If not, install manually, or with pear: pear install Net_Url.
root@localhost:~# pear install soapIt should be said that there have been some problems with the dependency-check in the pear script, and that's not uncommon that the above command fails with a dependency error, although all required packages actually are installed. If that happens, just install the package manually instead, and try to keep in mind that we're dealing with bleeding-edge, experimental software here. Note that pear will be standard in PHP 4.3, and all these issues should be taken care of by that time. 'Hello World' With PEAR::SOAP
After successfully installing PEAR::SOAP, the next step is to write a 'Hello World' using the implementation. To implement a SOAP server using PEAR::SOAP, you need to define a class that describes the server, and then pass an instance of this class over to PEAR::SOAP. PEAR::SOAP's SOAP_Server class will then use the characteristics of this class to set up a new SOAP service.pearsoap-hello-client.php
pearsoap-hello-client.php is our PEAR::SOAP version of the 'Hello World' consumer. Below you'll find a listing and description of this script.The SOAP_Client class is PEAR::SOAP's answer to NuSOAP's soapclient, and ezSOAP's eZSOAPClient classes. We need to include the definition of this class before we can proceed:Pearsoap-hello-server.php
In the PEAR::SOAP version of our simple SOAP service, pearsoap-hello-server.php, you'll see a quite different approach to server implementing that you've got used to walking through the two previous examples. As stated, PEAR::SOAP requires us to define a class that describes the service we want to deploy.The SOAP_Server class will implement the SOAP service described by our class, so that we need to include:<? /* Include PEAR::SOAP's SOAP_Server class: */ require_once('SOAP/Server.php');Here we start the definition of our class, SOAP_Hello_Server: /* To define a new SOAP service with PEAR::SOAP, we need to
construct a class that defines the characteristics for our service. An instance of this class is then used by SOAP_Server to create a new SOAP service: */ class SOAP_Hello_Server {
In the constructor of SOAP_Hello_Server, we define the $dispatch_map variable. This variable is used by PEAR::SOAP to figure out what methods the service should process requests to, and what kind of data is sent in and out of these methods (I.e. what parameters is passed to them, and what kind of data they return). /* $dispatch_map helps SOAP_Server figure out which parameters are used with the methods: */ var $dispatch_map = array(); /* dispatch mapping is optional. It is used in non-wsdl servers to allow for being more explicit with what arguments and types are passed in and out.*/ /* Here's the constructor for out class. It is used to define
$dispath_map: */ function SOAP_Hello_Server() { $this->dispatch_map['helloWorld'] = array( 'in' => array('inmessage'=>'string'), 'out' => array('outmessage'=>'string') ); }
The helloWorld method remains basically the same. The only difference is that we use SOAP_Fault for error /* Of course, we also need to define all the functions that should be requestable through our server: */ function helloWorld($inmessage) { /* Generate a SOAP error if the argument was not valid: */ if($inmessage == '') { /* The SOAP error is generated by the SOAP_Fault class: */ $fault = new SOAP_Fault('You must supply a valid string!','12345'); return $fault->message(); } else { /* If the argument is okay, we submit out return message: */ return "Hello $inmessage!"; } } }Okay, we've done the definition of SOAP_Hello_Server, se it's time to start the service. First thing we need to do is to create an instance of SOAP_Server: /* Create a new SOAP server using PEAR::SOAP's SOAP_Server class: */ $server = new SOAP_Server();
We also need to create an instance of our own class, SOAP_Hello_Server: /* Create an instance of our class: */ $soaphelloserver = new SOAP_Hello_Server();
And then we tell SOAP_Server about our class: /* Register this instance to the server class: */ $server->addObjectMap($soaphelloserver,array('namespace'=> 'urn:helloworld')););Next, SOAP_Server->service() is called to start the service: /* The following line starts the actual service: */ $server->service($HTTP_RAW_POST_DATA);
And, exit to avoid printing characters that could cause problems for our application:Testing The Application
Hopefully, you have now managed to install PEAR::SOAP on your box, and you're ready to test the application. Point your browser to pearsoap-hello-client.php, and you should see "Hello World" on your browser.Note that this article is a distillation from Wrox' forthcoming release - Professional PHP Webservices. The specific chapter (from which this article has been extracted) in the book has coverage on the other two leading SOAP implementations -- NuSOAP and eZSOAP. If you will read and toy around with them, you will notice that all three do exactly the same thing for us, save that each one is based on a different SOAP implementation. Ultimately it is your call as a developer, on which implementation to focus - Maybe the simplicity of NuSOAP appeals to you, or maybe it is the object oriented base of PEAR::SOAP that makes you feel more convenient? Nah! Don't decide just yet! Read the entire chapter from the book instead, and take a look at a couple of other examples that demonstrates the capabilities of PHP SOAP applications a bit further before you make that choice.Click on this link to read a pre-release review of the book.
