Showing posts with label Installing PEAR:SOAP. Show all posts
Showing posts with label Installing PEAR:SOAP. Show all posts

Wednesday, July 18, 2012

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.

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::SOAPs 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 youll find a listing and description of this script.
The SOAP_Client class is PEAR::SOAPs answer to NuSOAPs soapclient, and ezSOAPs eZSOAPClient classes. We need to include the definition of this class before we can proceed:
<?
    /* Include PEAR::SOAP's SOAP_Client class: */
    require_once('SOAP/Client.php');
SOAP_Clients requires one argument: the URL to the SOAP service we wish to connect to. Optionally, you can also pass an second boolean true to the script, which would indicate that the first argument is not an URL to a service, but a path to a WSDL:
    /* Create a new SOAP client using PEAR::SOAP's SOAP_Client-class: */
    $client = new SOAP_Client('http://localhost/soap/pear-soap/pearsoap-hello-server.php');

As usual, we send a single string to the server:
    /* Define the parameters we want to send to the server's helloWorld-function.
       Note that these arguments should be sent as an array: */
    $params = array('inmessage'=>'World');

Next, we make a call to the server, telling it we want to some assistance from its helloWorld method with the data in $params. When the request is carried out, the result gets stored in $response:
    /* Send a request to the server, and store its response in $response: */
$response = $client->call('helloWorld',$params,array('namespace'=> 'urn:helloworld'));

Print the result to the user:
    /* Print the server-response: */
    print $response;
?>

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.

When you�ve made sure you�ve got all the above packages installed, it�s safe to install PEAR::SOAP. As with the other PEAR packages, this can either be done manually by downloading from http://pear.php.net/soap, or by using the pear script:

root@localhost:~# pear install soap

It 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.