This document discusses using the NuSOAP library to create and consume web services in PHP. It describes how to create a SOAP server and client using NuSOAP, register functions for the server, call functions from the client, generate and use WSDL, handle errors, and support complex data types. The NuSOAP library provides an object-oriented interface for working with SOAP in PHP without requiring additional modules.

1. PHP web services with the NuSOAP library
Fulvio Corno, Dario Bonino
e-lite Research Group
Dipartimento di Automatica e Informatica
Politecnico di Torino
Torino - Italy
http://elite.polito.it
v. 2.1, April 2, 2009

2. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
2 / 39
PHP web services with the NuSOAP library

3. Web services in PHP The NuSOAP library License
Goals
Create and use Web Services using the RPC messaging model
Being able to create a Web Service in PHP (server-side)
Being able to call an existing Web Service from PHP code
(client-side)
Hiding, as much as possible, the creation of SOAP messages,
and their decoding
Avoid the difficulty of creating/editing WSDL files
3 / 39
PHP web services with the NuSOAP library

4. Web services in PHP The NuSOAP library License
Potential Solutions
Php comes with a “standard” SOAP library
http://www.php.net/soap
tutorial at http://devzone.zend.com/node/view/id/689
The PEAR library has a SOAP module
http://pear.php.net/package/SOAP
probably the most updated, but not well documented
The NuSOAP library (we will use this)
http://sourceforge.net/projects/nusoap/
4 / 39
PHP web services with the NuSOAP library

5. Web services in PHP The NuSOAP library License
Limitations
All considered libraries are easy to use when the input(s) and
output of the web service are simple types (numbers, strings)
Complex types are difficult to “teach” to the libraries, and they
are not fully supported
For practical reasons, we will try to use only xsd:string types
5 / 39
PHP web services with the NuSOAP library

6. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
6 / 39
PHP web services with the NuSOAP library

7. Web services in PHP The NuSOAP library License
NuSOAP characteristics
Written in PHP (no new modules to install or configure)
Simple object-oriented interface
May work with or without WSDL files
May automatically generate a WSDL file for the service
7 / 39
PHP web services with the NuSOAP library

8. Web services in PHP The NuSOAP library License
Installation
Download from
http://sourceforge.net/projects/nusoap/
Uncompress the file, and copy the lib directory under your
PHP project
In your PHP files (client or server), import the needed classes
require_once(’lib/nusoap.php’);
8 / 39
PHP web services with the NuSOAP library

9. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
9 / 39
PHP web services with the NuSOAP library

10. Web services in PHP The NuSOAP library License
SOAP Server
Minimal SOAP server
require_once(’lib/nusoap.php’) ;
$server = new nusoap_server; // Create server instance
$server->register( ’myFunction’ ) ;
function myFunction($parameters) {
. . .
return $result;
}
// Use the request to (try to) invoke the service
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA)
? $HTTP_RAW_POST_DATA : ’’;
$server->service($HTTP_RAW_POST_DATA);
10 / 39
PHP web services with the NuSOAP library

11. Web services in PHP The NuSOAP library License
SOAP Server
Step 1: create the server
// Create the server instance
$server = new nusoap_server;
$server is the special variable with the SOAP server
functionality
11 / 39
PHP web services with the NuSOAP library

12. Web services in PHP The NuSOAP library License
SOAP Server
Step 2: identify the service function
$server->register( ’myFunction’ ) ;
registers a new function (SOAP “operation”) in the same web
service
12 / 39
PHP web services with the NuSOAP library

13. Web services in PHP The NuSOAP library License
SOAP Server
Step 3: implement the service function
function myFunction($parameters) {
. . .
return $result;
}
function containing the implementation of the web service
receives the SOAP input(s) directly as funtion parameter(s)
its return value is automatically packaged as the SOAP return
value
13 / 39
PHP web services with the NuSOAP library

14. Web services in PHP The NuSOAP library License
SOAP Server
Step 4: execute the web service
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA)
? $HTTP_RAW_POST_DATA : ’’;
$server->service($HTTP_RAW_POST_DATA);
$HTTP_RAW_POST_DATA should contain the XML SOAP
request
$server->service analyzes the XML, calls the function, and
creates the XML response
the actual web service has already been called (http) to get the
current page
14 / 39
PHP web services with the NuSOAP library

15. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
15 / 39
PHP web services with the NuSOAP library

16. Web services in PHP The NuSOAP library License
SOAP Client
Minimal SOAP client
require_once(’lib/nusoap.php’);
// Create the client instance
$client = new nusoap_client(’http://localhost/ws.php’,
false); // false: no WSDL
// Call the SOAP method
$result = $client->call(’myFunction’,
array(’param’ => ’abc’));
print_r($result) ;
16 / 39
PHP web services with the NuSOAP library

17. Web services in PHP The NuSOAP library License
SOAP Client
Step 1: create the client
$client = new nusoap_client(
’http://localhost/ws.php’,
false ); // false: no WSDL
$client is the special variable with the SOAP client
functionality
the first parameter is the URL of the web service endpoint
the second parameter is false: no WSDL is used
17 / 39
PHP web services with the NuSOAP library

18. Web services in PHP The NuSOAP library License
SOAP Client
Step 2: call the web service
$result = $client->call(
’myFunction’,
array(’param’ => ’abc’) );
the first parameter is the name of the called function
the second parameter is an array with the list of SOAP inputs
the array contains a list of parameter name => parameter value
couples
18 / 39
PHP web services with the NuSOAP library

19. Web services in PHP The NuSOAP library License
SOAP Client
Step 3: use the result
print_r($result) ;
the result is available in a PHP variable
usual PHP type conversions apply
19 / 39
PHP web services with the NuSOAP library

20. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
20 / 39
PHP web services with the NuSOAP library

21. Web services in PHP The NuSOAP library License
Using WDSL
the WSDL file should describe the web service, and in particular
the name(s) and type(s) of input and output parameters
in some cases, we already have a WSDL description file
in other cases, we want the server to automatically provide a
WSDL file describing its services
21 / 39
PHP web services with the NuSOAP library

22. Web services in PHP The NuSOAP library License
Server support for WDSL
Support WSDL generation
$server->configureWSDL(’demows’,
’http://example.org/demo’) ;
tell the NuSOAP server that we want to support WSDL
generation
parameters: name of the service, namespace URL
22 / 39
PHP web services with the NuSOAP library

23. Web services in PHP The NuSOAP library License
Server support for WDSL
Declare input/output types
$server->register( ’myFunction’,
array("param"=>"xsd:string"), // inputs
array("result"=>"xsd:string"), // outputs
’http://example.org/demo’ // element namespace
) ;
for each function, declare types of input and output parameters
name => type arrays
type in XSD syntax
23 / 39
PHP web services with the NuSOAP library

24. Web services in PHP The NuSOAP library License
Self-documenting web service
With the above server declarations, the web page
http://localhost/ws.php may be called in 3 ways:
1 with an http POST, by providing an XML body: the normal Web
Service call
2 with an http GET, with a normal browser: shows a
human-readable description of the service
3 with an http GET and a ?wsdl parameter: generates the WSDL
on-the-fly and lets you download it
24 / 39
PHP web services with the NuSOAP library

25. Web services in PHP The NuSOAP library License
Client support for WDSL
Call using WSDL information
$client = new nusoap_client(
’http://localhost/ws.php?wsdl’,
true);
the client asks for the WSDL file (that is generate on-the-fly)
the second parameter set to true specifies that the first one is
the address of the WSDL file (and not of the endpoint)
25 / 39
PHP web services with the NuSOAP library

26. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
26 / 39
PHP web services with the NuSOAP library

27. Web services in PHP The NuSOAP library License
Error Checking - Client
Error types
error can either happen during the client creation or
during the evaluation of call results
fault can happen during the remote service call
Service creation
//build the nu-soap client
$client = new nusoap_client(
’http://localhost/ws.php?wsdl’,true);
//check errors
$err = $client->getError();
if($err)
//write the error and do not perform the call
echo "<strong>Error:</strong>".$err;
27 / 39
PHP web services with the NuSOAP library

28. Web services in PHP The NuSOAP library License
Error Checking - Client
Service call
//do the call
$callResult = $client->call("myFunction",
array("param"=>"abc"));
//check fault
if($client->fault)
{
echo "<strong>Fault:</strong>".
print_r($callResult);
}
28 / 39
PHP web services with the NuSOAP library

29. Web services in PHP The NuSOAP library License
Error Checking - Client
Call results
//check fault
if($client->fault) {
echo "<strong>Fault:</strong>".
print_r($callResult);
} else {
//check error
$err = $client->getError();
if($err)
{
//write the error
echo "<strong>Error:</strong>".$err;
}
else { ... } //result ok
}
29 / 39
PHP web services with the NuSOAP library

30. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
30 / 39
PHP web services with the NuSOAP library

31. Web services in PHP The NuSOAP library License
Complex Types
NuSOAP supports the definition of Complex Types, i.e., of
complex data structures that may be exchanged by web service
calls. Complex Types may be:
Composed of Simple xsd types
Composed of other Complex Types
May include (unbound) sequences or arrays of Complex or
Simple types
Declared as PHP arrays or structs (associative arrays)
31 / 39
PHP web services with the NuSOAP library

32. Web services in PHP The NuSOAP library License
Complex Types: structures
Structure types
$server->wsdl->addComplexType(
’Theater’,
’complexType’,
’struct’,
’sequence’,
’’,
array(
’idTheater’ => array(
’name’ => ’idTheater’, ’type’ => ’xsd:int’),
’Name’ => array(
’name’ => ’Name’, ’type’ => ’xsd:string’),
’Address’ => array(
’name’ => ’Address’, ’type’ => ’xsd:string’)
)
);
32 / 39
PHP web services with the NuSOAP library

33. Web services in PHP The NuSOAP library License
Generated Schema for structures
Automatically generated WSDL
<xsd:complexType name="Theater">
<xsd:sequence>
<xsd:element name="idTheater" type="xsd:int"/>
<xsd:element name="Name" type="xsd:string"/>
<xsd:element name="Address" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
33 / 39
PHP web services with the NuSOAP library

34. Web services in PHP The NuSOAP library License
Complex Types: arrays
Array types
$server->wsdl->addComplexType(
’Theaters’,
’complexType’,
’array’,
’’,
’SOAP-ENC:Array’,
array(),
array(
array(
’ref’=>’SOAP-ENC:arrayType’,
’wsdl:arrayType’=>’tns:Theater[]’)
),
’tns:Theater’
);
34 / 39
PHP web services with the NuSOAP library

35. Web services in PHP The NuSOAP library License
Generated Schema for arrays
Automatically generated WSDL
<xsd:complexType name="Theaters">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:Theater[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
35 / 39
PHP web services with the NuSOAP library

36. Web services in PHP The NuSOAP library License
Using Complex Types
Service registration
$server->register("getTheaters",
array("param"=>"xsd:string"), // inputs
array("result"=>"tns:Theaters"), // outputs
’http://example.org/demo’); // element
36 / 39
PHP web services with the NuSOAP library

37. Web services in PHP The NuSOAP library License
Further information
Software and function documentation:
http://sourceforge.net/projects/nusoap/
Tutorial introduction:
http://www.scottnichol.com/soap.htm (warning: uses
an old version of the library)
Slides: http://www.slideshare.net/sanil/
develop-webservice-in-php and
http://www.slideshare.net/harit/
web-services-in-php-1094228
37 / 39
PHP web services with the NuSOAP library

38. Web services in PHP The NuSOAP library License
Outline
1 Web services in PHP
2 The NuSOAP library
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
3 License
38 / 39
PHP web services with the NuSOAP library

39. Web services in PHP The NuSOAP library License
License
This document is licensed under the Creative Commons
Attribution-Noncommercial-Share Alike 3.0 Unported License.
http://creativecommons.org/licenses/by-nc-sa/3.0/
39 / 39
PHP web services with the NuSOAP library