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

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

    <note>
        <para>
            Die <classname>Zend_Soap_Wsdl</classname> Klasse wird von der Zend_Soap_Server
            Komponente intern verwendet um mit WSDL Dokumenten zu arbeiten. Trotzdem könnte man die
            Funktionalität die von dieser Klasse angeboten wird auch für eigene Zwecke verwendet
            werden. Das Zend_Soap_Wsdl Paket enthält sowohl einen Parser als auch einen Ersteller
            für WSDL Dokumente.
        </para>
        <para>
            Wenn man nicht plant das zu tun, kann dieses Kapitel der Dokumentation übersprungen
            werden.
        </para>
    </note>

    <sect2 id="zend.soap.wsdl.constructor">
        <title>Zend_Soap_Wsdl Konstruktor</title>
        <para>
            Der <classname>Zend_Soap_Wsdl</classname> Konstruktor nimmt drei Parameter:
            <orderedlist>
                <listitem>
                    <simpara>
                        <code>$name</code> - Name des Web Services der beschrieben wird.
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        <code>$uri</code> - URI wo das WSDL vorhanden sein wird (könnte auch eine
                        Referenz zu einer Datei auf dem Dateisystem sein.)
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        <code>$strategy</code>  - Optionales Flag das verwendet wird um die
                        Strategie für die Erkennung von komplexen Typen (Objekte) zu identifizieren.
                        Das war vor der Version 1.7 ein boolscher <code>$extractComplexTypes</code>
                        und kann aus Gründen der Rückwärtskompatibilität noch immer als Boolean
                        gesetzt werden. Standardmäßig ist das Erkennungsverhalten von 1.6 gesetzt.
                        Um mit Strategien für komplexe Typenerkennung weiterzumachen lesen wie
                        weiter im Kapitel: <xref linkend="zend.soap.wsdl.types.add_complex" />.
                    </simpara>
                </listitem>
            </orderedlist>
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.addmessage">
        <title>Die addMessage() Methode</title>
        <para>
            Die <code>addMessage($name, $parts)</code> Methode fügt eine neue Nachrichten
            Beschreibung zu einem WSDL Dokumetn hinzu (/definitions/message Element).
        </para>
        <para>
            Jede Nachricht korrespondiert zu einer Methode im Sinne von
            <classname>Zend_Soap_Server</classname> und <classname>Zend_Soap_Client</classname>
            Funktionalität.
        </para>
        <para>
           Der <code>$name</code> Parameter repräsentiert den Namen der Nachricht.
        </para>
        <para>
           Der <code>$parts</code> Parameter ist ein Array von Nachrichten Teilen welche SOAP Aufruf
           Parameter beschreiben. Es ist ein assoziatives Array:
           'part name' (SOAP Aufruf Parameter Name) =&gt; 'part type'.
        </para>
        <para>
            Das Typ Mapping Management wird durchgeführt indem die <code>addTypes()</code>,
            <code>addTypes()</code> und <code>addComplexType()</code> Methoden ausgeführt werden
            (siehe anbei).
        </para>
        <note>
            <para>
                Nachrichten Teile können entweder 'element' oder 'type' Attribute für das typisieren
                verwenden (siehe <ulink url="http://www.w3.org/TR/wsdl#_messages"/>).
            </para>
            <para>
                'element' Attribute müssen zu einem entsprechenden Element von Daten Typ Definition
                referieren. 'type' zu einem entsprechenden complexType Eintrag.
            </para>
            <para>
                Alle standardmäßigen XSD Typen haben beide 'element' und 'complexType' Definitionen
                (siehe <ulink url="http://schemas.xmlsoap.org/soap/encoding/"/>).
            </para>
            <para>
                Alle nicht-standardmäßigen Typen, welche hinzugefügt werden können durch verwenden
                der <classname>Zend_Soap_Wsdl::addComplexType()</classname> Methode, sind
                beschrieben durch Verwendung des 'complexType' Nodes des
                '/definitions/types/schema/' Abschnitts des WSDL Dokuments.
            </para>
            <para>
                <code>addMessage()</code> Methoden verwenden also immer das 'type' Attribut um Typen
                zu beschreiben.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_port_type">
        <title>Die addPortType() Methode</title>
        <para>
            Die <code>addPortType($name)</code> Methode fügt neue Port Typen zu einem WSDL Dokument
            (/definitions/portType) mit dem spezifizierten Port Typ Namen hinzu.
        </para>
        <para>
            Es verbindet ein Set von Web Service Methoden die im Sinne der Zend_Soap_Server
            Implementation definiert sind.
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_porttypes"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_port_operation">
        <title>Die addPortOperation() Methode</title>
        <para>
            Die <code>addPortOperation($portType, $name, $input = false, $output = false, $fault =
            false)</code> Methode fügt eine neue Port Operation zum spezifizierten Port Typ des WSDL
            Dokuments hinzu (/definitions/portType/operation).
        </para>
        <para>
            Jede Port Operation korrespondiert zu einer Methode der Klasse (wenn der Web Service auf
            einer Klasse basiert) oder Funktion (wenn der Web Service auf einem Set von Methoden
            basiert) im Sinne der Zend_Soap_Server Implementation.
        </para>
        <para>
            Sie fügt auch eine korrespondierende Port Operations Nachricht hinzu anhängig von den
            spezifizierten <code>$input</code>, <code>$output</code> und <code>$fault</code>
            Parametern.

            <note>
                <para>
                    Die Zend_Soap_Server Komponente erzeugt zwei Nachrichten für jede Port Operation
                    wärend das Service das auf der <classname>Zend_Soap_Server</classname> Klasse
                    basiert beschrieben wird:
                    <itemizedlist>
                        <listitem>
                            <para>
                                Eine Eingabe Nachricht mit dem Namen <code>$methodName .
                                'Request'</code>.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                Eine Ausgabe Nachricht mit dem Namen <code>$methodName .
                                'Response'</code>.
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </note>
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_request-response"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_binding">
        <title>Die addBinding() Methode</title>
        <para>
            Die <code>addBinding($name, $portType)</code> Methode fügt neue Bindungen in das WSDL
            Dokument ein (/definitions/binding).
        </para>
        <para>
            Der 'binding' WSDL Dokument Knoten definiert das Nachrichtenformat und Protokolldetails
            für Operationen und Nachrichten die von einem speziellen portType definiert sind
            (siehe <ulink url="http://www.w3.org/TR/wsdl#_bindings"/>).
        </para>
        <para>
            Die Methode erzeugt einen Bindungsknoten und gibt diesen zurück. Dieser kann dann
            verwendet werden um mit aktuellen Daten gefüllt zu werden.
        </para>

        <para>
            Die Zend_Soap_Server Implementation verwendet den <code>$serviceName . 'Binding'</code>
            Namen für das 'binding' Element eines WSDL Dokuments.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_binding_operation">
        <title>Die addBindingOperation() Methode</title>
        <para>
            Die <code>addBindingOperation($binding, $name, $input = false, $output = false, $fault =
            false)</code> Methode fügt eine Operation zu einem gebundenen Element mit dem
            spezifizierten Namen hinzu (/definitions/binding/operation).
        </para>
        <para>
            Sie nimmt das <code>XML_Tree_Node</code> Objekt das von <code>addBinding()</code>
            zurückgegeben wird als Eingabe (<code>$binding</code> Parameter) um ein 'operation'
            Element mit Eingabe/Ausgabe/Falsch Einträgen hinzuzufügen abhängig von den
            spezifizierten Parametern.
        </para>
        <para>
            Die Zend_Soap_Server Implementation fügt korrespondierende gebundene Einträge für jede
            Web Service Methode mit Eingabe und Ausgabe Einträgen hinzu die ein 'soap:body' Element
            als '&lt;soap:body use="encoded"
            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt; definieren.
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_bindings"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_soap_binding">
        <title>Die addSoapBinding() Methode</title>
        <para>
            Die <code>addSoapBinding($binding, $style = 'document', $transport =
            'http://schemas.xmlsoap.org/soap/http')</code> Methode fügt einen SOAP Bindung Eintrag
            ('soap:binding') zum Bindung Element (welches bereits zu einigen Port Typen verbunden
            ist) mit dem spezifizierten Stil und Transport hinzu (Die Zend_Soap_Server
            Implementation verwendet RPC Stil über HTTP).
        </para>
        <para>
            Das '/definitions/binding/soap:binding' Element wird verwendet um zu signieren das das
            Bindung zum SOAP Protokoll Format gebunden ist.
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_bindings"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_soap_operation">
        <title>Die addSoapOperation() Methode</title>
        <para>
            Die <code>addSoapOperation($binding, $soap_action)</code> Methode fügt einen SOAP
            Operations Eintrag ('soap:operation') zum Bindungs Element mit den spezifizierten
            Aktionen hinzu. Das 'style' Attribut des 'soap:operation' Elements wird nicht verwendet
            seit das Programmier Modell (RPC-orientiert oder Dokument-orientiert) die
            <code>addSoapBinding()</code> Methode verwenden kann.
        </para>
        <para>
            Das 'soapAction' Attribut des '/definitions/binding/soap:operation' Elements
            spezifiziert den Wert des SOAPAction Headers für diese Operation. Dieses Attribut wird
            für SOAP über HTTP benötigt und <emphasis>darf in keinem Fall</emphasis> für andere
            Transporte spezifiziert werden.
        </para>
        <para>
            Die Zend_Soap_Server Implementation verwendet <code>$serviceUri . '#' .
            $methodName</code> für den SOAP Operations Action Namen.
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_soap:operation"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_service">
        <title>Die addService() Methode</title>
        <para>
            Die <code>addService($name, $port_name, $binding, $location)</code> Methode fügt dem
            WSDL Dokument ein '/definitions/service' Element mit dem spezifizierten Web Service
            Namen, Port Namen, Bindung und Ort hinzu.
        </para>
        <para>
            WSDL 1.1 erlaubt es verschiedene Port Typen pro Service zu haben (Sets von Operationen).
            Diese Fähigkeit wird von der Zend_Soap_Server Implementation nicht verwendet und von der
            <classname>Zend_Soap_Wsdl</classname> Klasse nicht unterstützt.
        </para>
        <para>
            Die Zend_Soap_Server Implementation verwendet:
            <itemizedlist>
                <listitem>
                    <para>
                        <code>$name . 'Service'</code> als Web Service Name,
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>$name . 'Port'</code> als Port Typ Name,
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>'tns:' . $name . 'Binding'</code>
                            <footnote>
                                <para>
                                    <code>'tns:' namespace</code> wird als Skript URI definiert
                                    (<code>'http://'  .$_SERVER['HTTP_HOST'] .
                                    $_SERVER['SCRIPT_NAME']</code>).
                                </para>
                            </footnote>
                            als Bindungs Name,
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Die Skript URI<footnote><para><code>'http://'  .$_SERVER['HTTP_HOST'] .
                        $_SERVER['SCRIPT_NAME']</code></para></footnote> als eine Service URI für
                        die Web Service Definition bei Verwendung von Klassen.
                    </para>
                </listitem>
            </itemizedlist>
            wobei <code>$name</code> der Klassenname für die Web Service Definition ist wenn Klassen
            verwendet werden und Skript Name für die Web Service Definition wenn ein Set von
            Funktionen verwendet wird.
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_services"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.types">
        <title>Typ Entsprechung</title>
        <para>
            Die Zend_Soap WSDL Implementation der Zugriffsmethoden verwendet die folgenden Typ
            Entsprechungen zwischen PHP und SOAP Typen:

            <itemizedlist>
                <listitem>
                    <para>PHP Strings &lt;-&gt; <code>xsd:string</code>.</para>
                </listitem>
                <listitem>
                    <para>PHP Integer &lt;-&gt; <code>xsd:int</code>.</para>
                </listitem>
                <listitem>
                    <para>PHP Float und Double &lt;-&gt; <code>xsd:float</code>.</para>
                </listitem>
                <listitem>
                    <para>PHP Boolean &lt;-&gt; <code>xsd:boolean</code>.</para>
                </listitem>
                <listitem>
                    <para>PHP Arrays &lt;-&gt; <code>soap-enc:Array</code>.</para>
                </listitem>
                <listitem>
                    <para>PHP Objekt &lt;-&gt; <code>xsd:struct</code>.</para>
                </listitem>
                <listitem>
                    <para>
                        PHP Klasse &lt;-&gt; basierend auf der Strategie der komplexen Typen (Siehe:
                        <xref linkend="zend.soap.wsdl.types.add_complex" />)
                        <footnote>
                            <para>
                                Standardmäßig wird <classname>Zend_Soap_Wsdl</classname> mit der
                                Klasse
                                <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>
                                als Erkennungsalgorithmus für komplexe Typen erstellt. Der erste
                                Parameter des AutoDiscover Constructors nimmt jede Strategie für
                                komplexe Typen die
                                <classname>Zend_Soap_Wsdl_Strategy_Interface</classname>
                                implementiert oder einen String mit dem Namen dieser Klasse. Für
                                Rückwärtskompatibilität mit den dem Boolean
                                <code>$extractComplexType</code> werden Variablen auf dem folgenden
                                Weg geparst: Bei true, wird
                                <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>
                                verwendet, und bei false
                                <classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>.
                            </para>
                        </footnote>.
                    </para>
                </listitem>
                <listitem>
                    <para>PHP Void &lt;-&gt; Leerer Typ.</para>
                </listitem>
                <listitem>
                    <para>Wenn der Typ auf irgendeinem Grund zu keinem dieser Typen passt, dann wird
                    <code>xsd:anyType</code> verwendet.</para>
                </listitem>
            </itemizedlist>

            Wo <code>xsd:</code> ein "http://www.w3.org/2001/XMLSchema" Namespace ist, ist
            <code>soap-enc:</code> ein "http://schemas.xmlsoap.org/soap/encoding/" Namespace,
            und <code>tns:</code> ist ein "Ziel Namespace" für das Service.
        </para>

        <sect3 id="zend.soap.wsdl.types.retrieve">
            <title>Empfangen von Typ Informationen</title>
            <para>
                Die <code>getType($type)</code> Methode kann verwendet werden um ein Mapping für
                einen spezifizierten PHP Typ zu erhalten:

                <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>Hinzufügen komplexer Typ Informationen</title>
            <para>
                Die <code>addComplexType($type)</code> Methode wird verwendet um komplexe Typen
                (PHP Klassen) zu einem WSDL Dokument hinzuzufügen.
            </para>

            <para>
                Es wird automatisch von der <code>getType()</code> Methode verwendet und fügt einen
                korrespondierenden komplexen Typen von Methodenparametern oder Rückgabetypen hinzu.
            </para>

            <para>
                Der Algorithmus für das Erkennen und Aufbauen basiert auf der aktuellen Strategie
                für die aktive Erkennung von komplexen Typen. Man kann die Strategie für die
                Erkennung setzen indem entweder der Klassenname as String spezifiziert wird, oder
                indem eine Instanz einer <classname>Zend_Soap_Wsdl_Strategy_Interface</classname>
                Implementation als dritter Parameter des Konstruktors verwendet wird, oder indem die
                <code>setComplexTypeStrategy($strategy)</code> Funktion von Zend_Soap_Wsdl verwendet
                wird. Die folgenden Strategien für die Erkennung existieren aktuell:
            </para>

            <itemizedlist>
                <listitem>
                    <para>Klasse <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>:
                    Standardmäßig aktiviert (wenn dem Konstruktor kein dritter Parameter gesetzt
                    wird). Er iteriert über die öffentlichen Attribute eines Klassentyps und
                    registriert Sie als Untertypen des komplexen Objekttyps.</para>
                </listitem>
                <listitem>
                    <para>Klasse <classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>: Castet alle
                    komplexen Typen in einen einfachen XSD Typ xsd:anyType. Vorsicht ist angeraten
                    da diese Abkürzung für die Erkennung von komplexen Typen kann warscheinlich nur
                    von lose typisierten Sprachen wie PHP erfolgreich behandelt werden.
                    </para>
                </listitem>
                <listitem>
                    <para>Klasse <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence</classname>:
                    Diese Strategie erlaubt es die Rückgabeparameter mit diesen Typen zu
                    spezifizieren: <code>int[]</code> oder <code>string[]</code>. Er kann einfache
                    PHP Typen wie Int, String, Boolean, Float und so weiter behandeln, erlaubt aber
                    die Spezifikation von verschachtelten Arrays oder Typen von Arrays.</para>
                </listitem>
                <listitem>
                    <para>Klasse <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeComplex</classname>:
                    Diese Strategie erlaubt die Erkennung von sehr komplexen Arrays von Objekten.
                    Objekttypen werden basierend auf
                    <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> erkannt und
                    ein Array wird um diese Definition gewrappt.</para>
                </listitem>
                <listitem>
                    <para>Klasse <classname>Zend_Soap_Wsdl_Strategy_Composite</classname>: Diese
                    Strategie kann alle Strategien kombinieren indem PHP komplexe Typen
                    (Klassennamen) zu der gewünschten Strategie über die
                    <code>connectTypeToStrategy($type, $strategy)</code> Methode verbunden werden.
                    Eine komplette Typemap kann dem Contructor als Array, mit <code>$type</code> ->
                    <code>$strategy</code> Paaren angegeben werden. Der zweite Parameter
                    spezifiziert die Standardstrategie die verwendet wird wenn ein unbekannter Typ
                    hinzugefügt werden soll. Diese Parameter ist standardmäßig die
                    <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>
                    Strategie.</para>
                </listitem>
            </itemizedlist>

            <para>
                Die <code>addComplexType()</code> Methode erstellt ein
                '/definitions/types/xsd:schema/xsd:complexType' Element für jeden beschriebenen
                komplexen Typen mit dem Namen der spezifizierten PHP Klasse.
            </para>

            <para>
                Die Klassen Eigenschaften <emphasis>MÜSSEN</emphasis> ein Docblock Kapitel mit den
                beschriebenen PHP Typen haben damit die Eigenschaft in die WSDL Beschreibung
                hinzugefügt wird.
            </para>

            <para>
                <code>addComplexType()</code> prüft ob der Typ bereits im Typ Kapitel des WSDL
                Dokuments beschrieben wird.
            </para>

            <para>
                Es verhindert Duplikate wenn diese Methode zwei oder mehrmals aufgerufen wird und
                auch Rekursionen im Kapitel der Typ Definitionen.
            </para>

            <para>
                Siehe <ulink url="http://www.w3.org/TR/wsdl#_types"/> für Details.
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.soap.wsdl.add_documentation">
        <title>Die addDocumentation() Methode</title>
        <para>
            Die <code>addDocumentation($input_node, $documentation)</code> Methode fügt menschlich
            lesbare Dokumentation hinzu indem das optionale 'wsdl:document' Element verwendet wird.
        </para>
        <para>
            Das '/definitions/binding/soap:binding' Element wird verwendet um zu signieren das die
            Bindung zum SOAP Protokoll Format gebunden wurde.
        </para>
        <para>
            Siehe <ulink url="http://www.w3.org/TR/wsdl#_documentation"/> für Details.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.retrieve">
        <title>Das endgültige WSDL Dokument erhalten</title>
        <para>
            Die <code>toXML()</code>, <code>toDomDocument()</code> und <code>dump($filename =
            false)</code> Methoden können verwendet werden um das WSDL Dokument als XML, DOM
            Struktur oder Datei zu erhalten.
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.parser">
        <title>Parsen von WSDL Dokumentenrsing WSDL documents</title>

        <para>
            Zend_Soap_Wsdl enthält auch einen Parser für WSDL Dokumente der seine eigene
            Hauptanwendung für das Unit-Testen und die Code-Erzeugung von SOAP Webservices (Client
            und Server) hat. Das folgende Beispiel zeigt wie der Parser verwendet werden kann:
        </para>

        <programlisting language="php"><![CDATA[
// Laden von WSDL in DOMDocument
$dom = new DOMDocument();
$dom->loadXML($wsdlString);

// Parser erstellen
$parser = Zend_Soap_Wsdl_Parser::factory($dom);
$result = $parser->parse();

// Name des Webservices
echo $result->getName();

// Auf Ports und innere Element zugreifen
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();
        }
    }
}
// Man kann auf Bindungen, Nachrichten und Operationen und andere
// Elemente direkt zugreifen
foreach($result->operations AS $operation) {
    // mach was
}
foreach($result->bindings AS $binding {
    // mach was
}
foreach($result->messages AS $message) {
    // mach was
}
foreach($result->services AS $service) {
    // mach was
}
foreach($result->types AS $type) {
    // mach was
}
]]></programlisting>

        <para>Alle Element implementieren das Interface
        <classname>Zend_Soap_Wsdl_Element_Interface</classname> das auf eine <code>getName()</code>
        und <code>getDocumentation()</code> Funktion mit den eindeutigen Identifikatoren des
        Elements und seiner Dokumentation verweist. Alle Elemente haben öffentliche Eigenschaften
        die Ihren Status detailierter beschreiben und auch Ihre untergeordneten Abhängigkeiten für
        den einfachen Zugriff über Iteration enthalten.</para>
    </sect2>

</sect1>