Web Services and PHP

NOTE: There was a bug in the SOAP extension prior to version 5.0.2 that prevented signed long values from being passed correctly to and from PHP. As a result, any calls that involved big integers (including the session object's personID) would fail. The long and short of it (no pun intended), you wouldn't be able to do much with Vista web services, because most calls require the session object. The nice PHP volunteers fixed it within 4 days of my reporting it. So, make a mental note to replace all references in this article to PHP 5 with PHP 5.0.2.

For those who haven't heard of it, PHP is a popular, open source scripting language that is especially suited for Web development. PHP commands are embedded in HTML documents and processed each time the pages are requested, much like Microsoft Active Server Pages (ASP) or Java Server Pages (JSP). The language's syntax will be familiar to anyone who has worked with Javascript, Java, C, Basic... you get the picture.

One of the most exciting things about PHP (at least for me) is the wide range of functionality built into it. From database connectivity to regular expressions to FTP to PDF and Flash APIs?, PHP has it all (or almost) and what it doesn't have... well, someone will build it as an extension sooner or later.

For a long time, this was the case for SOAP-based Web Services in PHP. There was a variety of different extensions available and all of them required a bit of tweaking on the server to get them to work.

Enter PHP 5

PHP 5 was released on July 13, 2004 and one of the biggest new features is built-in support for Web Services access using the SOAP protocol. When I found out, I immediately set to work to see how much effort would be required to set it up and create a PHP script to call the Vista Web Services.

It took me about two hours to get it all together, but now that I've done it, I'm hoping others will be able to benefit from my experience and get themselves set up in much less time.

Requirements

PHP 5
Apache web server
Gnome XML Library

I tested PHP 5 with Apache 1.3.12 running on Windows 2000 and the instructions here are specific to Windows 2000, but you can run PHP on several different OS and web server platforms. I will try testing a Linux/Apache setup as well when I get a chance and I'll post my findings here. See the install.txt file included with the PHP distribution for detailed install instructions for your operating system and web server.

NOTE: The nice thing (although many would disagree) about the Windows version of PHP is that SOAP support is already compiled into the binary. If you install on Linux, you will need to compile PHP from source with the --enable-soap option.

Installing PHP 5

Here are the steps I followed for installing PHP 5.

Download the PHP 5 archive and extract it to a directory on the web server. I extracted it in C:\php. (I'll refer to this as the PHP install directory.)
In the PHP install directory, make a copy of the php.ini-recommended file and rename it to php.ini.
Edit php.ini as follows:
Add this line: extension=php_soap.dll
Find the line that contains extension_dir= and change it to: extension_dir = "C:\php"
Move php.ini to the %SYSTEMROOT% directory (on Windows 2000, the default is C:\WINNT).
Copy the php_soap.dll file from the ext subdirectory to the PHP install directory.

Installing Gnome libxml

Extract libxml2.dll from the Gnome XML library distribution and copy it to the PHP install directory.

Configuring Apache

You also need to modify the Apache configuration file.

Add the following lines to httpd.conf:
LoadModule php5_module c:/php/php5apache.dll
AddModule mod_php5.c
AddType application/x-httpd-php .php
Copy php5ts.dll from the PHP install directory into the directory that contains the apache.exe file.

The Moment of Truth

Restart Apache. To see if PHP is installed and working properly, create a file named phpinfo.php in your web server's htdocs directory and add the following code: <?php phpinfo(); ?>
Save the file and open it in a web browser. You should see all kinds of information about your PHP installation. If not, review the install procedure and consult install.txt in your PHP install directory.

If all is well, you can go ahead with something a bit more interesting, like connecting to a WebCT?Vista server and accessing Web Services. Here is a really simple example that uses the Context Web Service to print out the institutions that are available for login:

<?php
$baseUrl = "http://tcvista.pd.webct.com:9999/webct/axis";
$VistaContext = new SoapClient("$baseUrl/Context.wsdl");
$lcs = $VistaContext->getLearningContextList();
$count = count($lcs);
print "There are $count Institutions on this server:<br/>";
print "<table><tr><th>Name</TH><th>GLCID</th></tr>";
foreach($lcs as $lc)
{
print "" . $lc->name . "" . $lc->glcID . "";     
}
print "</table>";
?>

Your results should look something like this:

There are 4 Institutions on this server:
Name GLCID
Institution Name 10.0.2.19-1078797443387-2000832000
Dan Institution 10.0.2.19-1078852595711-2001100000
Northern University 10.0.2.19-1080068696268-2200298000
My Institution 10.0.2.19-1084572727374-2560057000

Known Issues

Here are some things that gave me some grief along the way:

Depending on how PHP error logging is configured, you may get a blank page (in which case, you'll need to check your web server's error log) or you'll see an error message like the following:[Wed Jul 21 09:47:21 2004] [error] PHP Fatal error:
Uncaught SoapFault exception: [WSDL] SOAP-ERROR: Parsing WSDL:
Couldn't load from
http://tcvista.pd.webct.com:9999/webct/axis/Context.wsdl in
c:\Apache\Apache\htdocs\vista_webservices_test.php:3
Stack trace:
#0
Unknown macro: {main}
thrown in c:\Apache\Apache\htdocs\vista_webservices_test.php on line 3
- There is a known bug in PHP 5 that prevents the WSDL files from being downloaded in some situations. If the SOAP fault message looks familiar, do the following:
1. Download the Vista Web Service wsdl files and place them in the same directory as the php script file.
2. In each wsdl file, locate the element, which looks something like this:
  <wsdl:service name="ContextWebService"> <wsdl:port binding="intf:ContextSoapBinding" name="Context"> <wsdlsoap:address location="http://localhost:9999/webct/axis/Context" /> </wsdl:port> </wsdl:service>
1. In the location attribute of wsdl:soapaddress , change localhost to the hostname of the Vista server.
2. Modify the paths in the script accordingly. (In the sample script above, you only need to change the path in the SoapClient constructor to Context.wsdl).
- Here's another error that might come up:[Wed Jul 21 09:56:26 2004] [error] PHP Fatal error:
  Uncaught SoapFault exception: [WSDL] SOAP-ERROR: Parsing Schema:
  unexpectedin schema in
  c:\Apache\Apache\htdocs\vista_webservices_test.php:2
  Stack trace:
  #0
thrown in c:\Apache\Apache\htdocs\vista_webservices_test.php on line 2
You'll probably need to remove all <documentation>, <annotation>, and <wsdl:documentation> tags from the WSDL files.

Conclusion

With a little perseverance, I managed to get the whole thing up and running in less time than I had expected. (I usually spend a lot of time on trial and error and googling exceptions.) PHP is a great language for server-side scripting and now that SOAP/Web Services support is built in, there's a whole new world of possibilities for developing WebCT? Vista server-side solutions. Personally, I won't be using Java to test new Vista Web Service functionality anymore

If you've used Vista Web Services with PHP, .Net, Perl, or some other development platform (especially something really exotic!), feel free to contribute an article here on DevNet?. We want to know about it!

This article originally authored by Paul Monk on the WebCT DevNet