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

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

    <note>
        <para>
            La classe <classname>Zend_Soap_Wsdl</classname> est utilisée par le composant
            Zend_Soap_Server pour manipuler des documents WSDL. Néanmoins, vous pouvez vous-même
            utiliser les services fournis par cette classe pour vos propres besoins. La classe
            Zend_Soap_Wsdl contient à la fois un analyseur et un constructeur de documents
            WSDL.
        </para>

        <para>
            Si vous ne voulez pas l'utiliser pour vos propres besoins, vous pouvez alors
            passer cette section de la documentation.
        </para>
    </note>

    <sect2 id="zend.soap.wsdl.constructor">
        <title>Constructeur Zend_Soap_Wsdl</title>

        <para>
            Le constructeur de <classname>Zend_Soap_Wsdl</classname> prend 3 paramètres :
            <orderedlist>
                    <listitem>
                        <simpara><varname>$name</varname> - nom du service Web décrit.</simpara>
                    </listitem>

                    <listitem>
                        <simpara><varname>$uri</varname> - <acronym>URI</acronym> d'accès au fichier WSDL. (Une référence
                        dans le système de fichier local est possible.)</simpara>
                    </listitem>

                    <listitem>
                        <simpara><varname>$strategy</varname> - identifiant optionnel pour identifier la
                        détection de stratégie des types complexes. Ceci est un booléen
                        <varname>$extractComplexTypes</varname> avant la version 1.7 et peut toujours être
                        paramétrer via un booléen pour la compatibilité ascendante. Par défaut le
                        comportement de détection de la 1.6 est activé. Pour avoir de plus amples
                        informations concernant les stratégies de détection des types complexes,
                        lisez : <link linkend="zend.soap.wsdl.types.add_complex">ajoutez des types
                        complexes</link>.</simpara>
                    </listitem>
                </orderedlist>
            </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.addmessage">
        <title>addMessage()</title>

        <para>
            <methodname>addMessage($name, $parts)</methodname> ajoute un message de description au
            document WSDL (/definitions/message de l'élément).
        </para>

        <para>
            Chaque message correspond à une méthode en terme de fonctionnalité de
            <classname>Zend_Soap_Server</classname> et
            <classname>Zend_Soap_Client</classname>.
        </para>

        <para>Le paramètre <varname>$name</varname> représente le nom du message.</para>

        <para>
            Le paramètre <varname>$parts</varname> est un tableau de paramètre des messages
            décrivant les paramètres d'appel <acronym>SOAP</acronym>. Le tableau est associatif: 'nom du paramètre'
            (nom du paramètre d'appel <acronym>SOAP</acronym>) =&gt; 'type du paramètre'.
        </para>

        <para>
            La correspondance de types est effectuée grâce à <methodname>addTypes()</methodname> et
            <methodname>addComplexType()</methodname>(voyez après).
        </para>

        <note>
            <para>
                Les paramètres de messages peuvent être soit "element", soit "type" (voyez
                <ulink url="http://www.w3.org/TR/wsdl#_messages"></ulink>).
            </para>

            <para>
                "element" doit correspondre à un élément de définition de type. "type"
                correspond à une entrée complexType.
            </para>

            <para>
                Tous les types standards XSD possèdent une définition "element" et
                "complexType" (Voyez <ulink
                url="http://schemas.xmlsoap.org/soap/encoding/"></ulink>).
            </para>

            <para>
                Tous les éléments non standards, qui doivent être ajoutés avec la méthode
                <methodname>Zend_Soap_Wsdl::addComplexType()</methodname>, sont décrits en utilisant
                un noeud "complexType" décrits dans la section "/definitions/types/schema/" du
                document WSDL.
            </para>

            <para>
                Ainsi, la méthode <methodname>addMessage()</methodname> utilise toujours un attribut
                "type" pour décrire des types.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_port_type">
        <title><methodname>addPortType()</methodname></title>

        <para>
            <methodname>addPortType($name)</methodname> ajoute un nouveau type de portage au document WSDL
            (/definitions/portType).
        </para>

        <para>
            Ceci fait la jointure entre des méthodes du service décrites en tant
            qu'implémentations de Zend_Soap_Server.
        </para>

        <para>
            Voyez <ulink url="http://www.w3.org/TR/wsdl#_porttypes"></ulink> pour plus de
            détails.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_port_operation">
        <title><methodname>addPortOperation()</methodname></title>

        <para>
            <code>addPortOperation($portType, $name, $input = false, $output = false, $fault =
            false)</code> ajoute des définitions de portage au portage défini dans le document WSDL
            (/definitions/portType/operation).
        </para>

        <para>
            Chaque opération de portage correspond à une méthode de classe (si le Web Service
            est basé sur une classe) ou à une fonction (si le Web Service est basé sur des
            fonctions), ceci en terme d'implémentation de Zend_Soap_Server.
        </para>

        <para>
            Cette méthode ajoute aussi les messages d'opération correspondants aux portages,
            ceci dépend des paramètres <varname>$input</varname>, <varname>$output</varname> and
            <varname>$fault</varname>. <note>
                <para>
                    Zend_Soap_Server génère 2 messages pour chaque opération de portage
                    lorsque le service est décrit au travers de la classe
                    <classname>Zend_Soap_Server</classname>: <itemizedlist>
                            <listitem>
                            <para>
                                Le message d'entrée nommé <code>$methodName .
                                'Request'</code>.
                            </para>
                        </listitem>

                        <listitem>
                            <para>
                                Les message de sortie nommé <code>$methodName .
                                'Response'</code>.
                            </para>
                        </listitem>
                        </itemizedlist>
                    </para>
                </note>
            </para>

        <para>
            Voyez <ulink url="http://www.w3.org/TR/wsdl#_request-response"></ulink> pour les
            détails.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_binding">
        <title><methodname>addBinding()</methodname></title>

        <para>
            <methodname>addBinding($name, $portType)</methodname> ajoute de nouvelles correspondances
            (bindings) au document WSDL (/definitions/binding).
        </para>

        <para>
            Le noeud du document WSDL "binding" définit le format du message et les détails du
            protocole pour les opérations et messages définis par un portage "portType" particulier
            (voyez <ulink url="http://www.w3.org/TR/wsdl#_bindings"></ulink>).
        </para>

        <para>
            La méthode crée le noeud de correspondance et le retourne. Il peut alors être
            utilisé.
        </para>

        <para>
            L'implémentation de Zend_Soap_Server utilise le nom <code>$serviceName .
            "Binding"</code> pour la correspondance ("binding") de l'élément du document
            WSDL.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_binding_operation">
        <title><methodname>addBindingOperation()</methodname></title>

        <para>
            <code>addBindingOperation($binding, $name, $input = false, $output = false, $fault
            = false)</code> ajoute une opération à l'élément de correspondance avec le nom spécifié
            (/definitions/binding/operation).
        </para>

        <para>
            Cette méthode prend un objet <code>XML_Tree_Node</code> tel que retourné par
            <methodname>addBinding()</methodname>, en paramètre (<varname>$binding</varname>) pour ajouter un élément
            "operation" avec des entrées input/output/false dépendantes des paramètres
            spécifiés.
        </para>

        <para>
            <classname>Zend_Soap_Server</classname> ajoute les correspondances pour chaque
            méthode du Web Service avec des entrées et sorties, définissant l'élément "soap:body"
            comme <code>&lt;soap:body use="encoded"
            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt;</code>
        </para>

        <para>
            Voyez les détails à <ulink
            url="http://www.w3.org/TR/wsdl#_bindings"></ulink>.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_soap_binding">
        <title><methodname>addSoapBinding()</methodname></title>

        <para>
            <code>addSoapBinding($binding, $style = 'document', $transport =
            'http://schemas.xmlsoap.org/soap/http')</code> ajoute des correspondances (bindings)
            <acronym>SOAP</acronym> ("soap:binding") à l'élément (déjà lié à un portage de type) avec le style et le
            transport spécifié (<classname>Zend_Soap_Server</classname> utilise le style RPC sur
            <acronym>HTTP</acronym>).
        </para>

        <para>
            L'élément "/definitions/binding/soap:binding" est alors utilisé pour spécifier que
            la correspondance est relative au format du protocole <acronym>SOAP</acronym>.
        </para>

        <para>
            Voyez <ulink url="http://www.w3.org/TR/wsdl#_bindings"></ulink> pour les
            détails.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_soap_operation">
        <title><methodname>addSoapOperation()</methodname></title>

        <para>
            <methodname>addSoapOperation($binding, $soap_action)</methodname> ajoute une opération <acronym>SOAP</acronym>
            ("soap:operation") à l'élément de correspondance avec l'action spécifiée. L'attribut
            "style" de l'élément "soap:operation" n'est pas utilisé alors que le modèle de
            programmation (RPC-oriented ou document-oriented) devrait utiliser la méthode
            <methodname>addSoapBinding()</methodname>
        </para>

        <para>
            L'attribut "soapAction" de l'élément "/definitions/binding/soap:operation"
            spécifie la valeur de l'en-tête <acronym>SOAP</acronym>Action pour l'opération. Cet attribut est requis
            pour <acronym>SOAP</acronym> sur <acronym>HTTP</acronym> et <emphasis>ne doit pas</emphasis> être renseigné pour les autres
            modes de transports.
        </para>

        <para>
            <classname>Zend_Soap_Server</classname> utilise <code>$serviceUri . '#' .
            $methodName</code> pour le nom de l'action <acronym>SOAP</acronym>.
        </para>

        <para>
            Voyez <ulink url="http://www.w3.org/TR/wsdl#_soap:operation"></ulink> pour plus de
            détails.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_service">
        <title><methodname>addService()</methodname></title>

        <para>
            <methodname>addService($name, $port_name, $binding, $location)</methodname> ajoute un élément
            "/definitions/service" au document WSDL avec le nom du Web Service spécifié, le nom du
            portage, la correspondance, et l'adresse.
        </para>

        <para>
            WSDL 1.1 autorise d'avoir plusieurs types de portage par service. Cette
            particularité n'est pas utilisée dans <classname>Zend_Soap_Server</classname> et est non
            supportée par la classe <classname>Zend_Soap_Wsdl</classname>.
        </para>

        <para>
            Utilisations de <classname>Zend_Soap_Server</classname> : <itemizedlist>
                    <listitem>
                        <para><code>$name . 'Service'</code> comme nom du Web Service,</para>
                    </listitem>

                    <listitem>
                        <para><code>$name . 'Port'</code> comme nom de portage des types,</para>
                    </listitem>

                    <listitem>
                    <para>
                        <code>'tns:' . $name . 'Binding'</code> <footnote>
                            <para>
                                <code>'tns:' namespace</code> est l'URI du script
                                (<code>'http://' .$_SERVER['HTTP_HOST'] .
                                $_SERVER['SCRIPT_NAME']</code>).
                            </para>
                            </footnote> comme nom de la correspondance,
                        </para>
                </listitem>

                <listitem>
                    <para>
                        l'URI du script<footnote>
                            <para>
                                <code>'http://' .$_SERVER['HTTP_HOST'] .
                                $_SERVER['SCRIPT_NAME']</code>
                            </para>
                        </footnote> en tant qu'URI du service pour les Web Service utilisant des
                        classes.
                    </para>
                </listitem>
            </itemizedlist> où <varname>$name</varname> est un nom de classe pour le Web Service
        utilisant des classes, ou un nom de script pour le Web Service qui utilise des
            fonctions.
        </para>

        <para>
            Voyez <ulink url="http://www.w3.org/TR/wsdl#_services"></ulink> pour les
            détails.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.types">
        <title>Correspondance de type</title>

        <para>
            Le WSDL de Zend_Soap utilise les correspondances suivantes pour faire correspondre
            les type <acronym>SOAP</acronym> à des types <acronym>PHP</acronym> : <itemizedlist>
                    <listitem>
                        <para>chaînes <acronym>PHP</acronym> &lt;-&gt; <code>xsd:string</code>.</para>
                    </listitem>

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

                    <listitem>
                        <para>flottants <acronym>PHP</acronym> &lt;-&gt; <code>xsd:float</code>.</para>
                    </listitem>

                    <listitem>
                        <para>booléens <acronym>PHP</acronym> &lt;-&gt; <code>xsd:boolean</code>.</para>
                    </listitem>

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

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

                    <listitem>
                    <para>
                        Classe <acronym>PHP</acronym> &lt;-&gt; basé sur la stratégie des types complexes (Voir :
                        <link linkend="zend.soap.wsdl.types.add_complex">cette section</link>)<footnote>
                            <para>
                                <classname>Zend_Soap_AutoDiscover</classname> sera créé avec
                                la classe
                                <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> en
                                tant qu'algorithme de détection pour les types complexes. Le premier
                                paramètre du constructeur AutoDiscover accepte toute stratégie de
                                types complexes implémentant
                                <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> ou une
                                chaîne correspondant au nom de la classe. Pour une compatibilité
                                ascendante, avec <varname>$extractComplexType</varname> les variables
                                booléennes sont analysées comme avec Zend_Soap_Wsdl. Regardez le
                                manuel <link
                                linkend="zend.soap.wsdl.types.add_complex">Zend_Soap_Wsdl sur
                                l'ajout des types complexes</link> pour plus d'informations.
                            </para>
                            </footnote>.
                        </para>
                </listitem>

                <listitem>
                    <para>Type <acronym>PHP</acronym> vide &lt;-&gt; void.</para>
                </listitem>

                <listitem>
                    <para>
                        Si le type na aucune correspondance avec les valeurs ci-dessus, alors
                        <code>xsd:anyType</code> est utilisé.
                    </para>
                </listitem>
            </itemizedlist> Où <code>xsd:</code> est l'espace de noms
        "http://www.w3.org/2001/XMLSchema", <code>soap-enc:</code> est l'espace de noms
        "http://schemas.xmlsoap.org/soap/encoding/", <code>tns:</code> est un "espace de noms
            cible" pour le service.
        </para>

        <sect3 id="zend.soap.wsdl.types.retrieve">
            <title>Récupérer des infos sur les types</title>

            <para>
                <methodname>getType($type)</methodname> peut être utilisée pour récupérer la
                correspondance d'un type PHP spécifié : <programlisting language="php"><![CDATA[
...
$wsdl = new Zend_Soap_Wsdl('My_Web_Service', $myWebServiceUri);

...
$soapIntType = $wsdl->getType('int');

...
class MyClass {
    ...
}
...
$soapMyClassType = $wsdl->getType('MyClass');
]]></programlisting></para>
            </sect3>

            <sect3 id="zend.soap.wsdl.types.add_complex">
                <title>Ajouter des infos sur les types complexes</title>

            <para>
                <methodname>addComplexType($type)</methodname> est utilisée pour ajouter des types
                complexes (classes <acronym>PHP</acronym>) à un document WSDL.
            </para>

            <para>
                C'est automatiquement utilisé par la méthode <methodname>getType()</methodname> pour
                ajouter les types complexes des paramètres de méthodes ou des types
                retournés.
            </para>

            <para>
                Sa détection et son algorithme de construction est basé sur la détection de
                stratégie des types complexes couramment active. Vous pouvez paramétrer la stratégie
                de détection soit en spécifiant le nom de classe sous la forme d'une chaîne de
                caractères ou une instance implémentant
                <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> en tant que troisième
                paramètre du constructeur ou en utilisant la fonction
                <methodname>setComplexTypeStrategy($strategy)</methodname> de
                <classname>Zend_Soap_Wsdl</classname>. Les stratégies de détection suivantes
                existent couramment :
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        la classe
                        <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> : activé
                        par défaut (quand aucun troisième paramètre n'est fourni). Itère parmi les
                        attributs publics d'un type de classe et les enregistre en tant que
                        sous-types d'un type d'objet complexe.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        la classe <classname>Zend_Soap_Wsdl_Strategy_AnyType</classname> :
                        caste tous les types complexes en un type XSD simple xsd:anyType. Attention
                        ce raccourci pour la détection des types complexes peut probablement
                        seulement être géré avec des langages faiblement typés comme le <acronym>PHP</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        la classe
                        <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence</classname> : cette
                        stratégie permet de spécifier les paramètres de retour de type :
                        <code>int[]</code> ou <code>string[]</code>. A partir de Zend Framework 1.9,
                        il peut gérer des types <acronym>PHP</acronym> simples comme int, string, boolean, float ainsi
                        que des objets ou des tableaux d'objets.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        la classe
                        <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeComplex</classname> : cette
                        stratégie permet de détecter des tableaux complexes d'objets. Les types
                        d'objets sont détectés sur la base de
                        <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> et un
                        tableau enveloppe cette définition.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        la classe <classname>Zend_Soap_Wsdl_Strategy_Composite</classname> :
                        cette stratégie peut combiner toutes les stratégies en connectant les types
                        complexes <acronym>PHP</acronym> (nom de classe) à la stratégie désirée grâce à la méthode
                        <methodname>connectTypeToStrategy($type, $strategy)</methodname>. Une carte de
                        correspondance complète de types peut être fourni au constructeur sous la
                        forme d'un tableau de paires <varname>$type</varname> -&gt;
                        <varname>$strategy</varname>. Le second paramètre spécifie la stratégie par défaut
                        si un type inconnu est ajouté. La valeur par défaut de ce paramètre est la
                        stratégie
                        <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                la méthode <methodname>addComplexType()</methodname> crée un élément
                "<code>/definitions/types/xsd:schema/xsd:complexType</code>" pour chaque type
                complexe décrit avec le nom d'une classe <acronym>PHP</acronym> spécifiée.
            </para>

            <para>
                Les propriétés des classes <emphasis>doivent</emphasis> posséder un bloc de
                documentation avec le type <acronym>PHP</acronym> en question, afin que la propriété soit incluse dans
                la description WSDL.
            </para>

            <para>
                <methodname>addComplexType()</methodname> vérifie sur le type est déjà décrit dans la
                section des types du document WSDL.
            </para>

            <para>
                Ceci évite les duplications et récursions si cette méthode est appelée plus
                d'une fois.
            </para>

            <para>
                Voyez <ulink url="http://www.w3.org/TR/wsdl#_types"></ulink> pour plus de
                détails.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_documentation">
        <title><methodname>addDocumentation()</methodname></title>

        <para>
            <methodname>addDocumentation($input_node, $documentation)</methodname> ajoute de la
            documentation lisible ("human readable") grâce à l'élément optionnel
            "wsdl:document".
        </para>

        <para>
            L'élément "/definitions/binding/soap:binding" est utilisé pour dire que la
            correspondance est liée au format du protocole <acronym>SOAP</acronym>.
        </para>

        <para>
            Voyez <ulink url="http://www.w3.org/TR/wsdl#_documentation"></ulink> pour les
            détails.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.retrieve">
        <title>Récupérer un document WSDL finalisé</title>

        <para>
            <methodname>toXML()</methodname>, <methodname>toDomDocument()</methodname> et <code>dump($filename =
            false)</code> peuvent être utilisées pour récupérer un document WSDL sous forme de <acronym>XML</acronym>,
            de structure DOM, ou de fichier.
        </para>
    </sect2>
</sect1>