Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

Programming with NuSOAP Using WSDL

NuSOAP is a group of PHP classes that allow developers to create and consume SOAP web services. It does not require any special PHP e tensions. !he current release version "#.$.%& of NuSOAP at the time this was written "#'(November()##*&+ supports much of the SOAP ,., specification. It can generate -S./ ,., and also consume it for use in seriali0ation. 1oth rpc2encoded and document2literal services are supported. However+ it must be noted that NuSOAP does not provide coverage of the SOAP ,., and -S./ ,., that is as complete as some other implementations+ such as .N3! and Apache A is. !his document follows up Introduction to NuSOAP+ Programming with NuSOAP+ and Programming with NuSOAP Part ) with additional samples that demonstrate how to use NuSOAP to create and consume SOAP web services using -S./. Hello+ -orld 4edu !he New 5lient .efining New .ata Structures

Hello, World Redux

Showing no imagination whatsoever+ I used the ubiquitous 6Hello+ -orld6 e ample in Introduction to NuSOAP. In that document+ I showed the SOAP request and response e changed by the client and server. Here+ I e tend that sample to use -S./. A -S./ document provides metadata for a service. NuSOAP allows a programmer to specify the -S./ to be generated for the service programmatically using additional fields and methods of the soap7server class. !he service code must do a number of things in order for correct -S./ to be generated. Information about the service is specified by calling the configure-S./ method. Information about each method is specified by supplying additional parameters to the register method. Service code for using -S./ is shown in the following e ample.
<?php // Pull in the NuSOAP code require_once('nusoap.php'); // Create the server instance $server = new soap_server(); // Initialize WSDL support $server->configureWSDL('hellowsdl', 'urn:hellowsdl'); // Register the method to expose $server->register('hello', // method name array('name' => 'xsd:string'), // input parameters array('return' => 'xsd:string'), // output parameters 'urn:hellowsdl', // namespace 'urn:hellowsdl#hello', // soapaction 'rpc', // style 'encoded', // use 'Says hello to the caller' // documentation ); // Define the method as a PHP function function hello($name) { return 'Hello, ' . $name; } // 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); ?>

Now for some magic. Point a -eb browser at this service+ which in my environment is at http822localhost2phphac92hellowsdl.php. !he H!:/ that is returned to your browser gives you lin9s to view the -S./ for the service or view information about each method+ in this case the hello method. !he screen should loo9 something li9e this.

hellowsdl
1 de 7 23/12/2013 13:48

Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

;iew the WSDL for the service. 5lic9 on an operation name to view it<s details.
hello

.isplaying the details for the hello operation loo9s something li9e this.

hellowsdl
Close

;iew the WSDL for the service. 5lic9 on an operation name to view it<s details.
hello

Name: hello Binding: hellowsdlBinding Endpoint: http://localhost/phphack /hellowsdl.php SoapAction: urn:hellowsdl#hello Style: rpc Input: use: encoded namespace: urn:hellowsdl encodingStyle: http://schemas.xmlsoap.org /soap/encoding/ message: helloRequest parts: name: xsd:string Output: use: encoded namespace: urn:hellowsdl encodingStyle: http://schemas.xmlsoap.org /soap/encoding/ message: helloResponse parts: return: xsd:string Namespace: urn:hellowsdl Transport: http://schemas.xmlsoap.org /soap/http Documentation: Says hello to the caller

So+ with =ust a little code added to the service+ NuSOAP provides browsable documentation of the service. 1ut+ that is not all. 1y either clic9ing the -S./ lin9 on the documentation page+ or by pointing the browser at the service with a query string of >wsdl "e.g. http822localhost2phphac92hellowsdl.php>wsdl&+ you get the following -S./.
<?xml version="1.0"?> <definitions xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:tns="urn:hellowsdl" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="urn:hellowsdl"> <types> <xsd:schema targetNamespace="urn:hellowsdl"> <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/" /> <xsd:import namespace="http://schemas.xmlsoap.org/wsdl/" /> </xsd:schema> </types> <message name="helloRequest"> <part name="name" type="xsd:string" /> </message> <message name="helloResponse"> <part name="return" type="xsd:string" /> </message>

2 de 7

23/12/2013 13:48

Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

<portType name="hellowsdlPortType"> <operation name="hello"> <documentation>Says hello to the caller</documentation> <input message="tns:helloRequest"/> <output message="tns:helloResponse"/> </operation> </portType> <binding name="hellowsdlBinding" type="tns:hellowsdlPortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="hello"> <soap:operation soapAction="urn:hellowsdl#hello" style="rpc"/> <input> <soap:body use="encoded" namespace="urn:hellowsdl" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use="encoded" namespace="urn:hellowsdl" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation> </binding> <service name="hellowsdl"> <port name="hellowsdlPort" binding="tns:hellowsdlBinding"> <soap:address location="http://localhost/phphack/hellowsdl.php"/> </port> </service> </definitions>

4eturn to top.

The New Client

Adding a few NuSOAP -S./ calls to the service allows it to generate -S./ and other documentation. 1y comparison+ client support for -S./ is anti(climactic+ at least for this simple e ample. !he simple client shown below is not much different than the non(-S./ client. !he only difference is that the constructor for the soapclient class is provided the ?4/ of the -S./+ rather than the service endpoint.
<?php // Pull in the NuSOAP code require_once('nusoap.php'); // Create the client instance $client = new soapclient('http://localhost/phphack/hellowsdl.php?wsdl', true); // Check for an error $err = $client->getError(); if ($err) { // Display the error echo '<h2>Constructor error</h2><pre>' . $err . '</pre>'; // At this point, you know the call that follows will fail } // Call the SOAP method $result = $client->call('hello', array('name' => 'Scott')); // Check for a fault if ($client->fault) { echo '<h2>Fault</h2><pre>'; print_r($result); echo '</pre>'; } else { // Check for errors $err = $client->getError(); if ($err) { // Display the error echo '<h2>Error</h2><pre>' . $err . '</pre>'; } else { // Display the result echo '<h2>Result</h2><pre>'; print_r($result); echo '</pre>'; } } // Display the request and response echo '<h2>Request</h2>'; echo '<pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>'; echo '<h2>Response</h2>'; echo '<pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>'; // Display the debug messages echo '<h2>Debug</h2>'; echo '<pre>' . htmlspecialchars($client->debug_str, ENT_QUOTES) . '</pre>'; ?>

3 de 7

23/12/2013 13:48

Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

Here are the request and response for this -S./ implementation.
POST /phphack/hellowsdl.php HTTP/1.0 Host: localhost User-Agent: NuSOAP/0.6.8 (1.81) Content-Type: text/xml; charset=ISO-8859-1 SOAPAction: "urn:hellowsdl#hello" Content-Length: 550 <?xml version="1.0" encoding="ISO-8859-1"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:tns="urn:hellowsdl"> <SOAP-ENV:Body> <tns:hello xmlns:tns="urn:hellowsdl"> <name xsi:type="xsd:string">Scott</name> </tns:hello> </SOAP-ENV:Body> </SOAP-ENV:Envelope> HTTP/1.1 200 OK Server: Microsoft-IIS/5.0 Date: Wed, 03 Nov 2004 21:05:34 GMT X-Powered-By: ASP.NET X-Powered-By: PHP/4.3.4 Server: NuSOAP Server v0.6.8 X-SOAP-Server: NuSOAP/0.6.8 (1.81) Content-Type: text/xml; charset=ISO-8859-1 Content-Length: 551 <?xml version="1.0" encoding="ISO-8859-1"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd"> <SOAP-ENV:Body> <ns1:helloResponse xmlns:ns1="urn:hellowsdl"> <return xsi:type="xsd:string">Hello, Scott</return> </helloResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

4eturn to top.

De ining New Data Stru!tures

An important aspect of -S./ is that it can encapsulate one or more @:/ Schema+ allowing programmers to describe the data structures used by a service. !o illustrate how NuSOAP supports this+ I will add -S./ code to the SOAP struct e ample in Programming with NuSOAP Part ). !he service code gains the changes already shown in the Hello+ -orld e ample+ but it also has code to define the Person data structure.
<?php // Pull in the NuSOAP code require_once('nusoap.php'); // Create the server instance $server = new soap_server(); // Initialize WSDL support $server->configureWSDL('hellowsdl2', 'urn:hellowsdl2'); // Register the data structures used by the service $server->wsdl->addComplexType( 'Person', 'complexType', 'struct', 'all', '', array( 'firstname' => array('name' => 'firstname', 'type' => 'xsd:string'), 'age' => array('name' => 'age', 'type' => 'xsd:int'), 'gender' => array('name' => 'gender', 'type' => 'xsd:string')

4 de 7

23/12/2013 13:48

Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

) ); $server->wsdl->addComplexType( 'SweepstakesGreeting', 'complexType', 'struct', 'all', '', array( 'greeting' => array('name' => 'greeting', 'type' => 'xsd:string'), 'winner' => array('name' => 'winner', 'type' => 'xsd:boolean') ) ); // Register the method to expose $server->register('hello', // method name array('person' => 'tns:Person'), // input parameters array('return' => 'tns:SweepstakesGreeting'), // output parameters 'urn:hellowsdl2', // namespace 'urn:hellowsdl2#hello', // soapaction 'rpc', // style 'encoded', // use 'Greet a person entering the sweepstakes' // documentation ); // Define the method as a PHP function function hello($person) { $greeting = 'Hello, ' . $person['firstname'] . '. It is nice to meet a ' . $person['age'] . ' year old ' . $person['gender'] . '.'; $winner = $person['firstname'] == 'Scott'; return array( 'greeting' => $greeting, 'winner' => $winner ); } // 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); ?>

1esides the additional code to support -S./+ the code for the service method itself is changed slightly. -ith -S./+ it is no longer necessary to use the soapval ob=ect to specify the name and data type for the return value. Similarly+ the -S./ client does not need to use a soapval to specify the name and data type of the parameter+ as shown in the following code.
<?php // Pull in the NuSOAP code require_once('nusoap.php'); // Create the client instance $client = new soapclient('http://localhost/phphack/hellowsdl2.php?wsdl', true); // Check for an error $err = $client->getError(); if ($err) { // Display the error echo '<h2>Constructor error</h2><pre>' . $err . '</pre>'; // At this point, you know the call that follows will fail } // Call the SOAP method $person = array('firstname' => 'Willi', 'age' => 22, 'gender' => 'male'); $result = $client->call('hello', array('person' => $person)); // Check for a fault if ($client->fault) { echo '<h2>Fault</h2><pre>'; print_r($result); echo '</pre>'; } else { // Check for errors $err = $client->getError(); if ($err) { // Display the error echo '<h2>Error</h2><pre>' . $err . '</pre>'; } else { // Display the result echo '<h2>Result</h2><pre>'; print_r($result); echo '</pre>'; } }

5 de 7

23/12/2013 13:48

Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

// Display the request and response echo '<h2>Request</h2>'; echo '<pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>'; echo '<h2>Response</h2>'; echo '<pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>'; // Display the debug messages echo '<h2>Debug</h2>'; echo '<pre>' . htmlspecialchars($client->debug_str, ENT_QUOTES) . '</pre>'; ?>

-S./ enables one more capability on the client. Instead of using the call method of the soapclient class+ a pro y can be used. !he pro y is a class that mirrors the service+ in that it has the same methods with the same parameters as the service. Some programmers prefer to use pro ies because the code reads as method calls on ob=ect instances+ rather than invocations through the call method. A client that uses a pro y is shown below.
<?php // Pull in the NuSOAP code require_once('nusoap.php'); // Create the client instance $client = new soapclient('http://localhost/phphack/hellowsdl2.php?wsdl', true); // Check for an error $err = $client->getError(); if ($err) { // Display the error echo '<h2>Constructor error</h2><pre>' . $err . '</pre>'; // At this point, you know the call that follows will fail } // Create the proxy $proxy = $client->getProxy(); // Call the SOAP method $person = array('firstname' => 'Willi', 'age' => 22, 'gender' => 'male'); $result = $proxy->hello($person); // Check for a fault if ($proxy->fault) { echo '<h2>Fault</h2><pre>'; print_r($result); echo '</pre>'; } else { // Check for errors $err = $proxy->getError(); if ($err) { // Display the error echo '<h2>Error</h2><pre>' . $err . '</pre>'; } else { // Display the result echo '<h2>Result</h2><pre>'; print_r($result); echo '</pre>'; } } // Display the request and response echo '<h2>Request</h2>'; echo '<pre>' . htmlspecialchars($proxy->request, ENT_QUOTES) . '</pre>'; echo '<h2>Response</h2>'; echo '<pre>' . htmlspecialchars($proxy->response, ENT_QUOTES) . '</pre>'; // Display the debug messages echo '<h2>Debug</h2>'; echo '<pre>' . htmlspecialchars($proxy->debug_str, ENT_QUOTES) . '</pre>'; ?>

4egardless of whether the 6regular6 or pro y coding style is used+ the request and response messages are the same.
POST /phphack/hellowsdl2.php HTTP/1.0 Host: localhost User-Agent: NuSOAP/0.6.8 (1.81) Content-Type: text/xml; charset=ISO-8859-1 SOAPAction: "urn:hellowsdl2#hello" Content-Length: 676 <?xml version="1.0" encoding="ISO-8859-1"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:tns="urn:hellowsdl2"> <SOAP-ENV:Body>

6 de 7

23/12/2013 13:48

Programming with NuSOAP Using WSDL

http://www.scottnichol.com/nusoapprogwsdl.htm

<tns:hello xmlns:tns="urn:hellowsdl2"> <person xsi:type="tns:Person"> <firstname xsi:type="xsd:string">Willi</firstname> <age xsi:type="xsd:int">22</age> <gender xsi:type="xsd:string">male</gender> </person> </tns:hello> </SOAP-ENV:Body> </SOAP-ENV:Envelope> HTTP/1.1 200 OK Server: Microsoft-IIS/5.0 Date: Wed, 03 Nov 2004 21:20:44 GMT X-Powered-By: ASP.NET X-Powered-By: PHP/4.3.4 Server: NuSOAP Server v0.6.8 X-SOAP-Server: NuSOAP/0.6.8 (1.81) Content-Type: text/xml; charset=ISO-8859-1 Content-Length: 720 <?xml version="1.0" encoding="ISO-8859-1"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:tns="urn:hellowsdl2"> <SOAP-ENV:Body> <ns1:helloResponse xmlns:ns1="urn:hellowsdl2"> <return xsi:type="tns:SweepstakesGreeting"> <greeting xsi:type="xsd:string"> Hello, Willi. It is nice to meet a 22 year old male. </greeting> <winner xsi:type="xsd:boolean">0</winner> </return> </helloResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

4eturn to top. Aou can download the source for these e amples as well. 4eturn to top.

Resour!es
Boin the NuSOAP mailing list to learn more and as9 questions. !he home of the NuSOAP pro=ect. NuSOAP home of .ietrich Ayala+ the author of NuSOAP. 4eturn to top.
5opyright C )##'()##* Scott Nichol. #'(Nov()##*

7 de 7

23/12/2013 13:48