Development

Changeset 8152

You must first sign up to be able to contribute.

Changeset 8152

Show
Ignore:
Timestamp:
03/29/08 21:24:49 (7 months ago)
Author:
chrisk
Message:

[ckWebServicePlugin] rewritten plugin documentation

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • plugins/ckWebServicePlugin/trunk/README

    r8062 r8152  
    99== Installation == 
    1010 
    11   * Install the plugin 
    12  
    13     execute:     
    14  
    15     {{{ 
    16       symfony plugin-install http://plugins.symfony-project.com/ckWebServicePlugin 
    17     }}} 
    18  
    19     or: 
    20  
    21     download the attached archive and put the `ckWebServicePlugin` into your `/plugins` folder 
    22  
    23   * Configure the application in your `app.yml` 
    24  
    25     {{{ 
    26       # your soap enviroment 
    27       soap: 
    28         # enable the `ckSoapParameterFilter` 
    29         enable_soap_parameter: on 
    30         ck_web_service_plugin: 
    31           # the location of your .wsdl file 
    32           wsdl: http://localhost/myWebService.wsdl 
    33           # the class that will be registered as handler for webservice requests 
    34           handler: ckSoapHandler 
    35           # set the persistence mode 
    36           persist: %SOAP_PERSISTENCE_SESSION% 
    37           # set the method every action has to implement to get the result of the action 
    38           result_callback: getSoapResult 
    39           # the options array, which is passed to the `SoapServer` constructor 
    40           options: 
    41             encoding: utf-8 
    42             soap_version: %SOAP_1_2% 
    43     }}} 
    44  
    45     You only have to configure `wsdl`, `options` and set `enable_soap_parameter` to `on`, if you want to use the standard settings shown above. 
    46  
    47   * Enable the controller in your `factories.yml` 
    48  
    49     {{{ 
    50       # your soap enviroment 
    51       soap: 
    52         controller: 
    53           class: ckWebServiceController 
    54     }}} 
    55  
    56   * Enable the `ckSoapParameterFilter` in your `filters.yml` 
    57  
    58     {{{ 
    59       soap_parameter: 
    60         class: ckSoapParameterFilter 
    61         param: 
    62           # `app_enable_soap_parameter` has to be set to `on` so the filter is only enabled in soap mode 
    63           condition: %APP_ENABLE_SOAP_PARAMETER% 
    64     }}} 
    65  
    66   * Clear your cache 
    67  
    68     {{{ 
    69       symfony cc 
    70     }}} 
    71  
    72 == Enabling actions for automatic wsdl generation == 
    73  
    74   * Add `@ws-enable`-tag to the comment block 
    75  
    76   * Also the method has no parameters add `@param`-tags for each parameter you want to use 
    77  
    78   * Add a `@return`-tag for the return type of the method 
    79  
    80   * The following example action should illustrate the use 
    81  
    82     {{{       
    83       class fooActions extends sfActions 
     11  To install the current release execute: 
     12   
     13  {{{ 
     14    symfony plugin-install http://plugins.symfony-project.com/ckWebServicePlugin 
     15  }}} 
     16   
     17  or to install the current revision, checkout: 
     18   
     19  {{{ 
     20    http://svn.symfony-project.com/plugins/ckWebServicePlugin/trunk 
     21  }}} 
     22 
     23  into a ''plugins/ckWebServicePlugin'' folder. 
     24 
     25  After this: configure the plugin how it is described in the next section and clear your cache. 
     26 
     27== Configuration == 
     28 
     29  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. 
     30 
     31=== app.yml === 
     32 
     33  Configure general plugin settings. 
     34 
     35  {{{ 
     36    # your enviroment for web service mode 
     37    soap: 
     38      # enable the `ckSoapParameterFilter` [mandatory] 
     39      enable_soap_parameter: on 
     40      ck_web_service_plugin: 
     41        # the location of your .wsdl file, relative to the web/ folder [mandatory] 
     42        wsdl: myWebService.wsdl  
     43        # the class that will be registered as handler for webservice requests [optional] 
     44        handler: ckSoapHandler 
     45        # set the persistence mode [optional] 
     46        persist: %SOAP_PERSISTENCE_SESSION% 
     47        # set the custom method every action class implements to get the result of the action [optional] 
     48        result_callback: getSoapResult 
     49        # the options array, which is passed to the `SoapServer` constructor, is the same as described in the php soap documentation [optional] 
     50        options: 
     51          encoding: utf-8 
     52          soap_version: %SOAP_1_2% 
     53  }}} 
     54 
     55=== module.yml === 
     56 
     57  '''Some of the configuration described here is done by the WSDL Generator!''' 
     58   
     59  The plugin allows per action configuration of parameters passed by the soap call so you can use them like request parameters. 
     60  Also you can configure per action in which action member the result is stored, if not set ''result'' is assumed. 
     61 
     62  {{{ 
     63    # your enviroment for web service mode 
     64    soap: 
     65      # the following part is done by the WSDL Generator, you only have to configure this if you don't use the generator 
     66      soap_parameter_map: 
     67        # the action name [mandatory] 
     68        test: 
     69          # the name of the first action parameter 
     70          - test 
     71          # the name of the second, third, ... action parameter 
     72          - second 
     73          - ... 
     74      # the name of the action member, which contains the result [optional] 
     75      soap_return_key: result_key 
     76  }}} 
     77 
     78=== factories.yml === 
     79 
     80  Enable the ''ckWebServiceController'', this is mandatory. 
     81 
     82  {{{ 
     83    # your enviroment for web service mode 
     84    soap: 
     85      controller: 
     86        class: ckWebServiceController 
     87  }}} 
     88 
     89=== filters.yml === 
     90 
     91  Enable the ''ckSoapParameterFilter'', this is mandatory. 
     92   
     93  {{{ 
     94    soap_parameter: 
     95      class: ckSoapParameterFilter 
     96      param: 
     97        # `app_enable_soap_parameter` has to be set to `on` so the filter is only enabled in soap mode 
     98        condition: %APP_ENABLE_SOAP_PARAMETER% 
     99  }}} 
     100 
     101=== php.yml === 
     102 
     103  Disable wsdl file caching, when your developing to see changes to the wsdl file instantly, this is optional. 
     104   
     105  {{{ 
     106    set: 
     107      soap.wsdl_cache_enabled: off 
     108  }}} 
     109 
     110== WSDL Generator == 
     111 
     112  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. 
     113  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. 
     114   
     115  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. 
     116  The Generator allows complex types as input/output values so you can use your classes. 
     117   
     118  The method names of the web service methods follow the scheme: ''module_Action''. 
     119   
     120  The generator is used through the ''wsdl-build'' symfony cli task, it has the following syntax: 
     121   
     122  {{{ 
     123    symfony build-wsdl app_name env_name [controller_name] [debug] webservice_name webservice_base_url 
     124  }}} 
     125   
     126  The first four parameters are the same as of the ''init-controller'' task. 
     127   
     128  It will generate a wsdl file and a controller script in the ''web/'' folder and add / modify all ''module.yml'' files of enabled actions. 
     129 
     130=== Example === 
     131 
     132  Howto execute the ''wsdl-build'' task shows the following example: 
     133   
     134  {{{ 
     135    symfony build-wsdl fronted soap myFooBarService http://www.myfoobar.com/ 
     136  }}} 
     137 
     138    * This will add a ''frontend_soap.php'' and a ''myFooBarService.wsdl'' to your ''/web'' folder. 
     139 
     140    * The endpoint for the generated service will be ''http://www.myfoobar.com/frontend_soap.php''. 
     141     
     142  Howto enable actions for export shows this example: 
     143   
     144  {{{ 
     145  #!php 
     146    class fooActions extends sfActions 
     147    { 
     148      /** 
     149       * Executes index action 
     150       * 
     151       * @ws-enable 
     152       * @param string $test A string parameter 
     153       * 
     154       * @return string      A string 
     155       */ 
     156      public function executeIndex() 
    84157      { 
    85         /** 
    86          * Method to get the result, when in soap mode 
    87          */ 
    88         public function getSoapResult() 
    89         { 
    90           return $this->result; 
    91         } 
    92  
    93         /** 
    94          * Executes index action 
    95          * 
    96          * @ws-enable 
    97          * @param string $test A string parameter 
    98          * 
    99          * @return string      A string 
    100          */ 
    101         public function executeIndex() 
    102         { 
    103             $this->result = 'Parameter $test='.$this->request->getParameter('test'); 
    104  
    105             //return what you want, the view rendering will be bypassed any way 
    106             return sfView::SUCCESS; 
    107         } 
    108  
    109         /** 
    110          * A method which will not be exposed in the wsdl. 
    111          * 
    112          * @param string $test A string parameter 
    113          * 
    114          * @return string      A string 
    115          */ 
    116         public function executeBar() 
    117         { 
    118  
    119         } 
     158        $this->result = 'Parameter $test='.$this->request->getParameter('test'); 
     159 
     160        //return what you want, the view rendering will be bypassed any way 
     161        return sfView::SUCCESS; 
    120162      } 
    121     }}} 
    122  
    123     The resulting webservice method, when using the pake task, will be `foo_Index` with parameter `test` of type `string` and return type `string`. 
    124  
    125 == Generating the .wsdl file == 
    126  
    127   * Execute the pake task, be sure the env_name is the same you used in the configuration 
    128  
    129     {{{ 
    130       symfony build-wsdl app_name env_name [controller_name] [debug] webservice_name webservice_base_url 
    131     }}} 
    132  
    133   * Clear your cache 
    134  
    135     {{{ 
    136       symfony cc 
    137     }}} 
    138  
    139   * This will add a .wsdl file to your `/web` folder, and add configuration on how to map the soap to request parameters to each `module.yml`, which exposes at least one method 
    140  
    141   * The names of the methods in the generated .wsdl file will follow the scheme: `module_Action` 
    142  
    143   * This task will also create a new controller in your `/web` folder 
    144  
    145   * Example: 
    146  
    147     {{{ 
    148       symfony build-wsdl fronted soap myFooBarService http://www.myfoobar.com/ 
    149     }}} 
    150  
    151     * This will add a `frontend_soap.php` and a `myFooBarService.wsdl` to your `/web` folder 
    152  
    153     * The endpoint for the generated service will be `http://www.myfoobar.com/frontend_soap.php` 
    154  
    155 == Notes == 
    156  
    157   * The whole view rendering part is bypassed any way, it doesn't matter if your module action returns sfView::NONE or sfView::SUCCESS, this has the advantage you can use the action easily in soap mode and normal mode (viewing via browser) without having to add additional conditions 
    158  
    159   * Complex Types are also supported by the `wsdl-build`-task, but the classes have to be in the `/lib` or `/apps/my_app/lib` folder 
    160  
    161   * You can use the symfony session features as usual 
    162  
    163   * When you are developing you might add the following line to your `php.yml` to disable caching of the .wsdl file 
    164    
    165     {{{ 
    166       set: 
    167         soap.wsdl_cache_enabled: off 
    168     }}} 
    169  
    170   * To use your own .wsdl or to use more descriptive method names, you should implement your own handler class and set the handler config parameter in your `app.yml`, see the following example: 
    171  
    172     {{{ 
    173       class mySoapHandler 
     163 
     164      /** 
     165       * A method which will not be exposed in the wsdl. 
     166       * 
     167       * @param string $test A string parameter 
     168       * 
     169       * @return string      A string 
     170       */ 
     171      public function executeBar() 
    174172      { 
    175         public function descriptiveFoo($foo, $bar) 
    176         { 
    177           return sfContext::getInstance()->getController()->invokeSoapEnabledAction('fooModule', 'index', array($foo, $bar)); 
    178         } 
     173        $this->something = "some text!"; 
    179174      } 
    180     }}} 
    181  
    182     If you have edited the `modules.yml` of your `fooModule` the mapping to request parameters will still be available, otherwise you will find them in the array returned by: 
    183  
    184     {{{ 
    185       $request->getParameter('param', 'ckWebServicePlugin'); 
    186     }}} 
    187  
    188   * Browse the source to better understand what's going on inside :) 
     175    } 
     176  }}} 
     177   
     178  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''. 
     179   
     180  '''Attention:''' 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. 
     181 
     182== Internals == 
     183 
     184  The next three sections should give a view inside the plugin. 
     185 
     186=== ckSoapHandler === 
     187 
     188  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. 
     189  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''. 
     190  If you want to use custom web service method names see section 'Custom RequestHandler'. 
     191 
     192=== ckSoapParameterFilter === 
     193 
     194  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. 
     195  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''. 
     196  The names in the configuration have to be in the same order like the function arguments.  
     197   
     198  In general a array containing all params can be retrieved by: ''$request->getParameter('param', null, 'ckWebServicePlugin');''. 
     199 
     200=== Getting the action result === 
     201 
     202  There are multiple stages of getting the action result. First we try to invoke a implementation of the ''result_callback'' configured in ''app.yml''. 
     203  If none is found on the action instance a default getter is mixed into the action and is called.  
     204   
     205  This default getter has the following behavior: 
     206  * if only one variable exists in the actions parameter holder (set via ''$actionInstance->var = 'some value';''), this variable is returned 
     207  * if a default key into the parameter holder is configured using ''soap_return_key'' in the ''module.yml'' ('''Attention:''' if this is not configured ''result'' is assumed) and this key exists its corresponding value is returned 
     208  * if both approaches fail nothing is returned  
     209 
     210  The described mechanism should be an easy to use, but powerfull way for you to get the result of an action. 
     211 
     212== Custom RequestHandler == 
     213 
     214  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''. 
     215 
     216=== Example === 
     217 
     218  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''. 
     219 
     220  {{{ 
     221  #!php 
     222    class mySoapHandler 
     223    { 
     224      public function descriptiveFooMethod($foo, $bar) 
     225      { 
     226        return sfContext::getInstance()->getController()->invokeSoapEnabledAction('fooModule', 'index', array($foo, $bar)); 
     227      } 
     228    } 
     229  }}} 
     230 
     231  If you have configured the ''module.yml'' of the ''fooModule'' in the following way: 
     232   
     233  {{{ 
     234    # your enviroment for web service mode 
     235    soap: 
     236      soap_parameter_map: 
     237        index: 
     238          - foo 
     239          - bar 
     240  }}} 
     241   
     242  parameter mapping will work like you expect it. 
    189243 
    190244== TODO == 
    191245 
    192   - decide how to handle redirects 
    193   - add a mixin method to actions, so you don't have to implement the getSoapResult in every *Actions class 
    194   - add the posibility to choose wether rendering is bypassed or not (per app / per module / per action) 
    195   - switch to symfony 1.1 (change the `build-wsdl` task, ...) 
    196   - write tests 
    197   - rewrite the wsdl generator 
    198   - enable nusoap, PEAR::SOAP as soap_server 
    199  
    200   - if anyone likes to contribute just let me know, help is welcome 
     246  * decide how to handle redirects 
     247  * add the posibility to choose wether rendering is bypassed or not (per app / per module / per action) 
     248  * switch to symfony 1.1 (change the ''build-wsdl'' task, ...) 
     249  * write tests 
     250  * rewrite the wsdl generator 
     251  * enable nusoap, PEAR::SOAP as soap_server 
     252 
     253== Contributing == 
     254 
     255  If you would like to contribute just let me know. 
    201256 
    202257== Contact == 
    203258 
    204   You may write me an email to: christian-kerl [at] web [dot] de 
     259  If you have any questions, suggestions or bug reports, write an email to: christian-kerl [at] web [dot] de