Using PHP to Create Web Services

I l @ ve RuBoard

Now that we have looked at what a web service is and what comprises it, let's now look at how you can create a web service in PHP.

Creating the Web Service

To create your web service, you will use the Microsoft SOAP SDK (http://msdn.microsoft.com/ webservices /). It gives you all you need to create web services and web service clients (connecting to and querying web services). The client portion of the SDK is included in the Windows XP operating system. The SDK is continually updated by Microsoft as the various protocols (such as SOAP and WSDL) change. The SDK used in this chapter is the Microsoft SOAP SDK 2.0 SP2 (see Figure 9.4).

Figure 9.4. The Microsoft SOAP SDK installer dialog box.

Other SOAP SDKs are also available, such as the IBM web service SDK, which includes web service libraries and a WSDL file generator (http://www-106.ibm.com/developerworks/webservices/). Both IBM and Microsoft provide SDKs for UDDI that are separate from their SOAP/WSDL SDKs.

Creating a Web Service Component

The base of your web service (the one that provides the public functions or methods that you want to query against) is the simple COM component you developed in Chapter 7, "PHP, COM, and .NET." You developed this in Visual Basic using the following code:

 Option Explicit  Public Function HelloFunc(ByRef uname As Variant) As Variant        HelloFunc = "hello " & uname  End Function 

All this COM component does is take a string as its argument (such as "everyone" ) and return a string (such as "hello everyone" ). You can either compile a new version of this COM component for use with your web service or simply reuse the same COM component exactly as you left it in Chapter 7.

Creating a WSDL File

As soon as you have your COM component, you need to make a WSDL file to turn it into a web service. Although you can write this by hand, as you have seen, this is quite complicated. Luckily, the Microsoft SOAP SDK provides you with a handy WSDL generation tool called wsdlgen.exe. (You can access it by selecting Start, SOAP SDK.) When you start the WSDL generation tool, you see a welcome screen, as shown in Figure 9.5.

Figure 9.5. The Microsoft WSDL Wizard welcome dialog box.

If you click Next, you can select which COM component you want to create the WSDL file for (its physical file location), as shown in Figure 9.6. Also select a name for your WSDL. You can use any name , but it is best to choose something short and easy to use.

Figure 9.6. The Microsoft WSDL Wizard COM object selection dialog box.

When you click Next, the tool checks what public functions and methods your COM component has available and allows you to select which ones you want to expose in the WSDL file, as shown in Figure 9.7. You might not want to expose them all, but you can do so if you want to.

Figure 9.7. The Microsoft WSDL Wizard function selection dialog box.

When you click Next, you reach the SOAP listener information dialog box, shown in Figure 9.8. This is quite an important section, because this is where you map the WSDL file to your COM component. This tool lets you create either an ASP listener or an ISAPI listener (also called a gateway). The listener can be stored in either the same place as your COM component or elsewhere. Make sure, however, that the directory you choose is accessible by the web server.

Figure 9.8. The Microsoft WSDL Wizard listener setup dialog box.

After you click Next, you select where you want to store the tool you will create (see Figure 9.9). The WSDL file can be separate from the COM component if you want.

Figure 9.9. The Microsoft WSDL Wizard file storage dialog box.

Click Next. The WSDL file is created (see Figure 9.10).

Figure 9.10. The Microsoft WSDL Wizard completion dialog box.

Client Application

To make use of the services your web service provides, you must access the WSDL file. Your client application does just this. You can use two methods in PHP to create the client application. You can use the COM objects that the Microsoft SOAP SDK provides, or you can use a native PHP implementation.

Using the Microsoft SOAP SDK COM Objects

When using the COM objects in the SDK, you can approach creating the client application using two methods. You can use the COM objects directly from PHP, or you can wrap them into a single COM object.

Using COM Objects Directly from PHP

The SOAP SDK provides you with a set of COM objects for querying a web service, as follows :

 <?php  //load COM SOAP client object  $soapob = new COM("MSSOAP.SoapClient");  //connect to web service  $soapob->mssoapinit("http://localhost/phpbook/Chapter9_SOAP/SOAP/Server/  PHP4WINSOAP.WSDL");  //obtain result from web service method  $soapmessage = $soapob->HelloFunc("Andrew");  //print result  print($soapmessage);  ?> 

First, you load the SOAP client COM object into memory:

 $soapob = new COM("MSSOAP.SoapClient"); 

Next you connect to your web service. (Remember to use the full URL of where you stored the WSDL file you created earlier in this chapter.)

 $soapob->mssoapinit("http://localhost/phpbook/Chapter9_SOAP/SOAP/Server/  PHP4WINSOAP.WSDL"); 

Next you call the HelloFunc method of your web service, passing the string "Andrew" and storing its return result:

 $soapmessage = $soapob->HelloFunc("Andrew"); 

Finally, you display the result:

 print($soapmessage); 

If you run the PHP script, you should see the result from the HelloFunc method of your web service, as shown in Figure 9.11.

Figure 9.11. Your web service displaying data.

If you change the call to the web service method, the output changes. For example, if you change the following line in your script:

 $soapmessage = $soapob->HelloFunc("Elle and Jack"); 

the output changes, as shown in Figure 9.12.

Figure 9.12. Your web service displaying different data.

Your Web Service Wrapped into a Single COM Object

You might want to reuse the same SOAP client application code across different scripts. In such a case, you can wrap the client application into a COM object.

If you start Visual Basic and create an ActiveX DLL called php4winsoap with a class called Output , you can add the following code:

 Public Function getdata()  Set sc = New SoapClient  On Error Resume Next  sc.mssoapinit "http://localhost/phpbook/Chapter9_SOAP/SOAP/Server/PHP4WINSOAP.WSDL"  If Err <> 0 Then    getdata = "initialization failed " + Err.Description  End If  getdata = sc.HelloFunc("Andrew")  End Function 

If you try to compile this code, you will get an error. You must also reference the SOAP COM objects in your visual basic project, as shown in Figure 9.13.

Figure 9.13. The Microsoft SOAP SDK COM library reference in Visual Basic.

As soon as the COM object is compiled, you can use it from within PHP:

 <?php  //load SOAP client COM object  $soapob = new COM("php4winsoap.output");  //call getdata method to obtain result of SOAP exchange  $soapmessage = $soapob->getdata();  //output result  print($soapmessage);  ?> 

If you run this script, the web service output is displayed, as in the previous example (see Figure 9.14).

Figure 9.14. Running your web service using a wrapped COM object.

Native PHP Implementation

PHP also lets you not use COM objects at all and connect and query WSDL files directly from PHP. This is made possible by the Simple Web Services API (SWSAPI). It is an open -source API whose creation has been led by the ActiveState Corporation in order to establish the same standard syntax for connecting and querying WSDL files in several different languages. SWSAPI currently is in beta and is available for Perl, Python, and PHP. It is expected to be made available for Ruby.

Using a native implementation means that you use your PHP libraries. In this case, the SWSAPI is a PHP library that builds on a native PHP implementation for SOAP called SOAP4X. To make use of the SWSAPI, you must unzip the PHP files into a directory you can access. You then make use of the SWSAPI via the following code:

 <?php  require_once('webservice.php');  $soapob = WebService::ServiceProxy('http://localhost/phpbook/Chapter9_SOAP/SOAP/Server/  PHP4WINSOAP.WSDL');  $soapmessage = $soapob->HelloFunc("Andrew");  print($soapmessage);  ?> 

Here you load up the SWSAPI functions from the SWSAPI PHP library:

 require_once('webservice.php'); 

What remains is very much like what you have seen using the Microsoft SOAP SDK COM objects. First, you call the WSDL file and store it in a variable:

 $soapob = WebService::ServiceProxy('http://localhost/phpbook/Chapter9_SOAP/SOAP/Server/  PHP4WINSOAP.WSDL'); 

You then call a function of the web service and store the result in a variable:

 $soapmessage = $soapob->HelloFunc("Andrew"); 

Finally, you display the result:

 print($soapmessage); 

If you run the script, you can see the result of calling your web service using the SWSAPI, as shown in Figure 9.15.

Figure 9.15. Running your web service using the SWSAPI.

Further information, downloads, and the SWSAPI specification can be found at http://aspn.activestate.com/ASPN/WebServices/SWSAPI/.

Useful Tools

One of the most useful tools that the toolkit provides is the Trace utility (MsSoapT.exe). You access it by selecting Start, SOAP SDK. Trace lets you view SOAP message exchanges between client applications and the web service at either the web service or the client application side.

If you monitor the web service side, you must modify the service name portion of the WSDL file as follows:

 <soap:address location='http://localhost:8080/phpbook/Chapter9_SOAP/SOAP/Server/  PHP4WINSOAP.ASP' /> 

Here you add a port number (8080) to the web service gateway's URL. If you start the Trace utility and select formatted trace, you are asked for the local port to listen on, as shown in Figure 9.16. In this case, because you are using port 8080, specify port 8080.

Figure 9.16. The Trace Setup dialog box.

If you click OK to start the trace, you see the Trace window, shown in Figure 9.17.

Figure 9.17. The SOAP Trace window.

If you run the web service client PHP script again, the Trace window stores the result of the SOAP message exchange. This exchange is stored under the IP that the web service was delivered from (in this case, the local host address of 127.0.0.1). The top pane of the Trace window contains the SOAP message that calls the web service's public function or method. The bottom pane contains the resulting SOAP message that the public function or method returns (see Figure 9.18). Note that if you change the WSDL file to support listening with the Trace utility and the Trace utility is not running, your web service reports an error.

Figure 9.18. The SOAP Trace window displaying SOAP messages.

The Trace utility is very useful in helping you see what SOAP messages are exchanged between the web service and client applications. It therefore helps you debug any problems in your web services.

I l @ ve RuBoard