documentation/manual/fr/module_specs/Zend_Soap_Wsdl.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21829 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.soap.wsdl">
   5     <title>WSDL</title>
   6
   7     <note>
   8         <para>
   9             La classe <classname>Zend_Soap_Wsdl</classname> est utilisée par le composant
  10             Zend_Soap_Server pour manipuler des documents WSDL. Néanmoins, vous pouvez vous-même
  11             utiliser les services fournis par cette classe pour vos propres besoins. La classe
  12             Zend_Soap_Wsdl contient à la fois un analyseur et un constructeur de documents
  13             WSDL.
  14         </para>
  15
  16         <para>
  17             Si vous ne voulez pas l'utiliser pour vos propres besoins, vous pouvez alors
  18             passer cette section de la documentation.
  19         </para>
  20     </note>
  21
  22     <sect2 id="zend.soap.wsdl.constructor">
  23         <title>Constructeur Zend_Soap_Wsdl</title>
  24
  25         <para>
  26             Le constructeur de <classname>Zend_Soap_Wsdl</classname> prend 3 paramètres :
  27             <orderedlist>
  28                     <listitem>
  29                         <simpara><varname>$name</varname> - nom du service Web décrit.</simpara>
  30                     </listitem>
  31
  32                     <listitem>
  33                         <simpara><varname>$uri</varname> - <acronym>URI</acronym> d'accès au fichier WSDL. (Une référence
  34                         dans le système de fichier local est possible.)</simpara>
  35                     </listitem>
  36
  37                     <listitem>
  38                         <simpara><varname>$strategy</varname> - identifiant optionnel pour identifier la
  39                         détection de stratégie des types complexes. Ceci est un booléen
  40                         <varname>$extractComplexTypes</varname> avant la version 1.7 et peut toujours être
  41                         paramétrer via un booléen pour la compatibilité ascendante. Par défaut le
  42                         comportement de détection de la 1.6 est activé. Pour avoir de plus amples
  43                         informations concernant les stratégies de détection des types complexes,
  44                         lisez : <xref linkend="zend.soap.wsdl.types.add_complex" />.</simpara>
  45                     </listitem>
  46                 </orderedlist>
  47             </para>
  48     </sect2>
  49
  50     <sect2 id="zend.soap.wsdl.addmessage">
  51         <title>addMessage()</title>
  52
  53         <para>
  54             <methodname>addMessage($name, $parts)</methodname> ajoute un message de description au
  55             document WSDL (/definitions/message de l'élément).
  56         </para>
  57
  58         <para>
  59             Chaque message correspond à une méthode en terme de fonctionnalité de
  60             <classname>Zend_Soap_Server</classname> et
  61             <classname>Zend_Soap_Client</classname>.
  62         </para>
  63
  64         <para>Le paramètre <varname>$name</varname> représente le nom du message.</para>
  65
  66         <para>
  67             Le paramètre <varname>$parts</varname> est un tableau de paramètre des messages
  68             décrivant les paramètres d'appel <acronym>SOAP</acronym>. Le tableau est associatif: 'nom du paramètre'
  69             (nom du paramètre d'appel <acronym>SOAP</acronym>) =&gt; 'type du paramètre'.
  70         </para>
  71
  72         <para>
  73             La correspondance de types est effectuée grâce à <methodname>addTypes()</methodname> et
  74             <methodname>addComplexType()</methodname>(voyez après).
  75         </para>
  76
  77         <note>
  78             <para>
  79                 Les paramètres de messages peuvent être soit "element", soit "type" (voyez
  80                 <ulink url="http://www.w3.org/TR/wsdl#_messages"></ulink>).
  81             </para>
  82
  83             <para>
  84                 "element" doit correspondre à un élément de définition de type. "type"
  85                 correspond à une entrée complexType.
  86             </para>
  87
  88             <para>
  89                 Tous les types standards XSD possèdent une définition "element" et
  90                 "complexType" (Voyez <ulink
  91                 url="http://schemas.xmlsoap.org/soap/encoding/"></ulink>).
  92             </para>
  93
  94             <para>
  95                 Tous les éléments non standards, qui doivent être ajoutés avec la méthode
  96                 <methodname>Zend_Soap_Wsdl::addComplexType()</methodname>, sont décrits en utilisant
  97                 un noeud "complexType" décrits dans la section "/definitions/types/schema/" du
  98                 document WSDL.
  99             </para>
 100
 101             <para>
 102                 Ainsi, la méthode <methodname>addMessage()</methodname> utilise toujours un attribut
 103                 "type" pour décrire des types.
 104             </para>
 105         </note>
 106     </sect2>
 107
 108     <sect2 id="zend.soap.wsdl.add_port_type">
 109         <title><methodname>addPortType()</methodname></title>
 110
 111         <para>
 112             <methodname>addPortType($name)</methodname> ajoute un nouveau type de portage au document WSDL
 113             (/definitions/portType).
 114         </para>
 115
 116         <para>
 117             Ceci fait la jointure entre des méthodes du service décrites en tant
 118             qu'implémentations de Zend_Soap_Server.
 119         </para>
 120
 121         <para>
 122             Voyez <ulink url="http://www.w3.org/TR/wsdl#_porttypes"></ulink> pour plus de
 123             détails.
 124         </para>
 125     </sect2>
 126
 127     <sect2 id="zend.soap.wsdl.add_port_operation">
 128         <title><methodname>addPortOperation()</methodname></title>
 129
 130         <para>
 131             <code>addPortOperation($portType, $name, $input = false, $output = false, $fault =
 132             false)</code> ajoute des définitions de portage au portage défini dans le document WSDL
 133             (/definitions/portType/operation).
 134         </para>
 135
 136         <para>
 137             Chaque opération de portage correspond à une méthode de classe (si le Web Service
 138             est basé sur une classe) ou à une fonction (si le Web Service est basé sur des
 139             fonctions), ceci en terme d'implémentation de Zend_Soap_Server.
 140         </para>
 141
 142         <para>
 143             Cette méthode ajoute aussi les messages d'opération correspondants aux portages,
 144             ceci dépend des paramètres <varname>$input</varname>, <varname>$output</varname> and
 145             <varname>$fault</varname>. <note>
 146                 <para>
 147                     Zend_Soap_Server génère 2 messages pour chaque opération de portage
 148                     lorsque le service est décrit au travers de la classe
 149                     <classname>Zend_Soap_Server</classname>: <itemizedlist>
 150                             <listitem>
 151                             <para>
 152                                 Le message d'entrée nommé <code>$methodName .
 153                                 'Request'</code>.
 154                             </para>
 155                         </listitem>
 156
 157                         <listitem>
 158                             <para>
 159                                 Les message de sortie nommé <code>$methodName .
 160                                 'Response'</code>.
 161                             </para>
 162                         </listitem>
 163                         </itemizedlist>
 164                     </para>
 165                 </note>
 166             </para>
 167
 168         <para>
 169             Voyez <ulink url="http://www.w3.org/TR/wsdl#_request-response"></ulink> pour les
 170             détails.
 171         </para>
 172     </sect2>
 173
 174     <sect2 id="zend.soap.wsdl.add_binding">
 175         <title><methodname>addBinding()</methodname></title>
 176
 177         <para>
 178             <methodname>addBinding($name, $portType)</methodname> ajoute de nouvelles correspondances
 179             (bindings) au document WSDL (/definitions/binding).
 180         </para>
 181
 182         <para>
 183             Le noeud du document WSDL "binding" définit le format du message et les détails du
 184             protocole pour les opérations et messages définis par un portage "portType" particulier
 185             (voyez <ulink url="http://www.w3.org/TR/wsdl#_bindings"></ulink>).
 186         </para>
 187
 188         <para>
 189             La méthode crée le noeud de correspondance et le retourne. Il peut alors être
 190             utilisé.
 191         </para>
 192
 193         <para>
 194             L'implémentation de Zend_Soap_Server utilise le nom <code>$serviceName .
 195             "Binding"</code> pour la correspondance ("binding") de l'élément du document
 196             WSDL.
 197         </para>
 198     </sect2>
 199
 200     <sect2 id="zend.soap.wsdl.add_binding_operation">
 201         <title><methodname>addBindingOperation()</methodname></title>
 202
 203         <para>
 204             <code>addBindingOperation($binding, $name, $input = false, $output = false, $fault
 205             = false)</code> ajoute une opération à l'élément de correspondance avec le nom spécifié
 206             (/definitions/binding/operation).
 207         </para>
 208
 209         <para>
 210             Cette méthode prend un objet <code>XML_Tree_Node</code> tel que retourné par
 211             <methodname>addBinding()</methodname>, en paramètre (<varname>$binding</varname>) pour ajouter un élément
 212             "operation" avec des entrées input/output/false dépendantes des paramètres
 213             spécifiés.
 214         </para>
 215
 216         <para>
 217             <classname>Zend_Soap_Server</classname> ajoute les correspondances pour chaque
 218             méthode du Web Service avec des entrées et sorties, définissant l'élément "soap:body"
 219             comme <code>&lt;soap:body use="encoded"
 220             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt;</code>
 221         </para>
 222
 223         <para>
 224             Voyez les détails à <ulink
 225             url="http://www.w3.org/TR/wsdl#_bindings"></ulink>.
 226         </para>
 227     </sect2>
 228
 229     <sect2 id="zend.soap.wsdl.add_soap_binding">
 230         <title><methodname>addSoapBinding()</methodname></title>
 231
 232         <para>
 233             <code>addSoapBinding($binding, $style = 'document', $transport =
 234             'http://schemas.xmlsoap.org/soap/http')</code> ajoute des correspondances (bindings)
 235             <acronym>SOAP</acronym> ("soap:binding") à l'élément (déjà lié à un portage de type) avec le style et le
 236             transport spécifié (<classname>Zend_Soap_Server</classname> utilise le style RPC sur
 237             <acronym>HTTP</acronym>).
 238         </para>
 239
 240         <para>
 241             L'élément "/definitions/binding/soap:binding" est alors utilisé pour spécifier que
 242             la correspondance est relative au format du protocole <acronym>SOAP</acronym>.
 243         </para>
 244
 245         <para>
 246             Voyez <ulink url="http://www.w3.org/TR/wsdl#_bindings"></ulink> pour les
 247             détails.
 248         </para>
 249     </sect2>
 250
 251     <sect2 id="zend.soap.wsdl.add_soap_operation">
 252         <title><methodname>addSoapOperation()</methodname></title>
 253
 254         <para>
 255             <methodname>addSoapOperation($binding, $soap_action)</methodname> ajoute une opération <acronym>SOAP</acronym>
 256             ("soap:operation") à l'élément de correspondance avec l'action spécifiée. L'attribut
 257             "style" de l'élément "soap:operation" n'est pas utilisé alors que le modèle de
 258             programmation (RPC-oriented ou document-oriented) devrait utiliser la méthode
 259             <methodname>addSoapBinding()</methodname>
 260         </para>
 261
 262         <para>
 263             L'attribut "soapAction" de l'élément "/definitions/binding/soap:operation"
 264             spécifie la valeur de l'en-tête <acronym>SOAP</acronym>Action pour l'opération. Cet attribut est requis
 265             pour <acronym>SOAP</acronym> sur <acronym>HTTP</acronym> et <emphasis>ne doit pas</emphasis> être renseigné pour les autres
 266             modes de transports.
 267         </para>
 268
 269         <para>
 270             <classname>Zend_Soap_Server</classname> utilise <code>$serviceUri . '#' .
 271             $methodName</code> pour le nom de l'action <acronym>SOAP</acronym>.
 272         </para>
 273
 274         <para>
 275             Voyez <ulink url="http://www.w3.org/TR/wsdl#_soap:operation"></ulink> pour plus de
 276             détails.
 277         </para>
 278     </sect2>
 279
 280     <sect2 id="zend.soap.wsdl.add_service">
 281         <title><methodname>addService()</methodname></title>
 282
 283         <para>
 284             <methodname>addService($name, $port_name, $binding, $location)</methodname> ajoute un élément
 285             "/definitions/service" au document WSDL avec le nom du Web Service spécifié, le nom du
 286             portage, la correspondance, et l'adresse.
 287         </para>
 288
 289         <para>
 290             WSDL 1.1 autorise d'avoir plusieurs types de portage par service. Cette
 291             particularité n'est pas utilisée dans <classname>Zend_Soap_Server</classname> et est non
 292             supportée par la classe <classname>Zend_Soap_Wsdl</classname>.
 293         </para>
 294
 295         <para>
 296             Utilisations de <classname>Zend_Soap_Server</classname> : <itemizedlist>
 297                     <listitem>
 298                         <para><code>$name . 'Service'</code> comme nom du Web Service,</para>
 299                     </listitem>
 300
 301                     <listitem>
 302                         <para><code>$name . 'Port'</code> comme nom de portage des types,</para>
 303                     </listitem>
 304
 305                     <listitem>
 306                     <para>
 307                         <code>'tns:' . $name . 'Binding'</code> <footnote>
 308                             <para>
 309                                 <code>'tns:' namespace</code> est l'URI du script
 310                                 (<code>'http://' .$_SERVER['HTTP_HOST'] .
 311                                 $_SERVER['SCRIPT_NAME']</code>).
 312                             </para>
 313                             </footnote> comme nom de la correspondance,
 314                         </para>
 315                 </listitem>
 316
 317                 <listitem>
 318                     <para>
 319                         l'URI du script<footnote>
 320                             <para>
 321                                 <code>'http://' .$_SERVER['HTTP_HOST'] .
 322                                 $_SERVER['SCRIPT_NAME']</code>
 323                             </para>
 324                         </footnote> en tant qu'URI du service pour les Web Service utilisant des
 325                         classes.
 326                     </para>
 327                 </listitem>
 328             </itemizedlist> où <varname>$name</varname> est un nom de classe pour le Web Service
 329         utilisant des classes, ou un nom de script pour le Web Service qui utilise des
 330             fonctions.
 331         </para>
 332
 333         <para>
 334             Voyez <ulink url="http://www.w3.org/TR/wsdl#_services"></ulink> pour les
 335             détails.
 336         </para>
 337     </sect2>
 338
 339     <sect2 id="zend.soap.wsdl.types">
 340         <title>Correspondance de type</title>
 341
 342         <para>
 343             Le WSDL de Zend_Soap utilise les correspondances suivantes pour faire correspondre
 344             les type <acronym>SOAP</acronym> à des types <acronym>PHP</acronym> : <itemizedlist>
 345                     <listitem>
 346                         <para>chaînes <acronym>PHP</acronym> &lt;-&gt; <code>xsd:string</code>.</para>
 347                     </listitem>
 348
 349                     <listitem>
 350                         <para>entiers <acronym>PHP</acronym> &lt;-&gt; <code>xsd:int</code>.</para>
 351                     </listitem>
 352
 353                     <listitem>
 354                         <para>flottants <acronym>PHP</acronym> &lt;-&gt; <code>xsd:float</code>.</para>
 355                     </listitem>
 356
 357                     <listitem>
 358                         <para>booléens <acronym>PHP</acronym> &lt;-&gt; <code>xsd:boolean</code>.</para>
 359                     </listitem>
 360
 361                     <listitem>
 362                         <para>tableaux <acronym>PHP</acronym> &lt;-&gt; <code>soap-enc:Array</code>.</para>
 363                     </listitem>
 364
 365                     <listitem>
 366                         <para>objets <acronym>PHP</acronym> &lt;-&gt; <code>xsd:struct</code>.</para>
 367                     </listitem>
 368
 369                     <listitem>
 370                     <para>
 371                         Classe <acronym>PHP</acronym> &lt;-&gt; basé sur la stratégie des types complexes (Voir :
 372                         <xref linkend="zend.soap.wsdl.types.add_complex" />)<footnote>
 373                             <para>
 374                                 <classname>Zend_Soap_AutoDiscover</classname> sera créé avec
 375                                 la classe
 376                                 <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> en
 377                                 tant qu'algorithme de détection pour les types complexes. Le premier
 378                                 paramètre du constructeur AutoDiscover accepte toute stratégie de
 379                                 types complexes implémentant
 380                                 <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> ou une
 381                                 chaîne correspondant au nom de la classe. Pour une compatibilité
 382                                 ascendante, avec <varname>$extractComplexType</varname> les variables
 383                                 booléennes sont analysées comme avec Zend_Soap_Wsdl. Regardez le
 384                                 manuel <link
 385                                 linkend="zend.soap.wsdl.types.add_complex">Zend_Soap_Wsdl sur
 386                                 l'ajout des types complexes</link> pour plus d'informations.
 387                             </para>
 388                             </footnote>.
 389                         </para>
 390                 </listitem>
 391
 392                 <listitem>
 393                     <para>Type <acronym>PHP</acronym> vide &lt;-&gt; void.</para>
 394                 </listitem>
 395
 396                 <listitem>
 397                     <para>
 398                         Si le type na aucune correspondance avec les valeurs ci-dessus, alors
 399                         <code>xsd:anyType</code> est utilisé.
 400                     </para>
 401                 </listitem>
 402             </itemizedlist> Où <code>xsd:</code> est l'espace de noms
 403         "http://www.w3.org/2001/XMLSchema", <code>soap-enc:</code> est l'espace de noms
 404         "http://schemas.xmlsoap.org/soap/encoding/", <code>tns:</code> est un "espace de noms
 405             cible" pour le service.
 406         </para>
 407
 408         <sect3 id="zend.soap.wsdl.types.retrieve">
 409             <title>Récupérer des infos sur les types</title>
 410
 411             <para>
 412                 <methodname>getType($type)</methodname> peut être utilisée pour récupérer la
 413                 correspondance d'un type PHP spécifié : <programlisting language="php"><![CDATA[
 414 ...
 415 $wsdl = new Zend_Soap_Wsdl('My_Web_Service', $myWebServiceUri);
 416
 417 ...
 418 $soapIntType = $wsdl->getType('int');
 419
 420 ...
 421 class MyClass {
 422     ...
 423 }
 424 ...
 425 $soapMyClassType = $wsdl->getType('MyClass');
 426 ]]></programlisting></para>
 427             </sect3>
 428
 429             <sect3 id="zend.soap.wsdl.types.add_complex">
 430                 <title>Ajouter des infos sur les types complexes</title>
 431
 432             <para>
 433                 <methodname>addComplexType($type)</methodname> est utilisée pour ajouter des types
 434                 complexes (classes <acronym>PHP</acronym>) à un document WSDL.
 435             </para>
 436
 437             <para>
 438                 C'est automatiquement utilisé par la méthode <methodname>getType()</methodname> pour
 439                 ajouter les types complexes des paramètres de méthodes ou des types
 440                 retournés.
 441             </para>
 442
 443             <para>
 444                 Sa détection et son algorithme de construction est basé sur la détection de
 445                 stratégie des types complexes couramment active. Vous pouvez paramétrer la stratégie
 446                 de détection soit en spécifiant le nom de classe sous la forme d'une chaîne de
 447                 caractères ou une instance implémentant
 448                 <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> en tant que troisième
 449                 paramètre du constructeur ou en utilisant la fonction
 450                 <methodname>setComplexTypeStrategy($strategy)</methodname> de
 451                 <classname>Zend_Soap_Wsdl</classname>. Les stratégies de détection suivantes
 452                 existent couramment :
 453             </para>
 454
 455             <itemizedlist>
 456                 <listitem>
 457                     <para>
 458                         la classe
 459                         <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> : activé
 460                         par défaut (quand aucun troisième paramètre n'est fourni). Itère parmi les
 461                         attributs publics d'un type de classe et les enregistre en tant que
 462                         sous-types d'un type d'objet complexe.
 463                     </para>
 464                 </listitem>
 465
 466                 <listitem>
 467                     <para>
 468                         la classe <classname>Zend_Soap_Wsdl_Strategy_AnyType</classname> :
 469                         caste tous les types complexes en un type XSD simple xsd:anyType. Attention
 470                         ce raccourci pour la détection des types complexes peut probablement
 471                         seulement être géré avec des langages faiblement typés comme le <acronym>PHP</acronym>.
 472                     </para>
 473                 </listitem>
 474
 475                 <listitem>
 476                     <para>
 477                         la classe
 478                         <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence</classname> : cette
 479                         stratégie permet de spécifier les paramètres de retour de type :
 480                         <code>int[]</code> ou <code>string[]</code>. A partir de Zend Framework 1.9,
 481                         il peut gérer des types <acronym>PHP</acronym> simples comme int, string, boolean, float ainsi
 482                         que des objets ou des tableaux d'objets.
 483                     </para>
 484                 </listitem>
 485
 486                 <listitem>
 487                     <para>
 488                         la classe
 489                         <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeComplex</classname> : cette
 490                         stratégie permet de détecter des tableaux complexes d'objets. Les types
 491                         d'objets sont détectés sur la base de
 492                         <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> et un
 493                         tableau enveloppe cette définition.
 494                     </para>
 495                 </listitem>
 496
 497                 <listitem>
 498                     <para>
 499                         la classe <classname>Zend_Soap_Wsdl_Strategy_Composite</classname> :
 500                         cette stratégie peut combiner toutes les stratégies en connectant les types
 501                         complexes <acronym>PHP</acronym> (nom de classe) à la stratégie désirée grâce à la méthode
 502                         <methodname>connectTypeToStrategy($type, $strategy)</methodname>. Une carte de
 503                         correspondance complète de types peut être fourni au constructeur sous la
 504                         forme d'un tableau de paires <varname>$type</varname> -&gt;
 505                         <varname>$strategy</varname>. Le second paramètre spécifie la stratégie par défaut
 506                         si un type inconnu est ajouté. La valeur par défaut de ce paramètre est la
 507                         stratégie
 508                         <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>.
 509                     </para>
 510                 </listitem>
 511             </itemizedlist>
 512
 513             <para>
 514                 la méthode <methodname>addComplexType()</methodname> crée un élément
 515                 "<code>/definitions/types/xsd:schema/xsd:complexType</code>" pour chaque type
 516                 complexe décrit avec le nom d'une classe <acronym>PHP</acronym> spécifiée.
 517             </para>
 518
 519             <para>
 520                 Les propriétés des classes <emphasis>doivent</emphasis> posséder un bloc de
 521                 documentation avec le type <acronym>PHP</acronym> en question, afin que la propriété soit incluse dans
 522                 la description WSDL.
 523             </para>
 524
 525             <para>
 526                 <methodname>addComplexType()</methodname> vérifie sur le type est déjà décrit dans la
 527                 section des types du document WSDL.
 528             </para>
 529
 530             <para>
 531                 Ceci évite les duplications et récursions si cette méthode est appelée plus
 532                 d'une fois.
 533             </para>
 534
 535             <para>
 536                 Voyez <ulink url="http://www.w3.org/TR/wsdl#_types"></ulink> pour plus de
 537                 détails.
 538             </para>
 539         </sect3>
 540     </sect2>
 541
 542     <sect2 id="zend.soap.wsdl.add_documentation">
 543         <title><methodname>addDocumentation()</methodname></title>
 544
 545         <para>
 546             <methodname>addDocumentation($input_node, $documentation)</methodname> ajoute de la
 547             documentation lisible ("human readable") grâce à l'élément optionnel
 548             "wsdl:document".
 549         </para>
 550
 551         <para>
 552             L'élément "/definitions/binding/soap:binding" est utilisé pour dire que la
 553             correspondance est liée au format du protocole <acronym>SOAP</acronym>.
 554         </para>
 555
 556         <para>
 557             Voyez <ulink url="http://www.w3.org/TR/wsdl#_documentation"></ulink> pour les
 558             détails.
 559         </para>
 560     </sect2>
 561
 562     <sect2 id="zend.soap.wsdl.retrieve">
 563         <title>Récupérer un document WSDL finalisé</title>
 564
 565         <para>
 566             <methodname>toXML()</methodname>, <methodname>toDomDocument()</methodname> et <code>dump($filename =
 567             false)</code> peuvent être utilisées pour récupérer un document WSDL sous forme de <acronym>XML</acronym>,
 568             de structure DOM, ou de fichier.
 569         </para>
 570     </sect2>
 571 </sect1>