repo_zf1/documentation/manual/en/module_specs/Zend_Soap_AutoDiscovery.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.soap.autodiscovery">
    <title>AutoDiscovery</title>

    <sect2 id="zend.soap.autodiscovery.introduction">
        <title>AutoDiscovery Introduction</title>

        <para>
            <acronym>SOAP</acronym> functionality implemented within Zend Framework is intended to
            make all steps required for <acronym>SOAP</acronym> communications more simple.
        </para>

        <para>
            <acronym>SOAP</acronym> is language independent protocol. So it may be used not only for
            <acronym>PHP</acronym>-to-PHP communications.
        </para>

        <para>
            There are three configurations for <acronym>SOAP</acronym> applications where Zend
            Framework may be utilized:

            <orderedlist>
                <listitem>
                    <simpara>
                        SOAP server <acronym>PHP</acronym> application &lt;---&gt;
                        <acronym>SOAP</acronym> client <acronym>PHP</acronym> application
                    </simpara>
                </listitem>

                <listitem>
                    <simpara>
                        SOAP server non-PHP application &lt;---&gt; <acronym>SOAP</acronym>
                        client <acronym>PHP</acronym> application
                    </simpara>
                </listitem>

                <listitem>
                    <simpara>
                        SOAP server <acronym>PHP</acronym> application &lt;---&gt;
                        <acronym>SOAP</acronym> client non-PHP application
                    </simpara>
                </listitem>
            </orderedlist>
        </para>

        <para>
            We always have to know, which functionality is provided by <acronym>SOAP</acronym>
            server to operate with it. <ulink url="http://www.w3.org/TR/wsdl">WSDL</ulink> is used
            to describe network service <acronym>API</acronym> in details.
        </para>

        <para>
            WSDL language is complex enough (see <ulink
                url="http://www.w3.org/TR/wsdl">http://www.w3.org/TR/wsdl</ulink>
            for the details). So it's difficult to prepare correct WSDL description.
        </para>

        <para>
            Another problem is synchronizing changes in network service <acronym>API</acronym> with
            already existing WSDL.
        </para>

        <para>
            Both these problem may be solved by WSDL autogeneration. A prerequisite for this is a
            <acronym>SOAP</acronym> server autodiscovery. It constructs object similar to object
            used in <acronym>SOAP</acronym> server application, extracts necessary information and
            generates correct WSDL using this information.
        </para>

        <para>
            There are two ways for using Zend Framework for <acronym>SOAP</acronym> server
            application:

            <itemizedlist>
                <listitem>
                    <para>Use separated class.</para>
                </listitem>

                <listitem>
                    <para>Use set of functions</para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Both methods are supported by Zend Framework Autodiscovery functionality.
        </para>

        <para>
            The<classname>Zend_Soap_AutoDiscover</classname> class also supports datatypes mapping
            from <acronym>PHP</acronym> to <ulink
                url="http://www.w3.org/TR/xmlschema-2/">XSD types</ulink>.
        </para>

        <para>
            Here is an example of common usage of the autodiscovery functionality. The
            <methodname>handle()</methodname> function generates the WSDL file and posts it to the
            browser.
        </para>

        <programlisting language="php"><![CDATA[
class My_SoapServer_Class {
...
}

$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->setClass('My_SoapServer_Class');
$autodiscover->handle();
]]></programlisting>

        <para>
            If you need access to the generated WSDL file either to save it to a file or as an
            <acronym>XML</acronym> string you can use the <methodname>dump($filename)</methodname>
            or <methodname>toXml()</methodname> functions the AutoDiscover class provides.
        </para>

        <note id="zend.soap.autodiscovery.introduction.noserver">
            <title>Zend_Soap_Autodiscover is not a Soap Server</title>

            <para>
                It is very important to note, that the class
                <classname>Zend_Soap_AutoDiscover</classname> does not act as a
                <acronym>SOAP</acronym> Server on its own. It only generates the WSDL and serves it
                to anyone accessing the url it is listening on.
            </para>

            <para>
                As the <acronym>SOAP</acronym> Endpoint Uri is uses the default
                <code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code>, but this
                can be changed with the <methodname>setUri()</methodname> function or the
                Constructor parameter of <classname>Zend_Soap_AutoDiscover</classname> class. The
                endpoint has to provide a <classname>Zend_Soap_Server</classname> that listens to
                requests.
            </para>

            <programlisting language="php"><![CDATA[
if(isset($_GET['wsdl'])) {
    $autodiscover = new Zend_Soap_AutoDiscover();
    $autodiscover->setClass('HelloWorldService');
    $autodiscover->handle();
} else {
    // pointing to the current file here
    $soap = new Zend_Soap_Server("http://example.com/soap.php?wsdl");
    $soap->setClass('HelloWorldService');
    $soap->handle();
}
]]></programlisting>
        </note>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.class">
        <title>Class autodiscovering</title>

        <para>
            If class is used to provide SOAP server functionality, then the same class should be
            provided to <classname>Zend_Soap_AutoDiscover</classname> for WSDL generation:
        </para>

        <programlisting language="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->setClass('My_SoapServer_Class');
$autodiscover->handle();
]]></programlisting>

        <para>
            The following rules are used while WSDL generation:

            <itemizedlist>
                <listitem>
                    <para>Generated WSDL describes an RPC style Web Service.</para>
                </listitem>

                <listitem>
                    <para>Class name is used as a name of the Web Service being described.</para>
                </listitem>

                <listitem>
                    <para>
                        <code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code> is
                        used as an <acronym>URI</acronym> where the WSDL is available by default but
                        can be overwritten via <methodname>setUri()</methodname> method.
                    </para>

                    <para>
                         It's also used as a target namespace for all service related names
                         (including described complex types).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Class methods are joined into one <ulink
                            url="http://www.w3.org/TR/wsdl#_porttypes">Port Type</ulink>.
                    </para>

                    <para>
                        <code>$className . 'Port'</code> is used as Port Type name.
                    </para>
                </listitem>

                <listitem>
                    <para>Each class method is registered as a corresponding port operation.</para>
                </listitem>

                <listitem>
                    <para>
                        Each method prototype generates corresponding Request/Response messages.
                    </para>

                    <para>
                        Method may have several prototypes if some method parameters are optional.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <note>
            <title>Important!</title>

            <para>
                WSDL autodiscovery utilizes the <acronym>PHP</acronym> docblocks provided by the
                developer to determine the parameter and return types. In fact, for scalar types,
                this is the only way to determine the parameter types, and for return types, this is
                the only way to determine them.
            </para>

            <para>
                That means, providing correct and fully detailed docblocks is not only best
                practice, but is required for discovered class.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.functions">
        <title>Functions autodiscovering</title>

        <para>
            If set of functions are used to provide SOAP server functionality, then the same set
            should be provided to <classname>Zend_Soap_AutoDiscovery</classname> for WSDL
            generation:
        </para>

        <programlisting language="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->addFunction('function1');
$autodiscover->addFunction('function2');
$autodiscover->addFunction('function3');
...
$autodiscover->handle();
]]></programlisting>

        <para>
            The following rules are used while WSDL generation:

            <itemizedlist>
                <listitem>
                    <para>Generated WSDL describes an RPC style Web Service.</para>
                </listitem>

                <listitem>
                    <para>
                        Current script name is used as a name of the Web Service being described.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code> is
                        used as an <acronym>URI</acronym> where the WSDL is available.
                    </para>

                    <para>
                         It's also used as a target namespace for all service related names
                         (including described complex types).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Functions are joined into one <ulink
                            url="http://www.w3.org/TR/wsdl#_porttypes">Port Type</ulink>.
                    </para>

                    <para>
                        <code>$functionName . 'Port'</code> is used as Port Type name.
                    </para>
                </listitem>

                <listitem>
                    <para>Each function is registered as a corresponding port operation.</para>
                </listitem>

                <listitem>
                    <para>
                        Each function prototype generates corresponding Request/Response messages.
                    </para>

                    <para>
                        Function may have several prototypes if some method parameters are optional.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <note>
            <title>Important!</title>

            <para>
                WSDL autodiscovery utilizes the <acronym>PHP</acronym> docblocks provided by the
                developer to determine the parameter and return types. In fact, for scalar types,
                this is the only way to determine the parameter types, and for return types, this is
                the only way to determine them.
            </para>

            <para>
                That means, providing correct and fully detailed docblocks is not only best
                practice, but is required for discovered class.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.datatypes">
        <title>Autodiscovering Datatypes</title>

        <para>
            Input/output datatypes are converted into network service types using the following
            mapping:

            <itemizedlist>
                <listitem>
                    <para>PHP strings &lt;-&gt; <code>xsd:string</code>.</para>
                </listitem>

                <listitem>
                    <para>PHP integers &lt;-&gt; <code>xsd:int</code>.</para>
                </listitem>

                <listitem>
                    <para>PHP floats and doubles &lt;-&gt; <code>xsd:float</code>.</para>
                </listitem>

                <listitem>
                    <para>PHP booleans &lt;-&gt; <code>xsd:boolean</code>.</para>
                </listitem>

                <listitem>
                    <para>PHP arrays &lt;-&gt; <code>soap-enc:Array</code>.</para>
                </listitem>

                <listitem>
                    <para>PHP object &lt;-&gt; <code>xsd:struct</code>.</para>
                </listitem>

                <listitem>
                    <para>
                        <acronym>PHP</acronym> class &lt;-&gt; based on complex type strategy (See:
                        <link linkend="zend.soap.wsdl.types.add_complex">this section</link>)

                        <footnote>
                            <para>
                                <classname>Zend_Soap_AutoDiscover</classname> will be created with
                                the
                                <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>
                                class as detection algorithm for complex types. The first parameter
                                of the AutoDiscover constructor takes any complex type strategy
                                implementing
                                <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> or a string
                                with the name of the class. For backwards compatibility with
                                <varname>$extractComplexType</varname> boolean variables are parsed
                                exactly like in <classname>Zend_Soap_Wsdl</classname>. See the
                                <link
                                    linkend="zend.soap.wsdl.types.add_complex"><classname>Zend_Soap_Wsdl</classname>
                                    manual on adding complex</link> types for more information.
                            </para>
                        </footnote>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        type[] or object[] (ie. int[]) &lt;-&gt; based on complex type strategy
                    </para>
                </listitem>

                <listitem>
                    <para>PHP void &lt;-&gt; empty type.</para>
                </listitem>

                <listitem>
                    <para>
                        If type is not matched to any of these types by some reason, then
                        <code>xsd:anyType</code> is used.
                    </para>
                </listitem>
            </itemizedlist>

            Where <code>xsd:</code> is "http://www.w3.org/2001/XMLSchema" namespace,
            <code>soap-enc:</code> is a "http://schemas.xmlsoap.org/soap/encoding/" namespace,
            <code>tns:</code> is a "target namespace" for a service.
        </para>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.wsdlstyles">
        <title>WSDL Binding Styles</title>

        <para>
            WSDL offers different transport mechanisms and styles. This affects the
            <code>soap:binding</code> and <code>soap:body</code> tags within the Binding
            section of WSDL. Different clients have different requirements as to what options
            really work. Therefore you can set the styles before you call any <code>setClass</code>
            or <code>addFunction</code> method on the AutoDiscover class.
        </para>

        <programlisting language="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
// Default is 'use' => 'encoded' and
// 'encodingStyle' => 'http://schemas.xmlsoap.org/soap/encoding/'
$autodiscover->setOperationBodyStyle(
                    array('use' => 'literal',
                          'namespace' => 'http://framework.zend.com')
                );

// Default is 'style' => 'rpc' and
// 'transport' => 'http://schemas.xmlsoap.org/soap/http'
$autodiscover->setBindingStyle(
                    array('style' => 'document',
                          'transport' => 'http://framework.zend.com')
                );
...
$autodiscover->addFunction('myfunc1');
$autodiscover->handle();
]]></programlisting>
    </sect2>
</sect1>