65 users Sign-in to change your status

This plugin exposes your actions as a webservice api. WebServices Development

• Homepage
• Repository
• Report a bug
• Download package
• Browse source

Developers

Name	Status	Email
Christian Kerl	lead	ed.bew <<ta>> lrek-naitsirhc

License

Copyright (c) 2008 Christian Kerl

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.

Releases for sf 1.4

Version	License	API	Released
4.0.0stable	MIT license	4.0.0stable	18/06/2010

Releases for sf 1.3

Version	License	API	Released
4.0.0stable	MIT license	4.0.0stable	18/06/2010

Releases for sf 1.2

Version	License	API	Released
3.1.0stable	MIT license	3.1.0stable	09/01/2010
3.0.0stable	MIT license	3.0.0stable	17/01/2009

Releases for sf 1.1

Version	License	API	Released
2.3.0stable	MIT license	2.3.0stable	08/08/2009
2.2.2stable	MIT license	2.2.2stable	16/01/2009
2.2.1stable	MIT license	2.2.1stable	20/11/2008
2.2.0stable	MIT license	2.2.0stable	20/11/2008
2.1.0stable	MIT license	2.1.0stable	19/08/2008
2.0.0devel	MIT license	2.0.0devel	19/07/2008

Releases for sf 1.0

Version	License	API	Released
1.5.0stable	MIT license	1.5.0stable	19/08/2008
1.4.1stable	MIT license	1.4.1stable	19/07/2008
1.4.0stable	MIT license	1.4.0stable	17/06/2008
1.2.0stable	MIT license	1.2.0stable	10/04/2008
1.1.3stable	MIT license	1.1.3stable	29/03/2008
1.0.0stable	MIT license	1.0.0stable	12/03/2008

Join this plugin team

Other releases

Release 4.0.0 - 18/06/2010

Release 3.1.0 - 09/01/2010

Release 3.0.0 - 17/01/2009

Release 2.3.0 - 08/08/2009

Release 2.2.2 - 16/01/2009

Release 2.2.1 - 20/11/2008

Release 2.2.0 - 20/11/2008

Release 2.1.0 - 19/08/2008

Release 2.0.0 - 19/07/2008

Release 1.5.0 - 19/08/2008

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

ckWebService plugin (for symfony 1.1)

The ckWebServicePlugin is a symfony plugin that let you expose your modules and actions as a webservice.

The Plugin is based on the standard PHP SOAP module, see http://de.php.net/manual/en/ref.soap.php.

It offers automatic generation of .wsdl files from your source code, using a WSDL Generator (ckWsdlGenerator).

Installation

To install the latest release:

> symfony plugin:install ckWebServicePlugin

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

> svn co http://svn.symfony-project.com/plugins/ckWebServicePlugin/trunk

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

Configuration

The plugin configuration is split over several yml files, some settings are mandatory others are optional and should only be set if you want to change the default behavior.

app.yml

Configure general plugin settings.

# your enviroment for web service mode
soap:
  # enable the `ckSoapParameterFilter` [mandatory]
  enable_soap_parameter: on
  ck_web_service_plugin:
    # the location of your .wsdl file, relative to the web/ folder [mandatory]
    wsdl: myWebService.wsdl 
    # the class that will be registered as handler for webservice requests [optional]
    handler: ckSoapHandler
    # set the persistence mode [optional]
    persist: %SOAP_PERSISTENCE_SESSION%
    # set wether or not action views should be rendered as normal [optional]
    render: off
    # set the custom method every action class implements to get the result of the action [optional]
    result_callback: getSoapResult
    # the options array, which is passed to the `SoapServer` constructor, is the same as described in the php soap documentation [optional]
    soap_options:
      encoding: utf-8
      soap_version: %SOAP_1_2%
    # register your SoapHeaders and their corresponding data container class [optional]
    soap_headers:
      FooHeader:                     # name of the soap header
        class: MyFooHeaderDataClass  # name of the data class
      BarHeader:
        class: MyFooHeaderDataClass

module.yml

The configuration described here is done by the WSDL Generator!

The plugin allows per action configuration of parameters passed by the soap call so you can use them like request parameters. Also you can configure per action in which action member the result is stored, if not set result is assumed, and wether or not to render the view as result.

# your enviroment for web service mode
soap:
  # the following part added by the WSDL Generator for each action, you only have to configure this if you don't use the generator
  action_name:
    # enable the action to be called from ckWebServiceController, should prevent malicious calls to actions through manipulated soap messages [mandatory]
    enable: true
    # ordered list of the parameters [optional]
    parameter: [first_param, second_param]
    # the name of the action member, which contains the result, if `render` is true this has no effect [optional]
    result: null
    # set wether or not the view should be rendered as normal, if this isn't set the value from `ck_web_service_plugin: render` in `app.yml` is used [optional]
    render: false

factories.yml

Enable the ckWebServiceController, this is mandatory.

# your enviroment for web service mode
soap:
  controller:
    class: ckWebServiceController

filters.yml

Enable the ckSoapParameterFilter, this is mandatory.

soap_parameter:
  class: ckSoapParameterFilter
  param:
    # `app_enable_soap_parameter` has to be set to `on` so the filter is only enabled in soap mode
    condition: %APP_ENABLE_SOAP_PARAMETER%

php.ini

Disable wsdl file caching, when your developing to see changes to the wsdl file instantly, this is optional.

soap.wsdl_cache_enabled=0

WSDL Generator (ckWsdlGenerator)

The WSDL Generator offers the possibility to search all your module actions for web service enabled actions and generate a wsdl file with input parameters and return types from the code. Also it generates yaml configuration for mapping of web service method parameters to request parameters. And lastly generates a controller script, the endpoint of the webservice.

Module actions are enabled for export by adding a @ws-enable to the doc comment block. Also actions have no function parameters you should add @param and one @return to each comment block so the web service methods have the proper input and output types. The Generator allows complex types as input/output values so you can use your classes.

The method names of the web service methods follow the scheme: module_Action.

The generator is used through the webservice:generate-wsdl symfony cli task, it has the following syntax:

> symfony webservice:generate-wsdl [--environment=soap] [--debug=on] app_name webservice_name webservice_base_url

It will generate a wsdl file and a controller script in the web/ folder and add / modify all module.yml files of your actions.

Example

Howto execute the webservice:generate-wsdl task shows the following example:

> symfony webservice:generate-wsdl frontend myFooBarService http://www.myfoobar.com/

• This will add a myFooBarService.php and a myFooBarService.wsdl to your /web folder.

• The endpoint for the generated service will be http://www.myfoobar.com/myFooBarService.php.

Howto enable actions for export shows this example:

<?php
class fooActions extends sfActions
{
  /**
   * Executes index action
   *
   * @ws-enable
   * @param string $test A string parameter
   *
   * @return string      A string
   */
  public function executeIndex()
  {
    $this->result = 'Parameter $test='.$this->request->getParameter('test');
 
    //return what you want, the view rendering will be bypassed any way
    return sfView::SUCCESS;
  }
 
  /**
   * A method which will not be exposed in the wsdl.
   *
   * @param string $test A string parameter
   *
   * @return string      A string
   */
  public function executeBar()
  {
    $this->something = "some text!";
  }
}

• This will generate a method with the name foo_Index with a parameter named test of type string and a return value of type string.

This class has no getSoapResult method, because the result of the action is stored in the result member, see 'Internals'->'Getting the action result' for more details.

sfComponent Extension

To determine if your application is currently in soap mode you can use the isSoapRequest() method in your component and action classes, to be more precise: in all subclasses of sfComponent.

SoapHeader

The plugin also supports the use of SoapHeaders. You can use them to send additional data, like authentication data, with a method call.

The data a soap header carries is always stored in a complex type, that means you have to specify a class in which the SoapServer can put the incoming data. For compatibility reasons to Microsofts .NET Framework webservice implementation the SoapHeader and the data class need to have the same name. But fortunatly PHP's SoapServer implementation allows a mapping of types, defined in the *.wsdl file, to PHP classes. To define these mappings you have to use the soap_headers setting in app.yml. The keys in this array are always the names of the SoapHeaders. The values are arrays containing a key class and as value the name of the data class. This enables you to give SoapHeaders, transporting the same kind of data, different names.

The data classes have to be in your project's or application's lib/ folder.

To handle incoming headers you have to listen to the webservice.handle_header event, it is a notifyUntil event. The event has two parameters. The first is header containing the name of the SoapHeader. The second is data containing an instance of the data class. If you want to modify the value of the header, use $event->setReturnValue($modifiedData) where $modifiedData is an instance of the data class.

The following example shows how to process a SoapHeader containing authentication data:

• The SoapHeader name will be SecurityHeader and the corresponding data class will be AuthData.

• Enable the header on a webservice enabled action:

  <?php
   
  class secureActions extends sfActions
  {
    /**
     * Action to multiply a number with a factor
     *
     * @ws-enable
     * @ws-header SecurityHeader: AuthData
     *
     * @param int $factor
     * @param int $number
     *
     * @return int
     */
    public function executeCalc($request)
    {
      if($this->getUser()->isAuthenticated())
      {
        $this->result = $request->getParameter('factor') * $request->getParameter('number');
      }
      else
      {
        $this->result = null;
      }
    }
  }

The @param doctag for the $request parameter is removed so it is not exported by the WSDL Generator.

• Add the following lines to the app.yml file:

  # your enviroment for web service mode
  soap:
    ck_web_service_plugin:
      # the rest of the plugin config
      # ...
      soap_headers:
        SecurityHeader:
          class: AuthData
  

• Create an AuthData.class.php file in your application's lib/ folder, this will be the data class for the header.

  <?php
   
  /**
   * AuthData stores authentication data send with a SoapHeader.
   */
  class AuthData
  {
      /**
       * Flag wether the authentication succeded.
       *
       * @var bool
       */
      public $success;
   
      /**
       * The user name.
       *
       * @var string
       */
      public $name;
   
      /**
       * The user password.
       *
       * @var string
       */
      public $pass;
  }

• Register an event listener in your application's configuration class and create the listener class in your application's lib/ folder.

  • Modified application's configuration class:

    <?php
     
    class appConfiguration extends sfApplicationConfiguration
    {
      public function configure()
      {
        $this->dispatcher->connect('webservice.handle_header', array('SecurityHeaderListener', 'listenToWebserviceHandleHeaderEvent'));
      }
    }

  • Create a SecurityHeaderListener.class.php file in your application's lib/ folder, this will be the event listener class:

    <?php
     
    /**
     * SecurityHeaderListener listens to the webservice.handle_header event for the SecurityHeader.
     */
    class SecurityHeaderListener
    {
      const HEADER_NAME = 'SecurityHeader';
     
      /**
       * Handles a webservice.handle_header event, if the header is of type SecurityHeader.
       *
       * @param sfEvent $event A sfEvent instance.
       */
      public static function listenToWebserviceHandleHeaderEvent(sfEvent $event)
      {
        if($event['header'] == self::HEADER_NAME)
        {
          $return = null;
     
          if($event['data']->name == 'test' && $event['data']->pass == 'test')
          {
            $return = clone $event['data'];
            $return->success = true;
            sfContext::getInstance()->getUser()->setAuthenticated(true);
          }
     
          $event->setReturnValue($return);
     
          return true;
        }
        else
        {
          return false;
        }
      }
    }

Internals

The next three sections should give an inside view of the plugin architecture.

ckSoapHandler

The ckSoapHandler class is the default web service request handler class. Because just since PHP 5.2 a method SoapServer::setObject(...) exists, which allows to set a object, which will handle requests, so to support older versions the SoapServer::setClass(...) is used. Because there should only be one instance of ckWebServiceController a helper class ckSoapHandler is defined, which just passes the requests back to the controller instance. This mechanism only works if you use method names of scheme module_Action. If you want to use custom web service method names see section 'Custom RequestHandler'.

ckSoapParameterFilter

Usually action method definitons (execute*) have no input parameters, instead data is aquired through getRequestParameter(...) method. In contrast to web service methods real parameters are passed. In conclusion we have to provide a mapping of function parameters to request parameters. This is done by the 'ckSoapParameterFilter' it takes the names of the request parameters from the corresponding module.yml. The names in the configuration have to be in the same order like the function arguments.

In general an array containing all params can be retrieved by: $request->getParameter('param', null, 'ckWebServicePlugin');.

Getting the action result

There are multiple stages of getting the action result. First we try to invoke an implementation of the result_callback configured in app.yml. If none is found on the action instance a default getter is mixed into the action and is called. In this version this is down by listening to the component.method_not_found event.

This default getter has the following behavior:

• when rendering is enable for the action (depending on configuration in module.yml and app.yml):
  • the rendered view is returned
• when rendering is disabled:
  • if only one variable exists in the actions parameter holder (set via $actionInstance->var = 'some value';), this variable is returned
  • if a default key into the parameter holder is configured using soap_return_key in the module.yml (if this is not configured result is assumed) and this key exists, its corresponding value is returned
  • if both approaches fail nothing is returned

The described mechanism should be an easy to use, but powerfull way for you to get the result of an action.

Custom RequestHandler

If the method names of scheme module_Action are to abstract for you or you have already a wsdl file I recommend to implement your own handler class. Don't forget to set this new handler class in app.yml.

Example

The following example assumes you have a wsdl with a web service method named descriptiveFooMethod and two parameters foo and bar. And a call to this should be redirected to the action index in the module fooModule.

<?php
class mySoapHandler
{
  public function descriptiveFooMethod($foo, $bar)
  {
    return sfContext::getInstance()->getController()->invokeSoapEnabledAction('fooModule', 'index', array($foo, $bar));
  }
}

If you have configured the module.yml of the fooModule in the following way:

# your enviroment for web service mode
soap:
  index:
    enable: true
    parameter: [foo, bar]

parameter mapping will work like you expect it.

TODO

• decide how to handle redirects
• write tests
• enable nusoap, PEAR::SOAP as soap_server

Contributing

If you would like to contribute just let me know.

Contact

If you have any questions, suggestions or bug reports, write an email to: christian-kerl [at] web [dot] de