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

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

    <sect2 id="zend.uri.overview">
        <title>Aperçu</title>

        <para>
            <classname>Zend_Uri</classname> est un composant destiné à aider à la manipulation
            et à la validation des <ulink url="http://www.w3.org/Addressing/"> Uniform Resource
            Identifiers</ulink> (URIs). <classname>Zend_Uri</classname> existe dans le but d'aider
            les autres composants de Zend Framework tels que <classname>Zend_Http_Client</classname>
            mais peut aussi être utilisé comme composant individuel.
        </para>

        <para>
            Les <acronym>URI</acronym>s commence toujours avec la définition de leur schéma, suivie d'un
            double-points. La construction des différents schémas variant beaucoup, une fabrique est
            à votre disposition. <classname>Zend_Uri</classname> possède une fabrique qui retourne
            des instances sous-classes d'elle même. Chaque sous classe possède le nom du schéma dans
            son nom, comme <classname>Zend_Uri_&lt;scheme&gt;</classname>, où
            <code>&lt;scheme&gt;</code> est le nom du schéma utilisé, tout en minuscule, sauf la
            première lettre. Une exception à cette règle est <acronym>HTTPS</acronym>, qui est aussi géré par
            <classname>Zend_Uri_Http</classname>.
        </para>
    </sect2>

    <sect2 id="zend.uri.creation">
        <title>Créer un nouvel URI</title>

        <para>
            <classname>Zend_Uri</classname> fabriquera un <acronym>URI</acronym> vierge, si seul son schéma est
            passé à <methodname>Zend_Uri::factory()</methodname>.
        </para>

        <example id="zend.uri.creation.example-1">
            <title>Créer un URI avec <methodname>Zend_Uri::factory()</methodname></title>

            <programlisting language="php"><![CDATA[
// Création d'un URI vierge
$uri = Zend_Uri::factory('http');

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

        <para>
            Pour créer un <acronym>URI</acronym> à partir de rien, passez simplement le schéma à
            <methodname>Zend_Uri::factory()</methodname> <footnote>
                <para>
                    Actuellement, <classname>Zend_Uri</classname> ne supporte que les schémas
                    intégrés <acronym>HTTP</acronym> et <acronym>HTTPS</acronym>
                </para>
            </footnote>. Si un schéma non supporté lui est passé ou aucune classe n'est spécifié,
            une <classname>Zend_Uri_Exception</classname> sera levée.
        </para>

        <para>
            Si un schéma ou <acronym>URI</acronym> fourni est supporté,
            <methodname>Zend_Uri::factory()</methodname> retournera une sous-classe d'elle-même
            spécialisée pour le schéma à créer.
        </para>

        <sect3>
            <title>Creating a New Custom-Class URI</title>

            <para>
                Starting from Zend Framework 1.10.5, you can specify a custom class to be
                used when creating the Zend_Uri instance, as a second parameter to the
                <methodname>Zend_Uri::factory()</methodname> method.
                This enables you to subclass Zend_Uri and create your own custom URI classes,
                and instantiate new URI objects based on your own custom classes.
            </para>

            <para>
                The 2nd parameter passed to <methodname>Zend_Uri::factory()</methodname> must
                be a string with the name of a class extending <classname>Zend_Uri</classname>.
                The class must either be alredy-loaded, or loadable using <methodname>Zend_Loader::loadClass()</methodname> -
                that is, it must follow the Zend Framework class and file naming conventions, and
                must be in your include_path.
            </para>

            <example id="zend.uri.creation.custom.example-1">
                <title>Creating a URI using a custom class</title>

                <programlisting language="php"><![CDATA[
// Create a new 'ftp' URI based on a custom class
$ftpUri = Zend_Uri::factory(
    'ftp://user@ftp.example.com/path/file',
    'MyLibrary_Uri_Ftp'
);

// $ftpUri is an instance of MyLibrary_Uri_Ftp, which is a subclass of Zend_Uri
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.uri.manipulation">
        <title>Manipuler un URI existant</title>

        <para>
            Pour manipuler un <acronym>URI</acronym> existant, passez le entièrement à
            <methodname>Zend_Uri::factory()</methodname>.
        </para>

        <example id="zend.uri.manipulation.example-1">
            <title>Manipuler un URI existant avec
            <methodname>Zend_Uri::factory()</methodname></title>

            <programlisting language="php"><![CDATA[
// Passez l'URI complet à la fabrique
$uri = Zend_Uri::factory('http://www.zend.com');

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

        <para>
            L'URI sera alors analysé et validé. S'il s'avère être invalide, une
            <classname>Zend_Uri_Exception</classname> sera envoyée immédiatement. Sinon,
            <methodname>Zend_Uri::factory()</methodname> retournera une sous classe d'elle-même qui
            spécialisera le schéma manipulé.
        </para>
    </sect2>

    <sect2 id="zend.uri.validation">
        <title>Validation d'URI</title>

        <para>
            La méthode <methodname>Zend_Uri::check()</methodname> peut être utilisée pour
            valider un <acronym>URI</acronym>.
        </para>

        <example id="zend.uri.validation.example-1">
            <title>Validation d'URI avec <methodname>Zend_Uri::check()</methodname></title>

            <programlisting language="php"><![CDATA[
// Valide si l'URI passé est bien formé
$valid = Zend_Uri::check('http://uri.en.question');

// $valid est TRUE ou FALSE
]]></programlisting>
        </example>

        <para>
            <methodname>Zend_Uri::check()</methodname> retourne un simple booléen, ce qui est
            plus pratique que de passer par <methodname>Zend_Uri::factory()</methodname> et de
            capturer les exceptions.
        </para>

        <sect3 id="zend.uri.validation.allowunwise">
            <title>Autoriser les caractères "imprudents" dans les URIs</title>

            <para>
                Par défaut, <classname>Zend_Uri</classname> n'acceptera pas les caractères
                suivants, définis par la <acronym>RFC</acronym> comme "imprudents" et invalide : <code>"{", "}", "|",
                "\", "^", "`"</code>. Cependant, de nombreuses implémentations acceptent ces
                caractères comme valides.
            </para>

            <para>
                <classname>Zend_Uri</classname> peut être paramètré pour accepter ces
                caractères "imprudents" en réglant l'option "allow_unwise" à <constant>TRUE</constant> en
                utilisant la méthode <methodname>Zend_Uri::setConfig()</methodname> :
            </para>

            <example id="zend.uri.validation.allowunwise.example-1">
                <title>Autoriser les caractères spéciaux dans les URIs</title>

                <programlisting language="php"><![CDATA[
// Normalement, ceci devrait retourner false :
$valid = Zend_Uri::check('http://example.com/?q=this|that'); // Contient le symbole '|'

// Cependant, vous pouvez autorise les caractères "imprudents"
Zend_Uri::setConfig(array('allow_unwise' => true));
$valid = Zend_Uri::check('http://example.com/?q=this|that'); // Retournera 'true'

// Initialiser 'allow_unwise' à sa valeur par défaut FALSE
Zend_Uri::setConfig(array('allow_unwise' => false));
]]></programlisting>
            </example>

            <note>
                <para>
                    <methodname>Zend_Uri::setConfig()</methodname> paramètre les options de
                    configuration de manière globale. Il est recommandé de réinitialiser l'option
                    <code>allow_unwise</code> à <constant>FALSE</constant> comme dans l'exemple ci-dessus, à
                    moins d'être certain de vouloir utiliser les caractères "imprudents" de manière
                    globale.
                </para>
            </note>
        </sect3>
    </sect2>

    <sect2 id="zend.uri.instance-methods">
        <title>Méthodes communes</title>

        <para>
            Toute instance sous-classe de <classname>Zend_Uri</classname> (par exemple
            <classname>Zend_Uri_Http</classname>) possède plusieurs méthodes utiles :
        </para>

        <sect3 id="zend.uri.instance-methods.getscheme">
            <title>Retrouver le schéma d'un URI</title>

            <para>
                Le schéma d'un <acronym>URI</acronym> est la partie précédent les double-points (:). Par exemple,
                le schéma de <code>http://www.zend.com</code> est <code>http</code>.
            </para>

            <example id="zend.uri.instance-methods.getscheme.example-1">
                <title>Récupérer le schéma d'un objet <classname>Zend_Uri_*</classname></title>

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

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

            <para>La méthode <methodname>getScheme()</methodname> retourne une chaîne de caractères.</para>
        </sect3>

        <sect3 id="zend.uri.instance-methods.geturi">
            <title>Récupérer l'URI entier</title>

            <example id="zend.uri.instance-methods.geturi.example-1">
                <title>Récupérer l'URI entier depuis un objet
                <classname>Zend_Uri_*</classname></title>

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

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

            <para>
                La méthode <methodname>getUri()</methodname> retourne une chaîne de caractères
                représentant l'URI entier.
            </para>
        </sect3>

        <sect3 id="zend.uri.instance-methods.valid">
            <title>Valider l'URI</title>

            <para>
                <methodname>Zend_Uri::factory()</methodname> validera de toute façon
                systématiquement l'URI qui lui est passé en paramètre. Par contre, l'URI peut
                devenir invalide après, s'il est modifié.
            </para>

            <example id="zend.uri.instance-methods.valid.example-1">
                <title>Valider un objet <classname>Zend_Uri_*</classname></title>

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

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

            <para>
                La méthode <methodname>valid()</methodname> propose une façon de vérifier si l'URI est
                toujours valide.
            </para>
        </sect3>
    </sect2>
</sect1>