readme.txt

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?

1. Determine a namespace based on the URI the webservice has been called
2. Determine the endpoint based on the URI the webservice has been called
3. 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
4. Determine a writeable cache folder
5. Load extensions, if the PHP "glob" function works
6. Load your webservice class, if it's not loaded already
7. Create the WSDL
8. Return HTML, PHP, the WSDL or configure and run a SOAP server
9. 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:

1. 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

2. 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.

PhpWsdl - Generate WSDL from PHP
Copyright (C) 2011  Andreas Müller-Saala, 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.

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.