Creating Web Services with PHP and SOAP, Part 2

Tweet
This entry is part 2 of 2 in the series Creating Web Services with PHP and SOAP

Creating Web Services with PHP and SOAP

In the first part of this series, I showed you how developing applications with the SOAP protocol is a great way to build interoperable software. I also demonstrated how easy it is to build your very own SOAP server and client using the NuSOAP library. This time around I’d like to introduce you to something that you will most definitely run into when working with SOAP – WSDL files.

In this article we’ll talk about what WSDL files are and how to use them. I’ll show you how to quickly build your WSDL files with NuSOAP and incorporate a WSDL file into the SOAP server and client examples from the first part.

What are WSDL Files?

Web Services Description Language (WSDL) files are XML documents that provide metadata for a SOAP service. They contain information about the functions or methods the application makes available and what arguments to use. By making WSDL files available to the consumers of your service, it gives them the definitions they need to send valid requests precisely how you intend them to be. You can think of WSDL files as a complete contract for the application’s communication. If you truly want to make it easy for others to consume your service you will want to incorporate WSDL into your SOAP programming.

WSDL Structure

Just like SOAP messages, WSDL files have a specific schema to adhere to, and specific elements that must be in place to be valid. Let’s look at the major elements that make up a valid WSDL file and explain their uses.

<definitions>
 <types>
  ........
 </types>
 <message>
  <part></part>
 </message>
 <portType>
  .......
 </portType>
 <binding>
  ....
 </binding>
 <service>
  ....
 </service>
</definitions>

The root element of the WSDL file is the definitions element. This makes sense, as a WSDL file is by definition a definition of the web service. The types element describes the type of data used, which in the case of WSDL, XML schema is used. Within the messages element, is the definition of the data elements for the service. Each messages element can contain one or more part elements. The portType element defines the operations that can be performed with your web service and the request response messages that are used. Within the binding element, contains the protocol and data format specification for a particular portType. Finally, we have the service element which defines a collection of service element contains the URI (location) of the service.

The terminology has changed slightly in naming some of the elements in the WSDL 2.0 specification. portType, for example, has changed its name to Interface. Since support for WSDL 2.0 is weak, I’ve chosen to go over version 1.1 which is more widely used.

Building a WSDL File

WSDL files can be cumbersome to write by hand as they must contain specific tags and are usually quite long. The nice thing about using NuSOAP is that it can create a WSDL file for you! Let’s modify the SOAP server we made in the first article to accommodate this.

Open productlist.php and change it to reflect the code below:

<?php
require_once "nusoap.php";

function getProd($category) {
    if ($category == "books") {
        return join(",", array(
            "The WordPress Anthology",
            "PHP Master: Write Cutting Edge Code",
            "Build Your Own Website the Right Way"));
    }
    else {
        return "No products listed under that category";
    }
}

$server = new soap_server();
$server->configureWSDL("productlist", "urn:productlist");

$server->register("getProd",
    array("category" => "xsd:string"),
    array("return" => "xsd:string"),
    "urn:productlist",
    "urn:productlist#getProd",
    "rpc",
    "encoded",
    "Get a listing of products by category");

$server->service($HTTP_RAW_POST_DATA);

Basically this is the same code as before but with only a couple of changes. The first change adds a call to configureWSDL(); the method acts as a flag to tell the server to generate a WSDL file for our service. The first argument is the name of the service and the second is the namespace for our service. A discussion of namespaces is really outside the scope of this article, but be aware that although we are not taking advantage of them here, platforms like Apache Axis and .NET do. It’s best to include them to be fully interoperable.

The second change adds additional arguments to the register() method. Breaking it down:

  • getProd is the function name
  • array("category" => "xsd:string") defines the input argument to getProd and its data type
  • array("return" => "xsd:string") defines the function’s return value and its data type
  • urn:productlist defines the namespace
  • urn:productlist#getProd defines the SOAP action
  • rpc defines the type of call (this could be either rpc or document)
  • encoded defines the value for the use attribute (encoded or literal could be used)
  • The last parameter is a documentation string that describes what the getProd function does

Now point your browser to http://yourwebroot/productlist.php?wsdl and you’ll see the brand new WSDL file created for you. Go ahead and copy that source and save it as it’s own file called products.wsdl and place it in you web directory.

Consuming WSDL Files with the Client

We’ve modified the SOAP server to generate a WSDL file, so now lets modify the SOAP client to consume it. Open up productlistclient.php created in the previous article and simply change the line that initiates the client from this:

$client = new nusoap_client("http://localhost/nusoap/productlist.php");

to this:

$client = new nusoap_client("products.wsdl", true);

The second parameter in the nusoap_client() constructor call tells NuSOAP to build a SOAP client to accept the WSDL file. Now launch productlistclient.php in your browser and you should see the same result as before, but now you’re using WSDL power!

Summary

In part 2 of this series on creating web services with PHP and SOAP, we went over the importance of using WSDL files for optimum interoperability. We talked about the different elements that make up a WSDL file and their definitions, and then I showed you how to quickly and easily create your own WSDL files with the NuSOAP library. Finally, we modified our SOAP server and client to demonstrate how to use WSDL in your applications.

As you can probably guess, I’ve just barely scraped the surface of what SOAP can do for you, but with these new tools you can provide an easy and well-accepted way of exposing web services to your users.

Comments on this article are closed. Have a question about PHP? Why not ask it on our forums?

Image via Lilyana Vynogradova / Shutterstock

Creating Web Services with PHP and SOAP

<< Creating Web Services with PHP and SOAP, Part 1

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • JACK

    Hi, thanks for the tutorial. This helping me so much.
    I have several question.
    May you give an quite advance tutorial using NuSOAP?
    such as, creating calculator system web service, or system expert in web service using NuSOAP.

    Thanks a bunch

  • sarmenhb

    getting an error Undefined variable: HTTP_RAW_POST_DATA
    how do i fix this?

  • sarmenhb

    instead of using $HTTP_RAW_POST_DATA use
    $post = file_get_contents(‘php://input’);
    because it requires you to enable something in php.ini and i had problems with it myself.

    • sarmenhb

      btw, thanks steph for these soap tuts you have made my life much easier. would you know a page where i can study soap using the regular php functions? is it basically the same or much difficult.
      thanks!

    • Aldrean

      Actual fix is to replace the line with
      $server->service(‘php://input’);

  • sarmenhb

    ps: im getting this error , wsdl error: : (:) is not a supported type. whats that mean?

  • Amit Patel

    Hello good one. But i want to create a wsdl using native soap not nusoap can you please write same example using native soap (for above php 5).i tried some example on but it is not working

    please be needfull

  • Raju

    Very Niceeeeeeeeeeeeeeeeeeee….

  • http://www.perfect-soft.ir Alireza Rahmani Khalili

    thank you so much for this great article it help me so much

  • Simple Dimple

    Works like a charm, tons of thanks your way.

  • Hossein Amerkashi

    This is great. Can you tell me how to handle sending in multiple parameters; e.g. category and subcategory?

    Thanks

  • http://www.madhavvyas.blogspot.com/ Madhav Vyas

    One of the best tutorial to understand NUSOAP. I have referred many tutorials but you have provide very detailed and easy to understand.
    Thank you very much for this tutorial.

  • Karthiha

    Very useful one. Thanks

  • Vid

    I am getting
    Error
    wsdl error: Bad path to WSDL file products.wsdl
    please help me out …

    • Ricardo

      I have the same problem.. how did you fix it?

  • Adolfo

    Hi Stephen, this post is great.
    I have a question for you, How do you send a file to a Web service made in PHP with nuSOAP and read every line into a array?

  • fatemeh

    thanks for your tutorial.but by wsdl i get no result.(result=””)
    what’s problem?

  • wanneng

    I have got this error, wenn I open productlistclient.php.
    no operations defined in the WSDL document!
    The products.wsdl like this
    =====================

    Get a listing of products by category

    ================

  • Kuldeep Singh

    This is very good tutorial for learn basics of SOAP and WSDL,

  • Ahmed

    can i use get instead of post? how can i achieve that? i mean something like
    localhost/nuSaop/products.wsdl/category/books

  • http://in.com ashu

    Very Good to learn…

  • praneeth

    i am getting this error…please help
    HTTP Error: Unsupported HTTP response status 404 Not Found (soapclient->response has contents of the response)

  • Ash

    Hi,
    Nice tutorial. I tried it on wamp server it works well.

  • Varun Sureka

    Hello Stephen,
    Everything is fine Infact it’s a very good tutorial but i am getting an Error message no operations defined in the WSDL document! But operation tag is created by the nusoap. Please guide me what i have to do next to solve this issue.