# Zend_Uri

## Aperçu

`Zend_Uri` est un composant destiné à aider à la manipulation et à la validation des Uniform Resource Identifiers (URIs). `Zend_Uri` existe dans le but d'aider les autres composants de Zend Framework tels que `Zend_Http_Client` mais peut aussi être utilisé comme composant individuel.

Les URIs 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. `Zend_Uri` 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 `Zend_Uri_<scheme>`, où `<scheme>` est le nom du schéma utilisé, tout en minuscule, sauf la première lettre. Une exception à cette règle est HTTPS, qui est aussi géré par `Zend_Uri_Http`.

## Créer un nouvel URI

`Zend_Uri` fabriquera un URI vierge, si seul son schéma est passé à `Zend_Uri::factory()`.

### Créer un URI avec `Zend_Uri::factory()`

    // Création d'un URI vierge
    $uri = Zend_Uri::factory('http');

    // $uri instanceof Zend_Uri_Http

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

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

### Creating a New Custom-Class URI

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 `Zend_Uri::factory()` 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.

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

#### Creating a URI using a custom class

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

## Manipuler un URI existant

Pour manipuler un URI existant, passez le entièrement à `Zend_Uri::factory()`.

### Manipuler un URI existant avec `Zend_Uri::factory()`

    // Passez l'URI complet à la fabrique
    $uri = Zend_Uri::factory('http://www.zend.com');

    // $uri instanceof Zend_Uri_Http

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

## Validation d'URI

La méthode `Zend_Uri::check()` peut être utilisée pour valider un URI.

### Validation d'URI avec `Zend_Uri::check()`

    // Valide si l'URI passé est bien formé
    $valid = Zend_Uri::check('http://uri.en.question');

    // $valid est TRUE ou FALSE

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

### Autoriser les caractères "imprudents" dans les URIs

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

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

#### Autoriser les caractères spéciaux dans les URIs

    // 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));

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

## Méthodes communes

Toute instance sous-classe de `Zend_Uri` (par exemple `Zend_Uri_Http`) possède plusieurs méthodes utiles :

### Retrouver le schéma d'un URI

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

#### Récupérer le schéma d'un objet `Zend_Uri_*`

    $uri = Zend_Uri::factory('http://www.zend.com');

    $scheme = $uri->getScheme();  // "http"

La méthode `getScheme()` retourne une chaîne de caractères.

### Récupérer l'URI entier

#### Récupérer l'URI entier depuis un objet `Zend_Uri_*`

    $uri = Zend_Uri::factory('http://www.zend.com');

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

La méthode `getUri()` retourne une chaîne de caractères représentant l'URI entier.

### Valider l'URI

`Zend_Uri::factory()` 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é.

#### Valider un objet `Zend_Uri_*`

    $uri = Zend_Uri::factory('http://www.zend.com');

    $isValid = $uri->valid();  // TRUE

La méthode `valid()` propose une façon de vérifier si l'URI est toujours valide.