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

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

    <sect2 id="zend.soap.autodiscovery.introduction">
        <title>AutoDiscovery Einführung</title>

        <para>
            Die <acronym>SOAP</acronym> Funktionalität die im Zend Framework implementiert ist, ist
            dazu gedacht alle benötigten Schritte für die <acronym>SOAP</acronym> Kommunikation
            einfacher zu gestalten.
        </para>

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

        <para>
            Es gibt drei Konfigurationen für <acronym>SOAP</acronym> Anwendungen wo Zend Framework
            verwendet werden kann:

            <orderedlist>
                <listitem>
                    <simpara>
                        SOAP Server <acronym>PHP</acronym> Anwendung &lt;---&gt;
                        <acronym>SOAP</acronym> Client <acronym>PHP</acronym> Anwendung
                    </simpara>
                </listitem>

                <listitem>
                    <simpara>
                        <acronym>SOAP</acronym> Server nicht-PHP Anwendung &lt;---&gt;
                        <acronym>SOAP</acronym> Client <acronym>PHP</acronym> Anwendung
                    </simpara>
                </listitem>

                <listitem>
                    <simpara>
                        SOAP Server <acronym>PHP</acronym> Anwendung &lt;---&gt;
                        <acronym>SOAP</acronym> Client nicht-PHP Anwendung
                    </simpara>
                </listitem>
            </orderedlist>
        </para>

        <para>
            Wir müssen immer wissen, welche Funktionalität vom <acronym>SOAP</acronym> Server
            angeboten wird um mit Ihm zu arbeiten. <ulink
                url="http://www.w3.org/TR/wsdl">WSDL</ulink> wird verwendet um die Netzwerk Service
            <acronym>API</acronym> 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
            <acronym>API</acronym> mit schon existierendem WSDL.
        </para>

        <para>
            Aber dieses Problem kann durch WSDL Autogeneration gelöst werden. Eine Vorbedingung
            dafür ist ein <acronym>SOAP</acronym> Server Autodiscovery. Es erzeugt ein Objekt
            ähnlich dem Objekt das in der <acronym>SOAP</acronym> 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 <acronym>SOAP</acronym>
            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 <acronym>PHP</acronym> 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.
        </para>

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

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

        <para>
            Wenn man auf die erzeugte WSDL Datei zugreifen muß um Sie in eine Datei oder als
            <acronym>XML</acronym> String abzuspeichern, kann man die Funktionen
            <methodname>dump($filename)</methodname> oder <methodname>toXml()</methodname> verwenden
            welche 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
                <acronym>SOAP</acronym> 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 <acronym>SOAP</acronym> 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>

            <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>
        </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:
        </para>

        <programlisting language="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->setClass('My_SoapServer_Class');
$autodiscover->handle();
]]></programlisting>

        <para>
            Die folgenden Regeln werden während 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 <acronym>URI</acronym> 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 <acronym>PHP</acronym> 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:
        </para>

        <programlisting language="php"><![CDATA[
$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->addFunction('function1');
$autodiscover->addFunction('function2');
$autodiscover->addFunction('function3');
...
$autodiscover->handle();
]]></programlisting>

        <para>
            Die folgenden Regeln werden während 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 <acronym>URI</acronym> 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 <acronym>PHP</acronym> 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>
                        <acronym>PHP</acronym> Klasse &lt;-&gt; basierend auf der Strategie der
                        komplexen Typen (Siehe <link
                            linkend="zend.soap.wsdl.types.add_complex">diesen Abschnitt</link>)

                        <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 <varname>$extractComplexType</varname>
                                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>

        <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>
    </sect2>
</sect1>