The ckWebServicePlugin allows you to build a webservice api for your symfony applications. It comes with a powerful and easy to use wsdl generator, which creates WS-I compliant wsdl files for a maximum of interopability with PHP, .NET and Java clients.

Developers

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Release 1.4.1 - 19/07/2008

Release 1.4.0 - 17/06/2008

Release 1.2.0 - 10/04/2008

Release 1.1.3 - 29/03/2008

Release 1.0.0 - 12/03/2008

ckWebServicePlugin (for symfony 1.1)

The ckWebServicePlugin allows you to build a webservice api for your symfony applications.
It comes with a powerful and easy to use wsdl generator, which creates WS-I compliant wsdl files for a maximum of interopability with PHP, .NET and Java clients.

Installation

To install the latest release, execute:

> symfony plugin:install ckWebServicePlugin

or to install the current revision, checkout the HEAD revision into a plugins/ckWebServicePlugin folder:

Now configure the plugin how it is described in the next section and clear your cache afterwards.

Configuration

The configuration can be devided into two parts. A basic one, which is mandatory and has to be done in order to get the plugin working.
The second, advanced, part is only required under certain circumstances and when you want to leverage the full power of the plugin.
So if you are using this plugin the first time you can skip the Advanced section.

For more details about the usage of SOAP Headers read the section Using SOAP Headers

module.yml

Every action, which should be callable in webservice mode, needs some configuration so the parameters are accessable through sfRequest::getParameter() and the proper value is returned as result.
This configuration is automaticly done by the webservice:generate-wsdl task, if you don't use the task or want to customize something you have to change the module.yml file corresponding to the action.

You see the name of the webservice method follows the scheme 'moduleName'_'actionName', because this might be not descriptive enough or an alternative scheme is desired,
we will see how to change this. For this we have to change again the action's doc comment:

The h (handler) option was added to the command, if it is not set the @ws-method doc tag is ignored.

The handler option leads to the generation of a MathApiHandler.class.php in the application's lib/ folder.
To enable this handler we have to edit the application's app.yml file and set the handler to MathApiHandler:

soap:
# ...
ck_web_service_plugin:
# ...
# the class that will be registered as handler for webservice requests
handler: MathApiHandler

create a new controller in your project's web/ folder with name 'webservice_name'.php,

if the handler option is set, it will add a 'webservice_name'Handler.class.php to the 'app_name''s lib/ folder.

The arguments explained in detail:

app_name:

specifies the application, which is searched for actions marked with the @ws-enable doc tag

webservice_name:

specifies the name of the webservice

webservice_base_url:

specifies the url under which the webservice will be accessable

The options explained in detail:

environment (short e):

sets the environment for webservice mode

defaults to soap

if you change it, don't forget to change the configuration files accordingly

debug (short d):

enables the debug mode in the generated controller

defaults to false

handler (short h):

generates a custom SOAP handler extending the ckSoapHandler

defaults to false

Understanding result adapters

Until now it wasn't explained how the result of an action is got, we have just seen, that the result was assigned to the $this->result property and a sfView constant was returned, like sfView::SUCCESS.

Because an action should be reusable in web and webservice mode, we can't rely on the return value, because in web mode it always has to be a template name.
For this reason the result adpater pattern was introduced. This means to get the action result an adapter object of a subclass of ckAbstractResultAdapter is used.
Which one is used is determined by the configuration in the action's module.yml file how it is shown in the Configuration->Advanced->module.yml section.
The param array in the module.yml file is passed to the result adapter's constructor and contains adapter specific settings.

There are three built-in adapters:

ckPropertyResultAdapter:

gets the result from a property of the action object

parameters:

property:

specifies the property name

defaults to result

if there is only one property, this one is returned, also its name doesn't match the specified property

ckMethodResultAdapter:

gets the result from a method call on the action object

parameters:

method:

specifies the method name

ckRenderResultAdapter:

executes the standard render pipeline and returns the resulting text

if this adapter is used the return value has to be string

parameters:

none

You can easily implement your own adapters by extending the ckAbstractResultAdapter class and overriding the abstract ckAbstractResultAdapter::getResult() method.

Using arrays and objects as parameters or result values

In the previous examples only simple types have been used for parameters and result values, but you propably want to use objects, arrays of simple types or arrays of complex types.
To illustrate these features we will stick to the example used earlier.

As we see, we can use a lightweight version of the ComplexNumber class, the only important thing is, that the properties are the same as defined in the wsdl file.

In this section you have learned how to work with arrays and classes, the next section covers the usage of SOAP Headers.

Using SOAP Headers

SOAP Headers provide a way to send additional information, which are not directly or semantically related to the original method call.
An good example for this are authentication information, so the use of a certain method can be restricted to a group of users.

To demonstrate the support for SOAP Headers, we will stick to the simple multiplication example used previously.

When the application receives a SOAP Header a webservice.handle_header event is dispatched (it is a notifyUntil event), it has two attributes, the first is header holding the name of the header and the second is data containing an instance of the header's data class.
To do the authentication stuff in our example we will define an AuthHeaderListener class by creating an AuthHeaderListener.class.php in the application's lib/ folder with the following content: