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

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

    <sect2 id="zend.soap.autodiscovery.introduction">
        <title>AutoDiscovery Einführung</title>
        <para>
            Die SOAP Funktionalität die im Zend Framework implementiert ist, ist dazu gedacht alle benötigten
            Schritte für die SOAP Kommunikation einfacher zu gestalten.
        </para>

        <para>
            SOAP ist ein von der Sprache unabhängiges Protokoll. Deshalb kann es nicht nur für
            PHP-zu-PHP Kommunikation verwendet werden.
        </para>

        <para>
            Es gibt drei Konfigurationen für SOAP Anwendungen wo Zend Framework verwendet werden kann:
            <orderedlist>
                <listitem>
                    <simpara>SOAP Server PHP Anwendung &lt;---&gt; SOAP Client PHP Anwendung</simpara>
                </listitem>
                <listitem>
                    <simpara>SOAP Server nicht-PHP Anwendung &lt;---&gt; SOAP Client PHP Anwendung</simpara>
                </listitem>
                <listitem>
                    <simpara>SOAP Server PHP Anwendung &lt;---&gt; SOAP Client nicht-PHP Anwendung</simpara>
                </listitem>
            </orderedlist>
        </para>

        <para>
            Wir müssen immer wissen, welche Funktionalität vom SOAP Server angeboten wird um mit Ihm zu
            arbeiten. <ulink url="http://www.w3.org/TR/wsdl">WSDL</ulink> wird verwendet um die Netzwerk
            Service API im Detail zu beschreiben.
        </para>

        <para>
            Die WSDL Sprache ist komplex genug (siehe <ulink url="http://www.w3.org/TR/wsdl">http://www.w3.org/TR/wsdl</ulink>
            für die Details). Es ist also kompliziert genug die richtige WSDL Beschreibung vorzubereiten.
        </para>

        <para>
            Ein anderes Problem ist die Synchronisation von Änderungen in der Netzwerk Service API mit schon
            existierendem WSDL.
        </para>

        <para>
            Aber dieses Problem kann durch WSDL Autogeneration gelöst werden. Eine Vorbedingung dafür ist ein
            SOAP Server Autodiscovery. Es erzeugt ein Objekt ähnlich dem Objekt das in der SOAP Server
            Anwendung verwendet wird, extrahiert notwendige Informationen und erzeugt ein korrektes WSDL indem
            es die Information verwendet.
        </para>

        <para>
            Es gibt zwei Wege für die Verwendung des Zend Framworks für SOAP Server Anwendungen:
            <itemizedlist>
                <listitem>
                    <para>Verwendung von eigenen Klassen.</para>
                </listitem>
                <listitem>
                    <para>Verwendung eines Sets von Funktionen</para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Beide Methoden werden von der Zend Framework Autodiscovery Funktionalität unterstützt.
        </para>

        <para>
            Die <classname>Zend_Soap_AutoDiscovery</classname> Klasse unterstützt auch das Mapping von Datentypen
            von PHP zu <ulink url="http://www.w3.org/TR/xmlschema-2/">XSD Typen</ulink>.
        </para>

        <para>
            Hier ist ein Beispiel einer üblichen Verwendung der Autodiscovery Funktionalität. Die
            Funktion <code>handle()</code> erzeugt die WSDL Datei und postet Sie an den Browser.

            <programlisting role="php"><![CDATA[
class My_SoapServer_Class {
...
}

$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->setClass('My_SoapServer_Class');
$autodiscover->handle();
]]></programlisting>
        </para>

        <para>
            Wenn man auf die erzeugte WSDL Datei zugreifen muß um Sie in eine Datei oder als XML String
            abzuspeichern, kann man die Funktionen <code>dump($filename)</code> oder <code>toXml()</code>
            verwenden die die AutoDiscovery Klasse anbietet.
        </para>

        <note id="zend.soap.autodiscovery.introduction.noserver">
            <title>Zend_Soap_Autodiscover ist kein Soap Server</title>

            <para>
                Es ist wichtig anzumerken, das die Klasse <classname>Zend_Soap_Autodiscover</classname> nicht für
                sich selbst als SOAP Server agiert. Sie erzeugt nur den WSDL und bietet Ihn jedem an der
                auf die URL zugreift auf die geschaut wird.
            </para>

            <para>
                Als Endpunkt der SOAP URI verwendet es den Standard
                <code>'http://'  .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code>, der aber mit der
                <code>setUri()</code> Funktion oder dem Contructor Parameter der
                <classname>Zend_Soap_AutoDiscover</classname> Klasse verändert werden kann. Der Endpunkt muß an
                einen <classname>Zend_Soap_Server</classname> übergeben werden der auf die Anfragen hört.
            </para>

            <para>
                <programlisting role="php"><![CDATA[
if(isset($_GET['wsdl'])) {
    $autodiscover = new Zend_Soap_AutoDiscover();
    $autodiscover->setClass('HelloWorldService');
    $autodiscover->handle();
} else {
    // zeigt auf diese aktuelle Datei
    $soap = new Zend_Soap_Server("http://example.com/soap.php?wsdl");
    $soap->setClass('HelloWorldService');
    $soap->handle();
}
]]></programlisting>
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.class">
        <title>Automatische Erkennung von Klassen</title>

        <para>
            Wenn eine Klasse verwendet wird um SOAP Server Funktionalitäten anzubieten, dann sollte die selbe
            Klasse an <classname>Zend_Soap_AutoDiscover</classname> für die WSDL Erzeugung übergeben werden:
            <programlisting role="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->setClass('My_SoapServer_Class');
$autodiscover->handle();
]]></programlisting>
        </para>

        <para>
            Die folgenden Regeln werden wärend der WSDL Erzeugung verwendet:
            <itemizedlist>
                <listitem>
                    <para>Erzeugtes WSDL beschreibt einen RPC srtigen Web Service.</para>
                </listitem>
                <listitem>
                    <para>Klassen Namen werden als Name des Web Services verwendet der beschrieben wird.</para>
                </listitem>
                <listitem>
                    <para>
                        <code>'http://'  .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code> wird als URI
                        verwendet wenn das WSDL standardmäßig vorhanden ist und kann über die
                        <code>setUri()</code> Methode überschrieben werden.
                    </para>
                    <para>
                         Es wird auch als Ziel Namespace für alle Service bezogenen Namen verwendet (inklusive
                         der beschriebenen komplexen Typen).
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Klassen Methoden werden in einen
                        <ulink url="http://www.w3.org/TR/wsdl#_porttypes">Port Typ</ulink> übernommen.
                    </para>
                    <para>
                        <code>$className . 'Port'</code> wird als Port Typ Name verwendet.
                    </para>
                </listitem>
                <listitem>
                    <para>Jede Klassen Methode wird als korrespondierende Port Operation registriert.</para>
                </listitem>
                <listitem>
                    <para>Jeder Methoden Prototyp erzeugt korrespondierende Anfrage/Antwort Nachrichten.</para>
                    <para>Eine Methode kann verschiedene Prototypen haben wenn einige Parameter der Methode
                    optional sind.</para>
                </listitem>
            </itemizedlist>
        </para>

        <note>
            <title>Wichtig!</title>
            <para>
                WSDL Autodiscovery verwendet PHP Docblocks die vom Entwickler angeboten werden um die Parameter
                und Return Typen zu erkennen. Faktisch ist das, für skalare Typen, der einzige Weg um die
                Parameter Typen zu erkennen und für Return Typen ist das der einzige Weg um Sie zu erkennen.
            </para>
            <para>
                Das bedeutet, das Anbieten von richtigen und komplett detailierten Docblocks ist nicht nur
                beste Praxis, sondern wird für das erkunden der Klasse benötigt.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.functions">
        <title>Funktionen für Autodiscovery</title>

        <para>
            Wenn ein Set von Funktionen verwendet wird um SOAP Server Funktionalität anzubieten, dann sollte
            das selbe Set mit <classname>Zend_Soap_AutoDiscovery</classname> für die WSDL Erzeugung verwendet werden:
            <programlisting role="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->addFunction('function1');
$autodiscover->addFunction('function2');
$autodiscover->addFunction('function3');
...
$autodiscover->handle();
]]></programlisting>
        </para>

        <para>
            Die folgenden Regeln werden wärend der WSDL Erzeugung verwendet:
            <itemizedlist>
                <listitem>
                    <para>Ein erstelltes WSDL beschreibt einen RPC artigen Web Service.</para>
                </listitem>
                <listitem>
                    <para>
                        Der aktuelle Skriptname wird als Name des Web Services verwendet der beschrieben wird.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>'http://'  .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code> wird als URI
                        verwendet wo WSDL vorhanden ist.
                    </para>
                    <para>
                        Wird als Ziel Namespace für alle Service bezogenen Namen verwendet (inklusive der
                        beschriebenen komplexen Typen).
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Funktionen werden in einem <ulink url="http://www.w3.org/TR/wsdl#_porttypes">Port Typ</ulink>
                        verbunden.
                    </para>
                    <para>
                        <code>$functionName . 'Port'</code> wird als Port Typ Name verwendet.
                    </para>
                </listitem>
                <listitem>
                    <para>Jede Funktion wird als korrespondierende Port Operation registriert.</para>
                </listitem>
                <listitem>
                    <para>Jeder Funktions Prototyp erzeugt eine korrespondierende Anfrage/Antwort Nachricht.</para>
                    <para>Funktionen können verschiedene Prototypen haben wenn einige Parameter der Methode
                    optional sind.</para>
                </listitem>
            </itemizedlist>
        </para>

        <note>
            <title>Wichtig!</title>
            <para>
                WSDL Autodiscovery verwendet PHP Docblocks die vom Entwickler angeboten werden um die Parameter
                und Return Typen zu erkennen. Faktisch ist das, für skalare Typen, der einzige Weg um die
                Parameter Typen zu erkennen und für Return Typen ist das der einzige Weg um Sie zu erkennen.
            </para>
            <para>
                Das bedeutet, das Anbieten von richtigen und komplett detailierten Docblocks ist nicht nur
                beste Praxis, sondern wird für das erkunden der Klasse benötigt.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.datatypes">
        <title>Automatische Erkennung. Datentypen</title>

        <para>
            Eingabe/Ausgabe Datentypen werden in Netzwerk Service Typen konvertiert indem das folgende
            Mapping verwendet wird:

            <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  (See: <xref linkend="zend.soap.wsdl.types.add_complex" />)
                        <footnote>
                            <para>
                                <classname>Zend_Soap_AutoDiscover</classname> wird mit der
                                <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> Klasse 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> implementieren oder
                                einen String mit dem Nmaen der Klasse. Um Backwards Compatibility mit
                                <code>$extractComplexType</code> zu gewährleisten werden boolsche
                                Variablen wie in <classname>Zend_Soap_Wsdl</classname> geparst. Siehe das
                                <link linkend="zend.soap.wsdl.types.add_complex"><classname>Zend_Soap_Wsdl</classname>
                                Manual über das Hinzufügen von komplexen</link> Typen für weitere Informationen.
                            </para>
                        </footnote>.
                    </para>
                </listitem>
                <listitem>
                    <para>type[] oder object[] (z.B. int[]) &lt;-&gt; basieren auf der Strategie der komplexen Typen</para>
                </listitem>
                <listitem>
                    <para>PHP Void &lt;-&gt; Leerer Typ.</para>
                </listitem>
                <listitem>
                    <para>Wenn der Typ aus irgendeinem Grund keinem dieser Typen entspricht, 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 einen Service.
        </para>
    </sect2>

    <sect2 id="zend.soap.autodiscovery.wsdlstyles">
        <title>Stile für das Binden von WSDL</title>

        <para>
            WSDL bietet verschiedene Transport Mechanismen und Stile. Das beeinträchtigt die
            <code>soap:binding</code> und <code>soap:body</code> Tags in der Binding Sektion von WSDL.
            Unterschiedliche Clients haben unterschiedliche Anforderungen wie diese Optionen wirklich
            arbeiten. Hierfür kann man die Stile setzen bevor man eine <code>setClass</code> oder
            <code>addFunction</code> Methode auf der AutoDiscovery Klasse ausführt.
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
// Standard ist 'use' => 'encoded' und
// 'encodingStyle' => 'http://schemas.xmlsoap.org/soap/encoding/'
$autodiscover->setOperationBodyStyle(
                    array('use' => 'literal',
                          'namespace' => 'http://framework.zend.com')
                );

// Standard ist 'style' => 'rpc' und
// 'transport' => 'http://schemas.xmlsoap.org/soap/http'
$autodiscover->setBindingStyle(
                    array('style' => 'document',
                          'transport' => 'http://framework.zend.com')
                );
...
$autodiscover->addFunction('myfunc1');
$autodiscover->handle();
]]></programlisting>
        </para>
    </sect2>
</sect1>