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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17172 -->
<!-- Reviewed: no -->
<sect1 id="zend.uri.chapter">
  <title>Zend_Uri</title>

  <sect2 id="zend.uri.overview">
    <title>Überblick</title>

    <para>
        <classname>Zend_Uri</classname> ist eine Komponente, die das Verändern und Validieren von
        <ulink url="http://www.w3.org/Addressing/">Uniform Resource Identifiers</ulink> (URIs)
        unterstützt. <classname>Zend_Uri</classname> existiert hauptsächlich, um andere Komponenten
        wie z.B. <classname>Zend_Http_Client</classname> zu unterstützen, aber ist auch als
        eigenständiges Hilfsmittel nützlich.
    </para>

    <para>
        URIs beginnen immer mit einem Schema, gefolgt von einem Doppelpunkt. Der Aufbau der vielen
        unterschiedlichen Schemata unterscheidet sich erheblich. Die <classname>Zend_Uri</classname>
        stellt eine Fabrik (Factory) bereit, die eine Unterklasse von sich selber zurück gibt, die
        auf das entsprechende Schema spezialisiert ist. Diese Unterklasse heißt
        <classname>Zend_Uri_&lt;scheme&gt;</classname>, wobei <code>&lt;scheme&gt;</code> das Schema
        in Kleinbuchstaben mit einem Großbuchstaben am Anfang darstellt. Eine Ausnahme dieser Regel
        ist HTTPS, das auch von <classname>Zend_Uri_Http</classname> verarbeitet wird.
    </para>
  </sect2>

  <sect2 id="zend.uri.creation">
    <title>Eine neue URI erstellen</title>

    <para>
        <classname>Zend_Uri</classname> erstellt eine neue URI von Grund auf, wenn nur das Schema an
        <methodname>Zend_Uri::factory()</methodname> übergeben wurde.
    </para>

    <example id="zend.uri.creation.example-1">
      <title>Erstellen einer neuen URI mit Zend_Uri::factory()</title>

      <programlisting language="php"><![CDATA[
// Um eine neue URI von Grund auf zu erstellen, übergebe nur das Schema.
$uri = Zend_Uri::factory('http');

// $uri instanceof Zend_Uri_Http
]]></programlisting>
    </example>

    <para>
        Um eine neue URI von Grund auf zu erstellen, übergibt man nur das Schema an
        <methodname>Zend_Uri::factory()</methodname><footnote><para>Zum Zeitpunkt des Schreiben
        unterstützt <classname>Zend_Uri</classname> nur HTTP und HTTPS Schemata</para></footnote>.
        Wenn eine nicht unterstütztes Schema übergeben wird, wird eine
        <classname>Zend_Uri_Exception</classname> ausgeworfen.
    </para>

    <para>
        Wenn das Schema oder die übergebene URI unterstützt wird, gibt
        <methodname>Zend_Uri::factory()</methodname> eine Unterklasse von sich selbst zurück, die
        auf das zu erstellende Schema spezialisiert ist.
    </para>
  </sect2>

  <sect2 id="zend.uri.manipulation">
    <title>Verändern einer vorhandenen URI</title>

    <para>
        Um eine vorhandene URI zu verändern, übergibt man die komplett URI an
        <methodname>Zend_Uri::factory()</methodname>.
    </para>

    <example id="zend.uri.manipulation.example-1">
      <title>Verändern einer vorhandenen URI mit Zend_Uri::factory()</title>

      <programlisting language="php"><![CDATA[
// Um eine vorhandene URI zu verändern, übergibt man sie.
$uri = Zend_Uri::factory('http://www.zend.com');

// $uri instanceof Zend_Uri_Http
]]></programlisting>
    </example>

    <para>
        Die URI wird analysiert und validiert. Wenn sie als ungültig erkannt wird, wird sofort eine
        <classname>Zend_Uri_Exception</classname> geworfen. Andernfalls gibt
        <methodname>Zend_Uri::factory()</methodname> eine Unterklasse von sich selbst zurück, die
        auf das zu verändernde Schema spezialisiert ist.
    </para>
  </sect2>

  <sect2 id="zend.uri.validation">
    <title>URI Validierung</title>

    <para>
        Die <methodname>Zend_Uri::check()</methodname> Methode kann verwendet werden, wenn nur das
        Validieren einer vorhandenen URI benötigt wird.
    </para>

    <example id="zend.uri.validation.example-1">
      <title>URI Validierung mit Zend_Uri::check()</title>

      <programlisting language="php"><![CDATA[
// Überprüfe, ob eine übergebe URI wohlgeformt ist
$valid = Zend_Uri::check('http://uri.in.question');

// $valid ist TRUE für eine valide URI, andernfalls FALSE
]]></programlisting>
    </example>

    <para>
        <methodname>Zend_Uri::check()</methodname> gibt ein Boolean zurück, was einfacher ist, als
        <methodname>Zend_Uri::factory()</methodname> zu verwenden und eine Ausnahme abzufangen.
    </para>

    <sect3 id="zend.uri.validation.allowunwise">
        <title>"Unwise" Zeichen in URIs erlauben</title>

        <para>
            Standardmäßig wird <classname>Zend_Uri</classname> die folgenden Zeichen nicht
            akzepzieren, da Sie durch die RFC als "unwise" definiert und deshalb ungültig sind:
            <code>"{", "}", "|", "\", "^", "`"</code>. Trotzdem, akzeptieren viele Implementierungen
            diese Zeichen als Gültig.
        </para>

        <para>
            <classname>Zend_Uri</classname> kann so eingestellt werden das es diese "unwise" Zeichen akzeptiert indem die
            'allow_unwise' Option auf ein boolsches TRUE gesetzt wird, durch Verwendung der
            <classname>Zend_Uri</classname>::setConfig() Methode:
        </para>

        <example id="zend.uri.validation.allowunwise.example-1">
            <title>Spezielle Zeichen in URIs erlauben</title>
            <programlisting language="php"><![CDATA[
// Enthält das '|' Symbol
// Normal würde das false zurückgeben:
$valid = Zend_Uri::check('http://example.com/?q=this|that');

// Trotzdem kann man diese "unwise" Zeichen erlauben
Zend_Uri::setConfig(array('allow_unwise' => true));
// Gibt 'true' zurück
$valid = Zend_Uri::check('http://example.com/?q=this|that');

// Setzt den Wert 'allow_unwise' auf das Standardmäßige FALSE zurück
Zend_Uri::setConfig(array('allow_unwise' => false));
]]></programlisting>
        </example>

        <note><para>
            <methodname>Zend_Uri::setConfig()</methodname> setzt Konfigurationsoptionen global. Es
            wird empfohlen die 'allow_unwise' Option auf 'false' zurückzusetzen wie im obigen
            Beispiel, solange man unwise Zeichen immer global erlauben will.
        </para></note>
    </sect3>
  </sect2>

  <sect2 id="zend.uri.instance-methods">
    <title>Allgemeine Instanzmethoden</title>

    <para>
        Jede Instant einer <classname>Zend_Uri</classname> Unterklasse (z.B.
        <classname>Zend_Uri_Http</classname>) hat verschiedene Instanzmethoden, die für die
        Verwendung mit jeglicher URI nützlich sind.
    </para>

    <sect3 id="zend.uri.instance-methods.getscheme">
      <title>Das Schema der URI erhalten</title>

      <para>
          Das Schema der URI ist der Teil der URI vor dem Doppelpunkt. Zum Beispiel ist
          <code>http</code> das Schema von <code>http://www.zend.com</code>.
      </para>

      <example id="zend.uri.instance-methods.getscheme.example-1">
        <title>Das Schema eines Zend_Uri_* Objektes erhalten</title>

        <programlisting language="php"><![CDATA[
$uri = Zend_Uri::factory('http://www.zend.com');

$scheme = $uri->getScheme();  // "http"
]]></programlisting>
      </example>

      <para>
          Die <methodname>getScheme()</methodname> Instanzmethode gibt nur das Schema des URI
          Objektes zurück.
      </para>

    </sect3>

    <sect3 id="zend.uri.instance-methods.geturi">
      <title>Die komplette URI erhalten</title>

      <example id="zend.uri.instance-methods.geturi.example-1">
        <title>Die komplette URI eines Zend_Uri_* Objektes erhalten</title>

        <programlisting language="php"><![CDATA[
$uri = Zend_Uri::factory('http://www.zend.com');

echo $uri->getUri();  // "http://www.zend.com"
]]></programlisting>
      </example>

      <para>
          Die <methodname>getUri()</methodname> Methode gibt den String zurück, der die komplette
          URI repräsentiert.
      </para>
    </sect3>

    <sect3 id="zend.uri.instance-methods.valid">
      <title>Die URI validieren</title>

      <para>
          <methodname>Zend_Uri::factory()</methodname> validiert immer jede übergebene URI und wird
          keine <classname>Zend_Uri</classname> Unterklasse instantieren, wenn die übergebene URI
          ungültig ist. Dennoch ist es nach der Instanzierung der <classname>Zend_Uri</classname>
          Unterklasse für eine neue oder eine bestehende URI möglich, dass die URI später ungültig
          wird, nachdem sie verändert worden ist.
      </para>

      <example id="zend.uri.instance-methods.valid.example-1">
        <title>Ein Zend_Uri_* Object validieren</title>

        <programlisting language="php"><![CDATA[
$uri = Zend_Uri::factory('http://www.zend.com');

$isValid = $uri->valid();  // TRUE
]]></programlisting>
      </example>

      <para>
          Die <methodname>valid()</methodname> Instanzmethode ermöglicht es, das URI Objekt auf
          Gültigkeit zu überprüfen.
      </para>
    </sect3>

  </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->