Since a SOAP http request is not as usual, you cannot use the "classic" request object. You should create a specific entry point in the www/ directory, soap.php for example. This entry point should use jSOAPRequest instead of jClassicRequest, and a specific coordinator: jSoapCoordinator. The type of the request and of the entry point is then "soap".

The entry point should then content:

require_once ('../application.init.php');

checkAppOpened();

jApp::loadConfig('soap/config.ini.php');
ini_set("soap.wsdl_cache_enabled", "0");

jClasses::inc('jsoap~jSoapCoordinator');
jClasses::inc('jsoap~jSoapRequest');

$jelix = new jSoapCoordinator();
jApp::setCoord($jelix);
$jelix->request = new jSoapRequest();
$jelix->request->initService();
$jelix->processSoap();

Don't forget to add this entry point in urls engine configuration section. If you have selected the "simple" url engine, in section simple_urlengine_entrypoints configuration file, just add:

soap = "@soap"

soap is the name of the entry point, and @soap indicate the type of the entry point.

If you have selected the significant url engine, add:

<entrypoint type="soap" name="soap" default="true" />

Independently of url engines, you retrieve an url for a soap action like this:

  $url = jUrl::get("module~action@soap");

Finally, create a configuration file in var/config/soap/config.ini.php.

As you probably saw in the entry point, some classes are used from a "jsoap" module. It is provided by Jelix. You should activate it:

  php.exe cmd.php installmodule jsoap

(see the chapter about installing a module)

This module includes also all what you need to generate WSDL content. (see below)

Since it is a specific type of request, a controller filename must be suffixed by ".soap.php". For example, for a "default" controller: default.soap.php. (it can co-exists with a “default” classic controller such as “default.classic.php”).

Method of a soap controller ¶

class defaultCtrl extends jController {

    /** 
     * Test with a simple parameter
     * @param string $name
     * @return string
     */
    function hello() {
        $resp = $this->getResponse('soap');
        $resp->data = "Hello ".$this->param('name');
        return $resp;
    }
}

    @param string $myparameter

    @param string[] $array_of_string

    @param string[=>] $array_of_string

/**
 * Struct used for tests
 */
class MyTestStruct{
    /**
     * @var string
     */
    public $name = 'Dupont';

    /**
     * @var string
     */
    public $firstName = 'Bertrand';

    /**
     * @var string
     */
    public $city = 'Paris';
}

    /** 
     * for this method, we receive a MyTestStruct and return a MyTestStruct object
     * @param MyTestStruct $input
     * @return MyTestStruct
     */
    function receiveObject() {
        $resp = $this->getResponse('soap');
        $input = $this->param('input');
        $input->name = 'Name updated';
        $resp->data = $input;
        return $resp;
    }

/**
 * An other struct used for test, this one have an other object as member propertie
 */
class MyTestStructBis {

    /**
     * @var MyTestStruct
     */
    public $test;

    /**
     * @var string
     */
    public $msg = 'hello';

    function __construct(){
        $this->test = new MyTestStruct();
    }
}

When you use the SOAP protocol, you should provide some WSDL files, which allows SOAP clients to know what are available SOAP methods.

The jsoap module provides features to generate WSDL. It contains a controller named "WSDL" with a wsdl() method. So, just indicate the url of this action to your soap client:

   http://mysite.com/index.php/jsoap/WSDL/wsdl?service=aModule~aController

or with the "simple" url engine:

   http://mysite.com/index.php?module=jsoap&action=WSDL:wsdl&service=aModule~aController

Note that you should give a "service" parameter indicating the controller which contains the web services. You can have more than one soap controller, but there is no way to return automatically a WSDL file for all soap web services implemented in your application.

You can display a HTML version of the list of SOAP services, by calling the index() method of the WSDL controller:

  http://mysite.com/index.php/jsoap/WSDL?service=aModule~aController

The application which calls your SOAP web services can be a PHP client, a javascript client etc.. Here is an example of a call with a PHP script.

        ini_set('soap.wsdl_cache_enabled', 0);

        // load the WSDL content
        try {
            $wsdlURI = "http://monsite.com/index.php/jsoap/WSDL/wsdl?service=myapp~default";
            $client = new SoapClient($wsdlURI, array('trace' => 1, 'soap_version'  => SOAP_1_1));
        } catch (SoapFault $fault) {
            throw new Exception($fault->getMessage());
        }

        try {
            $result =  $client->__soapCall('hello', array('Sylvain'));
            //...

            $result =  $client->__soapCall('returnObjects', array());
            //...

            $result =  $client->__soapCall('returnObjectBis', array());
            // ...

        } catch (SoapFault $fault) {
            print_r($fault);
            throw new Exception($fault->getMessage());
        }

If your jelix application needs to call soap servers, you can use jSoapClient. It is a class to retrieve a native SoapClient object, automatically configured with some parameters stored in a var/config/profiles.ini.php, like for jDb.

To use it, add sections in var/config/profiles.ini.php. Sections are profiles for connections. options in [jsoapclient] are aliases for profiles. Profiles are stored in section named [jsoapclient:myname] where myname is a name you choose freely. default name indicate the default profile. A profile should contain at least a wsdl option, containing the URL to a WSDL file. You can add other options, corresponding to parameters for the native class SoapClient of PHP.

[jsoapclient]

[jsoapclient:default]
wsdl= "http://example.com/books.wsdl"
soap_version = SOAP_1_1

And then, in your code:

        $client = jSoapClient::get(); // give a profile name if different from 'default'
        $result = $client->hello('Sylvain');
        // or
        $result =  $client->__soapCall('hello', array('Sylvain'));

You can indicate the option classmap in the profile, to map some classes on soap types. You have to use the json format to indicate the mapping.

[jsoapclient:default]
wsdl= "http://example.com/books.wsdl"
soap_version = SOAP_1_1
classmap = '{"soaptype":"myclass", "soaptype2":"myclass2"}'

The classes you indicate should be loaded before calling jSoapClient::get().

Since Jelix 1.5, you can declare this mapping into a separate ini file. You should indicate this file into a classmap_file property in the profile.

[jsoapclient:default]
wsdl= "http://example.com/books.wsdl"
soap_version = SOAP_1_1
classmap_file = soap_classmap.ini.php

In the ini file, you should have section corresponding with declared profiles, with the same name (without the "jsoapclient:" prefix). In these sections, you have list of "key=value". Keys are soap types, values are class names.

[default]
soaptype=myclass
soaptype2=myclass2

You can also declare a __common__ section, containing mapping applicable for all jsoapclient profiles.

So, the classmap of a profile, contains the classmap of __common__, the classmap of the section corresponding to the profile, and the classmap declared into the profile in the "classmap" property.

Other configuration options:

1. trace=on: to activate debugging. In a log file of type "soap", you'll have all SOAP requests and responses. You should configure the logger correctly. Example:

[logger]
soap=file

[fileLogger]
soap=soap.log

Since Jelix 1.6.16, you can also use the soapfile logger instead of file. This logger stores xml content of requests and responses in separate files to ease debugging.

1. exceptions: it's a boolean indicating if SOAP error should generate SoapFault exceptions.
2. connection_timeout: time in secondes to wait after a response, before generating an error
3. ssl_self_signed (since 1.6.15) : if "on", there will not error when the SSL certificat of the SOAP server cannot be verified. You should not activate it on distant SOAP servers.