PHP CookBook

Recipe 12.10 Receiving SOAP Requests

12.10.1 Problem

You want to create an SOAP server and respond to SOAP requests. If your server responds to SOAP requests, anyone on the Internet that has a SOAP client can make requests of your server.

12.10.2 Solution

Use PEAR's SOAP_Server class. Here's a server that returns the current date and time:

require 'SOAP/Server.php';

class pc_SOAP_return_time {
    var $method_namespace = 'urn:pc_SOAP_return_time';

    function return_time( ) {
        return date('Ymd\THis');
    }
}

$rt = new pc_SOAP_return_time( );

$server = new SOAP_Server;
$server->addObjectMap($rt);
$server->service($HTTP_RAW_POST_DATA);

12.10.3 Discussion

There are three steps to creating a SOAP server with PEAR's SOAP_Server class:

The PEAR SOAP_Server class uses objects to handle SOAP requests. A request-handling class needs a $method_namespace property that specifies the SOAP namespace for the class. In this case, it's urn:pc_SOAP_return_time. Object methods then map to SOAP procedure names within the namespace. The actual PHP class name isn't exposed via SOAP, so the fact that both the name of the class and its $method_namespace are identical is a matter of convenience, not of necessity:

class pc_SOAP_return_time {
    var $method_namespace = 'urn:pc_SOAP_return_time';

    function return_time( ) {
        return date('Ymd\THis');
    }
}

$rt = new pc_SOAP_return_time( );

Once the class is defined, you create an instance of the class to link methods with the SOAP server object. Before mapping the procedures to the class methods, however, you first must instantiate a SOAP_Server object:

$server = new SOAP_Server;
$server->addObjectMap($rt);
$server->service($GLOBALS['HTTP_RAW_POST_DATA']);

Once that's done, call SOAP_Server::addObjectMap( ) with the object to tell the SOAP server about the methods the object provides. Now the server is ready to reply to all SOAP requests within the namespace for which you've defined methods.

To tell the server to respond to the request, call SOAP_Server::service( ) and pass the SOAP envelope. Because the envelope arrives via POST, you pass $GLOBALS['HTTP_RAW_POST_DATA']. This provides the server with the complete request, because the class takes care of the necessary parsing.

To call this procedure using a PEAR SOAP client, use this code:

require 'SOAP/Client.php';
$soapclient = new SOAP_Client('http://clock.example.com/time-soap.php');
$result = $soapclient->call('return_time', array( ),
                             array('namespace' => 'urn:pc_SOAP_return_time'));
print "The local time is $result.\n";

This prints:

The local time is 20020821T132615.

To extend the method to read in parameters, you need to alter the method prototype to include parameter names and then modify the client request to include data for the additional arguments. This example modifies the SOAP procedure to accept an optional time zone argument:

class pc_SOAP_return_time {
    var $method_namespace = 'urn:pc_SOAP_return_time';

    function return_time($tz='') {
        if ($tz) { putenv("TZ=$tz"); }
        $date = date('Ymd\THis');
        if ($tz) { putenv('TZ=EST5EDT'); } // change EST5EDT to your server's zone 
        return $date
    }
}

The second parameter in the client's call now takes a tz option:

$result = $soapclient->call('return_time', array('tz' => 'PST8PDT'),
                             array('namespace' => 'urn:pc_SOAP_return_time'));

With the new settings, the server returns a time three hours behind the previous one:

20020821T202615

12.10.4 See Also

Recipe 12.9 for more on SOAP clients; PEAR's SOAP classes at http://pear.php.net/package-info.php?package=SOAP; Programming Web Services with SOAP (O'Reilly); the original SOAP current time application at http://www.soapware.org/currentTime.