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().

Example #1 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() ^[1] Zend_UriHTTPHTTPS . Si un schéma non supporté lui est passé, 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.

Manipuler un URI existant

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

Example #2 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.

Example #3 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() :

Example #4 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));

Note: 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.

Example #5 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

Example #6 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é.

Example #7 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.