repo_zf1/documentation/manual/de/module_specs/Zend_Service_StrikeIron-Overview.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17173 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.strikeiron">
    <title>Zend_Service_StrikeIron</title>

    <para>
        <classname>Zend_Service_StrikeIron</classname> bietet einen PHP 5 Clienten zu den Web
        Services von StrikeIron. Siehe die folgenden Sektionen:
    </para>

    <para>
        <itemizedlist>
            <listitem><para><xref linkend="zend.service.strikeiron" /></para></listitem>
        </itemizedlist>
        <itemizedlist>
            <listitem>
                <para><xref linkend="zend.service.strikeiron.bundled-services" /></para>
            </listitem>
        </itemizedlist>
        <itemizedlist>
            <listitem>
                <para><xref linkend="zend.service.strikeiron.advanced-uses" /></para>
            </listitem>
        </itemizedlist>
    </para>

    <sect2 id="zend.service.strikeiron.overview">
        <title>Übersicht</title>

        <para>
          <ulink url="http://www.strikeiron.com">StrikeIron</ulink> bietet hunderte von
          kommerziellen Daten Services ("Daten als Service") wie z.B. Online Steuer, Wärungsraten,
          Aktienwerte, Geocodes, Globale Adresen Prüfung, Yallow/White Pages, MapQuest
          Fahranleitungen, Dun &amp; Bradstreet Business Credit Prüfungen, und viele, viele mehr.
        </para>

        <para>
          Jedes StrikeIron Web Service bietet eine standard SOAP (und REST) API, die die Integration
          und Handhabung mehrerer Services sehr einfach macht. StrikeIron managt auch die
          Kundenverrechnung für alle Services in einem einzelnen Account, was es für Lösungsanbieter
          perfekt macht. Man kann mit freien WebServices unter <ulink
              url="http://www.strikeiron.com/sdp">http://www.strikeiron.com/sdp</ulink> starten.
        </para>

        <para>
          Die Services von StrikeIron können schon alleine durch die
          <ulink url="http://us.php.net/soap">PHP 5 SOAP Erweiterung</ulink> verwendet werden.
          Trotzdem bietet die Verwendung von StrikeIron auf diesem Weg kein ideales PHP-artiges
          Interface. Die <classname>Zend_Service_StrikeIron</classname> Componente bietet einen
          leichtgewichtigen Layer aufbauend auf der SOAP Erweiterung für die Arbeit mit den Services
          von StrikeIron auf einem bequemeren und PHP-artigeren Weg.
        </para>

        <note>
          <para>
            Die PHP 5 SOAP Erweiterung muß installiert und aktiviert sein um
            <classname>Zend_Service_StrikeIron</classname> zu verwenden.
          </para>
        </note>

        <para>
          Die <classname>Zend_Service_StrikeIron</classname> Komponente bietet:

          <itemizedlist>
            <listitem>
              <para>
                Einen einzigen Punkt für die Konfiguration der eigenen Authentifizierungsdaten für
                StrikeIron die durch alle StrikeIron Services hinweg verwendet werden können.
              </para>
            </listitem>

            <listitem>
              <para>
                Einen standardtisierten Weg um die eigenen StrikeIron Einwahl Informationen wie den
                Lizenz Status und die Anzahl von verbleibenden Hits zu einem Service zu erhalten.
              </para>
            </listitem>

            <listitem>
              <para>
                Die Möglichkeit jedes StrikeIron Service von deren WSDL aus zu verwenden ohne eine
                PHP Wrapper Klasse zu erstellen, und die Option einen Wrapper für ein bequemeres
                Interface zu erstellen.
              </para>
            </listitem>

            <listitem>
              <para>
                Wrapper für drei populäre StrikeIron Services.
              </para>
            </listitem>
          </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.service.strikeiron.registering">
      <title>Registrieren mit StrikeIron</title>
      <para>
        Bevor man mit <classname>Zend_Service_StrikeIron</classname> beginnen kann, muß man sich
        zuerst für einen StrikeIron Entwickler Zugang <ulink
            url="http://strikeiron.com/Register.aspx">registrieren</ulink>.
      </para>

      <para>
        Nach der Registrierung erhält man einen StrikeIron Benutzernamen und ein Passwort. Diese
        werden Verwendet wenn man sich auf StrikeIron verbindet indem man
        <classname>Zend_Service_StrikeIron</classname> verwendet.
      </para>

      <para>
        Man muß sich auch für StrikeIron's Super Data Pack Web Service
        <ulink url="http://www.strikeiron.com/ProductDetail.aspx?p=257">anmelden</ulink>.
      </para>

      <para>
        Beide Schritte der Registrierung sind frei und können relativ schnell mit der WebSeite von
        StrikeIron durchgeführt werden.
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.getting-started">
      <title>Beginnen</title>
      <para>
        Sobald man sich für einen StrikeIron Account
        <ulink url="http://strikeiron.com/Register.aspx">registriert</ulink> und für das <ulink
            url="http://www.strikeiron.com/ProductDetail.aspx?p=257">Super Data Pack</ulink>
        angemeldet hat, ist man für die Benutzung von <classname>Zend_Service_StrikeIron</classname>
        bereit.
      </para>

      <para>
        StrikeIron besteht aus hunderten von verschiedenen WebServices.
        <classname>Zend_Service_StrikeIron</classname> kann mit vielen dieser Services verwendet
        werden bietet aber nur für drei von Ihnen unterstützte Wrapper:
      </para>

      <itemizedlist>
        <listitem>
          <para>
              <link linkend="zend.service.strikeiron.bundled-services.zip-code-information">ZIP Code
              Informationen</link>
          </para>
        </listitem>
        <listitem>
          <para>
              <link linkend="zend.service.strikeiron.bundled-services.us-address-verification">US
              Addressen Prüfung</link>
          </para>
        </listitem>
        <listitem>
          <para>
              <link linkend="zend.service.strikeiron.bundled-services.sales-use-tax-basic">Verkaufs-
                  &amp; Steuergrundlagen</link>
          </para>
        </listitem>
      </itemizedlist>

      <para>
        Die Klasse <classname>Zend_Service_StrikeIron</classname> bietet einen einfachen Web um die
        eigenen Account Informationen von StrikeIron und andere Option im Konstruktor zu
        spezifizieren. Sie bietet auch eine Factory Methode die Clients für StrikeIron Services
        zurück gibt:

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'your-username',
                                                'password' => 'your-password'));

$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));
]]></programlisting>
      </para>

      <para>
        Die <methodname>getService()</methodname> Methode gibt einen Client für irgendein StrikeIron
        Service zurück das durch den Namen seiner PHP Wrapper Klasse definiert wurde. In diesem
        Fall, referiert der Name <code>SalesUseTaxBasic</code> zu der Wrapper Klasse
        <classname>Zend_Service_StrikeIron_SalesUseTaxBasic</classname>. Wrapper sind für drei
        Services inkludiert und in <link linkend="zend.service.strikeiron.bundled-services">Bundled
            Services</link> beschrieben.
      </para>

      <para>
        Die <methodname>getService()</methodname> Methode kann auch einen Client für ein StrikeIron
        Service zurückgeben das bisher keinen PHP Wrapper hat. Das wird in <link
            linkend="zend.service.strikeiron.advanced-uses.services-by-wsdl">Services durch WSDL
            verwenden</link> erklärt.
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.making-first-query">
      <title>Die erste Abfrage durchführen</title>

      <para>
        Sobald die <methodname>getService()</methodname> Methode verwendet wurde um einen Clienten
        für ein gewünschtes StrikeIron Service zu erhalten, kann dieser Client verwendet werden
        durch Aufruf seiner Methoden ganz wie jedes andere PHP Objekt.

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'your-username',
                                                'password' => 'your-password'));

// Einen Client für das Verkaufs / Steuerbasis Service erhalten
$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));

// Steuerrate für Ontario, Canada abfragen
$rateInfo = $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
echo $rateInfo->province;
echo $rateInfo->abbreviation;
echo $rateInfo->GST;
]]></programlisting>

        Im obigen Beispiel wird die <methodname>getService()</methodname> Methode verwendet um einen
        Client zum <link
            linkend="zend.service.strikeiron.bundled-services.sales-use-tax-basic">Verkaufs- &amp;
            Steuergrundlagen</link> Service zu erhalten. Das Client Objekt wird in
        <varname>$taxBasic</varname> gespeichert.
      </para>

      <para>
        Die <methodname>getTaxRateCanada()</methodname> Methode wird dann vom Service aus
        aufgerufen. Ein assoziatives Array wird verwendet um der Methode Schlüssel Parameter
        anzugeben. Das ist der Weg auf dem alle StrikeIron Methoden aufgerufen werden.
      </para>

      <para>
        Das Ergebnis von <methodname>getTaxRateCanada()</methodname> wird in
        <varname>$rateInfo</varname> gespeichert und hat Eigenschaften wie <code>province</code> und
        <constant>GST</constant>.
      </para>

      <para>
        Viele der Services von StrikeIron sind so einfach wie das obige Beispiel. Siehe
        <link linkend="zend.service.strikeiron.bundled-services">mitgelieferte Services</link> für
        detailierte Informationen zu drei der Services von StrikeIron.
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.examining-results">
      <title>Ergebnisse betrachten</title>
      <para>
        Wenn man Services von StrikeIron lernt oder versucht fehler zu beheben, ist es oft nützlich
        das Ergebnis das von einem Methodenaufruf zurückgegeben wird auszugeben. Das Ergebnis wird
        immer ien Objekt sein das eine Instanz von
        <classname>Zend_Service_StrikeIron_Decorator</classname> ist. Das ist ein kleines <ulink
            url="http://en.wikipedia.org/wiki/Decorator_pattern">Dekorator</ulink> Objekt das die
        Ergebnisse des Methoden Aufrufs ummantelt.
      </para>

      <para>
        Der einfachste Weg ein Ergebnis vom Service zu betrachten ist die Verwendung der eingebauten
        PHP Methode <ulink url="http://www.php.net/print_r">print_r()</ulink>:

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'your-username',
                                                'password' => 'your-password'));

$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));

$rateInfo = $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
print_r($rateInfo);
?>

Zend_Service_StrikeIron_Decorator Object
(
    [_name:protected] => GetTaxRateCanadaResult
    [_object:protected] => stdClass Object
        (
            [abbreviation] => ON
            [province] => ONTARIO
            [GST] => 0.06
            [PST] => 0.08
            [total] => 0.14
            [HST] => Y
        )
)
]]></programlisting>
      </para>

      <para>
        In der obigen Ausgabe sehen wir das der Dekorator (<varname>$rateInfo</varname>) ein Objekt
        ummantelt das <code>GetTaxRateCanadaResult</code> heißt, und das Ergebnis des Aufrufes von
        <methodname>getTaxRateCanada()</methodname> ist.
      </para>

      <para>
        Das bedeutet das <varname>$rateInfo</varname> öffentliche Eigenschaften wie
        <code>abbreviation</code>, <code>province</code>, und <constant>GST</constant> hat. Dieser
        werden z.B. mit <code>$rateInfo->province</code> aufgerufen.
      </para>

      <tip>
        <para>
          Die Eigenschaften von StrikeIron Ergebnissen beginnen oft mit einem Großbuchstaben wie
          <code>Foo</code> oder <code>Bar</code> wobei die meisten PHP Objekt Eigenschaften
          normalerweise mit einem Kleinbuchstaben wie <code>foo</code> oder <code>bar</code>
          beginnen. Der Dekorator wird diesen Eingriff automatisch durchführen sodas eine
          Eigenschaft von <code>Foo</code> als <code>foo</code> gelesen werden kann.
        </para>
      </tip>

      <para>
        Wenn man jemals das originale Objekt oder seinen Namen vom Dekorator heraus benötigt können
        die Methoden <methodname>getDecoratedObject()</methodname> und
        <methodname>getDecoratedObjectName()</methodname> verwendet werden.
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.handling-errors">
      <title>Fehler handhaben</title>
      <para>
        Die vorigen Beispiel sind naiv, was bedeutet das keine Handhabung von Fehlern gezeigt wurde.
        Es ist möglich das StrikeIron einen Fehler zurückgibt wärend des Aufrufs einer Methode.
        Selbst fehlerhafte Account Daten oder ein abgelaufener Zugang kann StrikeIron dazu bringen
        einen Fehler zu werfen.
      </para>

      <para>
        Eine Ausnahme wird geworfen wenn solch ein Fehler auftritt. Man sollte das berücksichtigen
        und solche Ausnahmen fangen wenn man Methodenaufrufe zu einem Service durchführt:

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'your-username',
                                                'password' => 'your-password'));

$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));

try {

  $taxBasic->getTaxRateCanada(array('province' => 'ontario'));

} catch (Zend_Service_StrikeIron_Exception $e) {

  // Fehler handhaben für Events wie Verbindungsprobleme oder Account Probleme

}
]]></programlisting>
        Die geworfenen Ausnahmen werden immer
        <classname>Zend_Service_StrikeIron_Exception</classname> sein.
      </para>

      <para>
        Es ist wichtig die Unterschiede zwischen Ausnahmen und normalen fehlgeschlagenen
        Methodenaufrufen zu verstehen. Ausnahmen treten für <emphasis>ausgenommene</emphasis>
        Verhaltenweisen auf, wie z.B. ein Netzwerk das abstürzt oder ein abgelaufener Account.
        Fehlgeschlagene Methodenaufrufe die häufig auftreten, wie z.B. wenn
        <methodname>getTaxRateCanada()</methodname> die angegebene <code>province</code> nicht
        findet, führen nicht dazu das Ausnahmen geworfen werden.
      </para>

      <note>
        <para>
          Jedesmal wenn ein Methodenaufruf zu einem Service von StrikeIron durchgeführt wird, sollte
          das Ergebnis Objekt auf Gültigkeit geprüft werden und man sollte genauso vorsehen eine
          Ausnahme zu fangen.
        </para>
      </note>

      <para><!-- inkludiert für Leerzeichen --></para>
    </sect2>

    <sect2 id="zend.service.strikeiron.checking-subscription">
      <title>Den eigenen Account prüfen</title>
      <para>
        StrikeIron bietet viele verschiedene Services. Einige von Ihnen sind kostenlos, eine sind
        auf einer Testbasis vorhanden, und einige sind nur für zahlende Kunden. Wenn StrikeIron
        verwendet wird, ist es wichtig auf den Account Status für die Services zu achten die man
        verwendet und diesen regelmäßig zu prüfen.
      </para>

      <para>
        Jeder StrikeIron Client, der von der <code>getService</code> Methode zurückgegeben wird, hat
        die Möglichkeit den Account Status für diesen Service zu prüfen indem die
        <methodname>getSubscriptionInfo()</methodname> Methode dieses Clients verwendet wird:

        <programlisting language="php"><![CDATA[
// Einen Client für das Verkaufs / Steuerbasis Service erhalten
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'your-username',
                                                'password' => 'your-password'));

$taxBasic = $strikeIron->getService(array('class => 'SalesUseTaxBasic'));

// Prüfe die noch möglichen Zugriffe für das Verkaufs- & Steuerbasis Service
$subscription = $taxBasic->getSubscriptionInfo();
echo $subscription->remainingHits;
]]></programlisting>
      </para>

      <para>
        Die <methodname>getSubscriptionInfo()</methodname> Methode gibt ein Objekt zurück, das
        typischerweise eine <code>remainingHits</code> Eigenschaft hat. Es ist wichtig den Status,
        für jeden Service der verwendet wird, zu prüfen. Wenn ein Methodenaufruf zu StrikeIron
        gemacht wird, nachdem die möglichen Zugriffe aufgebraucht wurden, wird eine Ausnahme
        auftreten.
      </para>

      <para>
        Das Prüfen des Accounts zu einem Service benötigt keinen Zugriff (hit) auf diesen Server.
        Jedes Mal wenn irgendein Methodenaufruf zu einem Service gemacht wurde, wird die Anzahl der
        möglichen Zugriffe gecached und dieser gecachete Wert wird durch
        <methodname>getSubscriptionInfo()</methodname> zurückgegeben ohne das noch einmal mit dem
        Service eine Verbindung aufgebaut werden muß. Um
        <methodname>getSubscriptionInfo()</methodname> dazu zu bringen seinen Cache auszuschalten
        und die Account Informationen nochmals abzufragen, kann
        <methodname>getSubscriptionInfo(true)</methodname> verwendet werden.
      </para>
    </sect2>
</sect1>