repo_zf1/documentation/manual/fr/module_specs/Zend_Soap_Server.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.soap.server">
    <title>Zend_Soap_Server</title>

    <para>
        La classe <classname>Zend_Soap_Server</classname> a été créée pour simplifier la
        création d'un service Web <acronym>SOAP</acronym> en <acronym>PHP</acronym>.
    </para>

    <para>
        Elle peut être utilisée en mode WSDL ou non-WSDL, et elle utilise des fonctions ou des
        classes pour définir le service Web rendu.
    </para>

    <para>
        Lorsque le composant <classname>Zend_Soap_Server</classname> fonctionne en mode WSDL,
        il utilise le document WSDL pour décrire le comportement des objets du serveur ainsi que les
        options de transport vers les clients.
    </para>

    <para>
        Un document WSDL peut être auto-généré en utilisant <link
        linkend="zend.soap.autodiscovery.introduction">le composant Zend_Soap_AutoDiscovery</link>,
        ou alors construit manuellement avec <link linkend="zend.soap.wsdl">la classe
        <classname>Zend_Soap_Wsdl</classname></link> ou tout autre outil de génération de <acronym>XML</acronym>
    </para>

    <para>
        Si le mode non-WSDL est utilisé, alors toutes les options du protocole doivent être
        configurées.
    </para>

    <sect2 id="zend.soap.server.constructor">
        <title>Constructeur de <classname>Zend_Soap_Server</classname></title>

        <para>
            Le constructeur de <classname>Zend_Soap_Server</classname> s'utilise différemment
            selon que l'on fonctionne en mode WSDL ou non.
        </para>

        <sect3 id="zend.soap.server.constructor.wsdl_mode">
            <title>Constructeur de <classname>Zend_Soap_Server</classname> en mode WSDL</title>

            <para>
                Le constructeur de <classname>Zend_Soap_Server</classname> prend 2 paramètres
                optionnel en mode WSDL: <orderedlist>
                        <listitem>
                        <para>
                            <varname>$wsdl</varname>, l'URI permettant l'accès au fichier WSDL
                            <footnote>
                                <para>
                                    Peut être spécifié plus tard avec la méthode
                                    <methodname>setWsdl($wsdl)</methodname>
                                </para>
                                </footnote>.
                            </para>
                    </listitem>

                    <listitem>
                        <para>
                            <varname>$options</varname> - options de création des objets serveurs
                            <footnote>
                                <para>
                                    Peut être spécifié plus tard avec la méthode
                                    <methodname>setOptions($options)</methodname>
                                </para>
                                </footnote>.
                            </para>

                        <para>
                            Les options suivantes sont reconnues en mode WSDL : <itemizedlist>
                                    <listitem>
                                    <para>
                                        "soap_version" ("soapVersion") : version du protocole <acronym>SOAP</acronym>
                                        à utiliser (SOAP_1_1 ou <acronym>SOAP</acronym>_1_2).
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>"actor" : l'URI du serveur <acronym>SOAP</acronym>.</para>
                                </listitem>

                                <listitem>
                                    <para>
                                        "classmap" ("classMap") : utilisé pour faire correspondre
                                        des types WSDL à des classes <acronym>PHP</acronym>.
                                    </para>

                                    <para>
                                        L'option doit être un tableau avec pour clés les types
                                        WSDL et pour valeur les classes <acronym>PHP</acronym> correspondantes.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        "encoding" : encodage interne des caractères (l'encodage
                                        externe est toujours UTF-8).
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        "wsdl" : équivalent à un appel à
                                        <methodname>setWsdl($wsdlValue)</methodname>
                                    </para>
                                </listitem>
                                </itemizedlist>
                            </para>
                    </listitem>
                    </orderedlist>
                </para>
        </sect3>

        <sect3 id="zend.soap.server.wsdl_mode">
            <title>Constructeur de <classname>Zend_Soap_Server</classname> en mode
            non-WSDL</title>

            <para>
                Le premier paramètre du constructeur <emphasis>doit</emphasis> être mis à la
                valeur <constant>NULL</constant> si vous voulez utiliser
                <classname>Zend_Soap_Server</classname> en mode non-WSDL.
            </para>

            <para>Vous devez aussi spécifier "uri" dans ce cas (voir juste après).</para>

            <para>
                Le second paramètre de constructeur est un tableau (<varname>$options</varname>)
                d'options permettant la création de l'objet serveur <acronym>SOAP</acronym>.<footnote>
                    <para>
                        Les options se configurent aussi plus tard, grâce à la méthode
                        <methodname>setOptions($options)</methodname>
                    </para>
                    </footnote>.
                </para>

            <para>
                Les options suivantes sont reconnues en mode non-WSDL : <itemizedlist>
                        <listitem>
                        <para>
                            "soap_version" ("soapVersion") : version <acronym>SOAP</acronym> à utiliser (SOAP_1_1
                            ou <acronym>SOAP</acronym>_1_2).
                        </para>
                    </listitem>

                    <listitem>
                        <para>"actor" : l'URI du serveur <acronym>SOAP</acronym>.</para>
                    </listitem>

                    <listitem>
                        <para>
                            "classmap" ("classMap") : utilisé pour faire correspondre des
                            types WSDL à des classes <acronym>PHP</acronym>.
                        </para>

                        <para>
                            L'option doit être un tableau avec pour clés les types WSDL et
                            pour valeur les classes <acronym>PHP</acronym> correspondantes.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            "encoding" : encodage interne des caractères (l'encodage externe
                            est toujours UTF-8).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            "wsdl" : équivalent à un appel à
                            <code>setWsdl($wsdlValue).</code>
                        </para>
                    </listitem>
                    </itemizedlist>
                </para>
        </sect3>
    </sect2>

    <sect2 id="zend.soap.server.api_define_methods">
        <title>Méthodes de définitions de l'API du service</title>

        <para>Il existe 2 manières de déclarer l'API de votre serveur <acronym>SOAP</acronym>.</para>

        <para>
            La première consiste à attacher des classes à l'objet
            <classname>Zend_Soap_Server</classname>, celles-ci devront alors décrire l'API du
            service en totalité : <programlisting language="php"><![CDATA[
...
class MyClass {
    /**
     * Cette méthode accepte ...
     *
     * @param integer $inputParam
     * @return string
     */
    public function method1($inputParam) {
        ...
    }

    /**
     * Cette méthode accepte ...
     *
     * @param integer $inputParam1
     * @param string  $inputParam2
     * @return float
     */
    public function method2($inputParam1, $inputParam2) {
        ...
    }

    ...
}
...
$server = new Zend_Soap_Server(null, $options);
// Connecte la classe au serveur Soap
$server->setClass('MyClass');
// Connecte un objet déjà initialisé au serveur Soap
$server->setObject(new MyClass());
...
$server->handle();
]]></programlisting> <note>
                    <title>Important!</title>

                <para>
                    Vous devriez complètement décrire chaque méthode grâce aux blocs de
                    commentaires PHPDoc dans le cas où vous souhaitez utiliser l'auto découverte du
                    service pour préparer le WSDL correspondant.
                </para>
                </note>
            </para>

        <para>
            La seconde manière de décrire l'API de votre service Web est d'utiliser des
            fonctions PHP conjointement avec les méthodes <methodname>addFunction()</methodname> ou
            <methodname>loadFunctions()</methodname> :<programlisting language="php"><![CDATA[
...
/**
 * Cette fonction ...
 *
 * @param integer $inputParam
 * @return string
 */
function function1($inputParam) {
    ...
}

/**
 * Cette fonction ...
 *
 * @param integer $inputParam1
 * @param string  $inputParam2
 * @return float
 */
function function2($inputParam1, $inputParam2) {
    ...
}
...
$server = new Zend_Soap_Server(null, $options);
$server->addFunction('function1');
$server->addFunction('function2');
...
$server->handle();
]]></programlisting></para>
        </sect2>

        <sect2 id="zend.soap.server.request_response">
            <title>Gestion des objets de requête et de réponse</title>

            <note>
                <title>Avancée</title>

            <para>
                Cette section décrit la gestion avancée des requêtes et réponses <acronym>SOAP</acronym> et
                pourra être évitée.
            </para>
        </note>

        <para>
            Le composant Zend_Soap_Server effectue des requêtes et récupère des réponses, ceci
            automatiquement. Il est possible d'intercepter la requête/réponse pour ajouter du pré ou
            post processus.
        </para>

        <sect3 id="zend.soap.server.request_response.request">
            <title>Requête</title>

            <para>
                La méthode <methodname>Zend_Soap_Server::handle()</methodname> utilise la
                requête depuis le flux d'entrée standard ('php://input'). Le comportement peut être
                changé en passant des paramètres à la méthode <methodname>handle()</methodname> ou en spécifiant
                sa propre requête grâce à la méthode <methodname>setRequest()</methodname> :<programlisting
                role="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
// Affecte une requête personnalisée
$server->handle($request);
...
// Affecte une requête personnalisée
$server->setRequest();
$server->handle();
]]></programlisting></para>

            <para>
                Un objet de requête peut être représenté de plusieurs manières différentes
                :<itemizedlist>
                        <listitem>
                            <para>DOMDocument (casté en <acronym>XML</acronym>)</para>
                        </listitem>

                        <listitem>
                        <para>
                            DOMNode (le DOMDocument attaché est extrait et casté en
                            <acronym>XML</acronym>)
                        </para>
                    </listitem>

                    <listitem>
                        <para>SimpleXMLElement (casté en <acronym>XML</acronym>)</para>
                    </listitem>

                    <listitem>
                        <para>
                            stdClass (__toString() est appelée et son contenu est vérifié
                            comme <acronym>XML</acronym> valide)
                        </para>
                    </listitem>

                    <listitem>
                        <para>chaînes de caractères (vérifiée comme <acronym>XML</acronym> valide)</para>
                    </listitem>
                    </itemizedlist>
                </para>

            <para>
                La dernière requête utilisée et traitée peut être récupérée en utilisant la
                méthode <methodname>getLastRequest()</methodname> :<programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
$server->handle();
$request = $server->getLastRequest();
]]></programlisting></para>
            </sect3>

            <sect3 id="zend.soap.server.request_response.response">
                <title>Réponse</title>

            <para>
                <methodname>Zend_Soap_Server::handle()</methodname> émet automatiquement la
                réponse vers le flux standard de sortie. Ce comportement peut être changé en
                utilisant <methodname>setReturnResponse()</methodname> avec une valeur <constant>TRUE</constant> ou
                <constant>FALSE</constant> en paramètre. <footnote>
                    <para>
                        L'état actuel du drapeau de retour de la réponse peut être vérifié via
                        la méthode <methodname>setReturnResponse()</methodname> sans paramètre.
                    </para>
                </footnote>. La réponse générée par <methodname>handle()</methodname> est alors retournée et
            non plus émise. <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
// Récupère la réponse plutôt que de l'émettre
$server->setReturnResponse(true);
...
$response = $server->handle();
...
]]></programlisting></para>

            <para>
                Autrement, la dernière réponse peut être récupérer avec la méthode
                <methodname>getLastResponse()</methodname> :<programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
$server->handle();
$response = $server->getLastResponse();
...
]]></programlisting></para>
            </sect3>
        </sect2>
    </sect1>