This document provides an overview of using the NuSOAP library to create PHP web services. It discusses creating SOAP servers and clients with NuSOAP, using WSDL files, handling errors, and supporting complex data types. The NuSOAP library allows creating and consuming web services in PHP in an object-oriented way and can automatically generate WSDL files to describe the services.

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
Web services in PHP
1
The NuSOAP library
2
SOAP Server
SOAP Client
Using WSDL
Error Checking
Complex Types
License
3
PHP web services with the NuSOAP library
2 / 39

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
PHP web services with the NuSOAP library
3 / 39

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/
PHP web services with the NuSOAP library
4 / 39

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
PHP web services with the NuSOAP library
5 / 39

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

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
PHP web services with the NuSOAP library
7 / 39

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’);
PHP web services with the NuSOAP library
8 / 39

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

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);
PHP web services with the NuSOAP library
10 / 39

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
PHP web services with the NuSOAP library
11 / 39

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
PHP web services with the NuSOAP library
12 / 39

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
PHP web services with the NuSOAP library
13 / 39

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
PHP web services with the NuSOAP library
14 / 39

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

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) ;
PHP web services with the NuSOAP library
16 / 39

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
PHP web services with the NuSOAP library
17 / 39

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
PHP web services with the NuSOAP library
18 / 39

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
PHP web services with the NuSOAP library
19 / 39

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

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
PHP web services with the NuSOAP library
21 / 39

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
PHP web services with the NuSOAP library
22 / 39

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

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:
with an http POST, by providing an XML body: the normal Web
1
Service call
with an http GET, with a normal browser: shows a
2
human-readable description of the service
with an http GET and a ?wsdl parameter: generates the WSDL
3
on-the-fly and lets you download it
PHP web services with the NuSOAP library
24 / 39

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)
PHP web services with the NuSOAP library
25 / 39

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

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 quot;<strong>Error:</strong>quot;.$err;
PHP web services with the NuSOAP library
27 / 39

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

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

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

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)
PHP web services with the NuSOAP library
31 / 39

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’)
)
);
PHP web services with the NuSOAP library
32 / 39

33. Web services in PHP The NuSOAP library License
Generated Schema for structures
Automatically generated WSDL
<xsd:complexType name=quot;Theaterquot;>
<xsd:sequence>
<xsd:element name=quot;idTheaterquot; type=quot;xsd:intquot;/>
<xsd:element name=quot;Namequot; type=quot;xsd:stringquot;/>
<xsd:element name=quot;Addressquot; type=quot;xsd:stringquot;/>
</xsd:sequence>
</xsd:complexType>
PHP web services with the NuSOAP library
33 / 39

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’
);
PHP web services with the NuSOAP library
34 / 39

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

36. Web services in PHP The NuSOAP library License
Using Complex Types
Service registration
$server->register(quot;getTheatersquot;,
array(quot;paramquot;=>quot;xsd:stringquot;), // inputs
array(quot;resultquot;=>quot;tns:Theatersquot;), // outputs
’http://example.org/demo’); // element
PHP web services with the NuSOAP library
36 / 39

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
PHP web services with the NuSOAP library
37 / 39

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

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/
PHP web services with the NuSOAP library
39 / 39