solomonainomugisha/php-wsdl-creator

Contents

- Why another WSDL generator?
- How to use PhpWsdl
- The quick mode
- How to get rid of the NULL-problem
- Demonstrations
- To cache or not to cache
- Debugging
- Undocumented
- SOAP with JavaScript
- SOAP with Microsoft Visual Studio
- License
- Support
- Project homepage

Why another WSDL generator?

I started to develop my own WSDL generator for PHP because the ones I saw had too many disadvantages for my purposes. The main problem - and the main reason to make my own WSDL generator - was receiving NULL in parameters that leads the PHP SoapServer to throw around with "Missing parameter" exceptions. F.e. a C# client won't send the parameter, if its value is NULL. But the PHP SoapServer needs the parameter tag with 'xsi:nil="true"' to call a method with the correct number of parameters.

At the end the NULL-problem still exists a little bit, but I've created a thin, fast and ComplexType-supporting WSDL generator for my PHP webservices - and maybe yours?

If this isn't enough for your application, I recommend you to have a look at Zend.

How to use PhpWsdl

To use PhpWsdl you need these classes:
- class.phpwsdl.php
    The base class for creating WSDL, running a SOAP server, or creating a PHP 
    SOAP client proxy class

- class.phpwsdlclient.php
    The base class for doing SOAP requests or creating a PHP SOAP client proxy 
    class from a SOAP webservice

- class.phpwsdlcomplex.php
    Represents a complex type

- class.phpwsdlelement.php
    Represents an element of a complex type

- class.phpwsdlenum.php
    Represents an enumeration

- class.phpwsdlformatter.php
    A PHP class to format a XML string human readable

- class.phpwsdlmethod.php
    Represents a SOAP method

- class.phpwsdlobject.php
    The parent class for PhpWsdl objects

- class.phpwsdlparam.php
    Represents a parameter or a return value of a SOAP method

- class.phpwsdlparser.php
    The PHP source code parser

- class.phpwsdlproxy.php
    A proxy webservice class to get rid of the NULL problem

You only need to include the 'class.phpwsdl.php' in your project to use 
PhpWsdl. This class will load it's depencies from the same location.

PhpWsdl enables you to mix class and global methods in one webservice, if you 
use the PhpWsdlProxy class (see demo3.php).

If you want to use my solution for transferring hash arrays with SOAP, you 
can also include 'class.phpwsdlhash.php' (not loaded by default). This file 
contains some type definitions and methods for working with hash arrays. Have 
a look inside for some documentation.

Call your webservice URI without any parameter to display a HTML description 
of the SOAP interface. Attach "?wsdl" to the URI to get the WSDL definition. 
Add "&readable" too, to get humen readable WSDL. Attach "?phpsoapclient" to 
download a PHP SOAP client proxy for your webservice.

Some classes can consume settings. Open the source code and have a look at the 
constructor to see what you can do with settings. Settings are defined with 
the @pw_set keyword in comments. An example usage for settings can be found in 
class.complextypedemo.php.

You don't have to specify the SOAP endpoint URI - PhpWsdl is able to determine 
this setting. But since I don't know your environment and your purposes, it's 
still possible to change the SOAP endpoint location per instance.

Open the demo*.php files in your PHP source editor for some code examples. At 
the Google Code project you'll find some Wikis, too.

Note: PhpWsdl can include documentation tags in WSDL. But f.e. Visual Studio 
won't use these documentations for IntelliSense. This is not a bug in PhpWsdl.

The quick mode

PhpWsdl can determine most of the required configuration to run a SOAP server. The fastest way is:

PhpWsdl::RunQuickMode();

This example requires the webservice handler class to be in the same file. If the class is located in another file, you can specify the file like this:

PhpWsdl::RunQuickMode('class.soapdemo.php');

Or, if there are multiple files to parse for WSDL definitions:

PhpWsdl::RunQuickMode(Array( 'class.soapdemo.php', 'class.complextypedemo.php' ));

When providing more than one file, be sure the first class in the first file is the webservice handler class!

You even don't need to load your classes with "require_once" - let PhpWsdl do it for you.

But what will the quick mode do for you, what you don't know?

Determine a namespace based on the URI the webservice has been called
Determine the endpoint based on the URI the webservice has been called
Determine the webservice name (and handler class name) from the first exported class of the running script or class.webservice.php or the list of files
Determine a writeable cache folder
Load extensions, if the PHP "glob" function works
Load your webservice class, if it's not loaded already
Create the WSDL
Return HTML, PHP, the WSDL or configure and run a SOAP server
Exit the script execution

If your webservice can run without giving a file name or list to the constructor, you may want to try the autorun feature. There are two ways to enable the autorun:

Edit the source of class.phpwsdl.php and set the property PhpWsdl::$AutoRun to TRUE to enable the autorun for all your webservices that use PhpWsdl
Set the global variable $PhpWsdlAutoRun to TRUE to enable the autorun for the current webservice

The autorun is demonstrated in demo4/5.php.

How to get rid of the NULL-problem

When a SOAP client like .NET is making a SOAP request and a parameter is NULL, 
the parameters tag won't be included in the SOAP request. The PHP SoapServer 
will then throw around with "Missing parameter" exceptions or call your 
method with a wrong parameter count.

The only way I found to get rid of this problem is using a proxy class that is 
able to find missing parameters to call the target method correctly. For this 
it's important that the PHP SoapServer don't know the WSDL of your webservice.

But this solutions opens another problem: If the PHP SoapServer don't know 
your WSDL, return values won't be encoded properly. You have to encode them by 
yourself using PHPs SoapVar class. I didn't implement an encoding routine in 
the proxy yet - maybe coming soon.

To see an example how to use the proxy, please look into demo3.php.

Another solution is to work with complex types that serve the parameters. Then 
every method that supports NULL in parameters needs to use a complex type as 
the only one parameter that includes the parameters as elements. In this case 
you don't need the proxy class.

Demonstrations

This package contains some demonstrations:

demo.php A basic usage demonstration
demo2.php How to use PhpWsdl without PHP comment definitions of the WSDL elements
demo3.php How to use the proxy to get rid of the NULL parameter problem How to mix class and global methods in one webservice
demo4.php A quick and dirty single file usage example
demo5.php A quick demonstration how to serve global methods
demo6.php A quick demonstration how to use the SOAP client

Some demonstrations are using the following classes:

class.complextypedemo.php How to define a complex type and array types
class.soapdemo.php A simple SOAP webservice class with some test methods

If you want to test PhpWsdl online without installing it on your own server, you can try these URIs:

http://wan24.de/test/phpwsdl2/demo.php -> HTML documentation output & endpoint http://wan24.de/test/phpwsdl2/demo.php?WSDL -> WSDL output http://wan24.de/test/phpwsdl2/demo.php?PHPSOAPCLIENT -> PHP output

demo?.php are available under the same location, too. If you try the PDF download, you'll notice that you get other results as if you try it from your server. This is because I use a valid license key for the HTML2PDF API - PhpWsdl will then create a TOC and attach the WSDL files and a PHP SOAP client into the PDF, so it's very easy for you to provide your webservice fully documented any ready to use for other developers.

Note: Sometimes my test URIs won't work because I'm testing a newer version...

To cache or not to cache

I recommend to use the WSDL caching feature of PhpWsdl. For this you need 
a writeable folder where PhpWsdl can write WSDL files to. Using the cache is 
much faster in an productive environment. During development you may want to 
disable caching (see the demo scripts for those two lines of code). To 
completely disable the caching feature, you need to set the static CacheFolder 
property of PhpWsdl to NULL. Without a cache folder (or when using the proxy 
class) returning complex types needs attention: Use PHPs SoapVar class to 
encode them properly.

Debugging

All debug messages are collected with the PhpWsdl::Debug method. All messages are being collected in the PhpWsdl::$DebugInfo array. But PhpWsdl can also write to a text log file, too.

To enable debugging, set the property PhpWsdl::$Debugging to TRUE:

PhpWsdl::$Debugging=true;

To enable writing to a log file, set the property PhpWsdl::$DebugFile to the location of the file:

PhpWsdl::$DebugFile='./cache/debug.log';

You can enable adding backtrace informations in the debug message by setting the property PhpWsdl::$DebugBackTrace to TRUE:

PhpWsdl::$DebugBackTrace=true;

Undocumented

Things that are not yet demonstrated are:
- Adding/Removing predefined basic types in PhpWsdl::$BasicTypes
- Usage of the non-nillable types
- Hooking in PhpWsdl (see inline documentation)
- How to handle hash arrays with PhpWsdlHashArrayBuilder (see inline 
  documentation)
- How to develop extensions for an extended complex type support f.e.

SOAP with JavaScript

For using SOAP with JavaScript I use the SOAPClient class from Matteo Casati. I also tested this class with the PhpWsdl demonstrations, and I was able to receive complex types as JavaScript object. But sending a complex type to the webservice failed with some constructor-problem within the SOAPClient class. Currently I haven't worked on a solution for this problem because I don't use complex types... Maybe using "anyType" can fix this problem.

If you want to use foreign SOAP webservices with your AJAX application, you need to use a SOAP webservice proxy. This addon is available as seperate download or directly from the SVN respository. The AJAX proxy is using JSON - have look at http://www.json.org/js.html for informations how to en- and decode objects to/from JSON in your JavaScript application.

But if you use JavaScript at the client side you should have a look at the PhpWsdlServers extension that serves a JSON webservice and produces JavaScript client code for you. Since I added the JSON webservice I don't use SOAP with JavaScript clients in my projects anymore.

SOAP with Microsoft Visual Studio

All tests using Microsoft Visual Studio 2010 ran without any problems. You can 
add your webservice as service or web reference to your project. Visual Studio 
will then generate proxy classes and other things for you. Earlier or later 
versions of Visual Studio or .NET should be compatible, too.

License

PhpWsdl is GPL (v3 or later) licensed per default. I offer a LGPL like license bundled with an individual SLA for your company, if required - contact me with email to schick_was_an at hotmail dot com for details.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses/.

See license.txt for the full GPLv3 license text.

Support

If you need help implementing PhpWsdl, I may help you with email. Contact me 
at schick_was_an at hotmail dot com. If you found an error, please report it 
at the project homepage.

The is a online wiki at the project homepage, where you may find some 
additional documentation and help, too.

Project homepage

PhpWsdl is hosted by Google Code. The project homepage is located at

http://code.google.com/p/php-wsdl-creator/

This location should be the only source for downloads, source, Wikis and reported issues.

You can find my German speaking homepage here (automatic language translation is available via Google Translate plugin):

http://wan24.de

There you'll find some other projects and some free downloads that are maybe interesting for you, too.

solomonainomugisha / php-wsdl-creator

readme