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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17133 -->
<!-- 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 <methodname>handle()</methodname> erzeugt die WSDL Datei und postet Sie an den
            Browser.

            <programlisting language="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 <methodname>dump($filename)</methodname>
            oder <methodname>toXml()</methodname> 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 <methodname>setUri()</methodname> 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 language="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 language="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 <methodname>setUri()</methodname> 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 language="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 language="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>