Contents
~~~~~~~~
- Why another WSDL generator?
- How to use PhpWsdl
- How to get rid of the NULL-problem
- Demonstrations
- To cache or not to cache
- 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 it's 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 
NuSOAP (sourceforge.net/projects/nusoap).

How to use PhpWsdl
~~~~~~~~~~~~~~~~~~
To use PhpWsdl you need these classes:
- class.phpwsdl.php
- class.phpwsdlcomplex.php
- class.phpwsdlelement.php
- class.pgpwsdlmethod.php
- class.phpwsdlparam.php
- class.phpwsdlproxy.php

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.

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.

You can use my RunServer method, but you don't need to. You can use any SOAP 
server with the WSDL generated by PhpWsdl. I personally prefer using the PHP 
SoapServer.

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 settings. But since I don't know your environment and your purposes, it's 
still possible to change the SOAP endpoint location.

Open the demo*.php files in your PHP source editor for some code examples.

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.

There is another disadvantage when using the proxy: The WSDL must be generated 
for most SOAP requests, not using the cache. This may be an performance issue. 
A way to make this less ressource intensive you can create WSDL definitions 
from code instead of using PHP comments (see demo2.php). Then PhpWsdl won't 
need parsing your PHP source for a SOAP request.

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

These 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

All examples should produce equal and valid WSDL.

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 CacheFolder 
property in your PhpWsdl instance 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.

Undocumented
~~~~~~~~~~~~
Things that are not yet demonstrated are:
- Adding/Removing predefined basic types in PhpWsdl->BasicTypes
- Hooking in PhpWsdl (see inline documentation)
- Adding support for more keywords to the definition parser in PhpWsdl (see 
  inline documentation, you'll need to modify the regular expressions and use 
  hooking)
- How to handle hash arrays with PhpWsdlHashArrayBuilder

SOAP with JavaScript
~~~~~~~~~~~~~~~~~~~~
For using SOAP with JavaScript I use the SOAPClient class from Matteo Casati. 
I also tested this class with these 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...

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 yout project. Visual Studio 
will then generate proxy classes and other things for you. Earlier or later 
versions of Visual Studio or .NET should be also compatible.

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.

PhpWsdl - Generate WSDL from PHP
Copyright (C) 2011  Andreas Zimmermann, wan24.de 

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.

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:

http://wan24.de

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