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

<!-- EN-Revision: 13768 -->
<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 <classname>Zend_Soap_Wsdl</classname></title>

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

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

                <listitem>
                    <simpara><code>$strategy</code> - identifiant optionnel pour identifier la détection de stratégie
                    des types complexes. Ceci est un booléen <code>$extractComplexTypes</code> 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 : <xref
                    linkend="zend.soap.wsdl.types.add_complex" />.</simpara>
                </listitem>
            </orderedlist></para>
    </sect2>

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

        <para><code>addMessage($name, $parts)</code> 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 <code>$name</code> représente le nom du message.</para>

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

        <para>La correspondance de types est effectuée grâce à <code>addTypes()</code> et
        <code>addComplexType()</code>(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
            <classname>Zend_Soap_Wsdl::addComplexType()</classname>, 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 <code>addMessage()</code> utilise toujours un attribut "type" pour décrire des
            types.</para>
        </note>
    </sect2>

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

        <para><code>addPortType($name)</code> 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><code>addPortOperation()</code></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 <code>$input</code>, <code>$output</code> and <code>$fault</code>. <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><code>addBinding()</code></title>

        <para><code>addBinding($name, $portType)</code> 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><code>addBindingOperation()</code></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 <code>addBinding()</code>, en
        paramètre (<code>$binding</code>) 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><code>addSoapBinding()</code></title>

        <para><code>addSoapBinding($binding, $style = 'document', $transport =
        'http://schemas.xmlsoap.org/soap/http')</code> ajoute des correspondances (bindings) SOAP ("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 HTTP).</para>

        <para>L'élément "/definitions/binding/soap:binding" est alors utilisé pour spécifier que la correspondance est
        relative au format du protocole SOAP.</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><code>addSoapOperation()</code></title>

        <para><code>addSoapOperation($binding, $soap_action)</code> ajoute une opération SOAP ("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
        <code>addSoapBinding()</code></para>

        <para>L'attribut "soapAction" de l'élément "/definitions/binding/soap:operation" spécifie la valeur de l'en-tête
        SOAPAction pour l'opération. Cet attribut est requis pour SOAP sur HTTP 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
        SOAP.</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><code>addService()</code></title>

        <para><code>addService($name, $port_name, $binding, $location)</code> 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ù <code>$name</code> 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 SOAP à des
        types PHP : <itemizedlist>
                <listitem>
                    <para>chaînes PHP &lt;-&gt; <code>xsd:string</code>.</para>
                </listitem>

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

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

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

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

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

                <listitem>
                    <para>Classe PHP &lt;-&gt; basé sur la stratégie des types complexes (Voir : <xref
                    linkend="zend.soap.wsdl.types.add_complex" />)<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
                            <code>$extractComplexType</code> 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 PHP 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><code>getType($type)</code> peut être utilisée pour récupérer la correspondance d'un type PHP spécifié
            : <programlisting role="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><code>addComplexType($type)</code> est utilisée pour ajouter des types complexes (classes PHP) à un
            document WSDL.</para>

            <para>C'est automatiquement utilisé par la méthode <code>getType()</code> 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 <code>setComplexTypeStrategy($strategy)</code> 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 PHP.</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>. Il peut
                    seulement gérer les types PHP simples comme int, string, boolean, float et ainsi de suite, mais
                    permet de spécifier des tableaux imbriqués de tableaux de type.</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 PHP (nom de classe) à la stratégie désirée
                    grâce à la méthode <code>connectTypeToStrategy($type, $strategy)</code>. Une carte de correspondance
                    complète de types peut être fourni au constructeur sous la forme d'un tableau de paires
                    <code>$type</code> -&gt; <code>$strategy</code>. 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 <code>addComplexType()</code> 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 PHP spécifiée.</para>

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

            <para><code>addComplexType()</code> 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><code>addDocumentation()</code></title>

        <para><code>addDocumentation($input_node, $documentation)</code> 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 SOAP.</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><code>toXML()</code>, <code>toDomDocument()</code> et <code>dump($filename = false)</code> peuvent être
        utilisées pour récupérer un document WSDL sous forme de XML, de structure DOM, ou de fichier.</para>
    </sect2>

    <sect2 id="zend.soap.wsdl.parser">
        <title>Analyse des documents WSDL</title>

        <para>Zend_Soap_Wsdl contient aussi un analyseur de documents WSDL qui a son application la plus importante dans
        les tests unitaires et dans la génération de code pour les services Web SOAP (client et serveur). L'exemple
        suivant vous montre comment l'analyseur peut être utilisé :</para>

        <programlisting role="php"><![CDATA[
// Chargement du WSDL dans un DOMDocument
$dom = new DOMDocument();
$dom->loadXML($wsdlString);

// Création de l'analyseur
$parser = Zend_Soap_Wsdl_Parser::factory($dom);
$result = $parser->parse();

// Nom du service Web
echo $result->getName();

// Ports d'accès et éléments internes
foreach($result->ports AS $port) {
    echo $port->getName();
    foreach($port->bindings AS $binding) {
        echo $binding->getName();

        foreach($binding->operations AS $operation) {
            echo $operation->getName();
            echo $operation->inputMessage->getName();
            echo $operation->outputMessage->getName();
        }
    }
}
// Vous pouvez accéder aux liaisons (bindings), aux messages, aux opérations
// et tout autre éléments directement
foreach($result->operations AS $operation) {
    // faire qqch
}
foreach($result->bindings AS $binding {
    // faire qqch
}
foreach($result->messages AS $message) {
    // faire qqch
}
foreach($result->services AS $service) {
    // faire qqch
}
foreach($result->types AS $type) {
    // faire qqch
}
]]></programlisting>

        <para>Tous les éléments implémentent l'interface <classname>Zend_Soap_Wsdl_Element_Interface</classname> qui déclare les
        fonctions <code>getName()</code> et <code>getDocumentation()</code> fournissant respectivement un identifiant
        unique de l'élément et sa documentation. Tous les éléments possèdent des propriétés publiques qui décrivent son
        état avec plus de détails et qui contient aussi ses dépendances imbriquées pour un accès itérable facile.</para>
    </sect2>
</sect1>