Introduction au module Apache mod_rewrite

Langues Disponibles: en | + fr

+ +

Ce document est un complément à la documentation de référence du module +mod_rewrite. Il décrit les concepts de base dont la +connaissance est nécessaire pour l'utilisation de +mod_rewrite. D'autres documents entrent d'avantage dans +les détails, mais celui-ci devrait aider le débutant à se mouiller les +pieds. +

Introduction
Expressions rationnelles
Les bases des règles de réécriture
Drapeaux de réécriture
Conditions de réécriture
Tables de réécriture
Fichiers .htaccess

Voir aussi

Introduction

Le module Apache mod_rewrite est un module puissant +et sophistiqué qui permet la réécriture des URLs. Grâce à lui, vous +pouvez effectuer quasiment tous les types de réécriture d'URLs dont vous +avez besoin. Il est cependant assez complexe, et peut paraître +intimidant au débutant. Certains ont aussi tendance à traiter les +règles de réécriture comme des incantations magiques, et à les utiliser +sans vraiment comprendre leur manière d'agir.

+ +

Ce document a pour ambition d'être suffisamment explicite pour +permettre la compréhension, et non la copie en aveugle, de ce qui suit. +

+ +

Gardez à l'esprit que de nombreuses tâches de manipulation d'URLs +courantes n'ont pas besoin de la puissance et de la complexité de +mod_rewrite. Pour les tâches simples, voir +mod_alias et la documentation sur la Mise en correspondance des URLs avec le +système de fichiers.

+ +

Enfin, avant de procéder, assurez-vous d'avoir configuré la directive +RewriteLog. Bien que ce +fichier journal puisse contenir une quantité impressionnante d'informations, +il s'avère indispensable pour le débogage des problèmes avec la +configuration de mod_rewrite, car il vous indiquera +exactement la manière dont chaque règle est traitée.

+ +

On ne peut pas utiliser la directive RewriteLog dans les fichiers +.htaccess, car elle doit être définie au niveau du fichier +de configuration du serveur principal.

Expressions rationnelles

+ +

mod_rewrite utilise le vocabulaire des Expressions rationnelles compatibles Perl. +Ce document n'a pas pour prétention d'être une référence détaillée des +expressions rationnelles. A cet effet, nous recommandons les pages de manuel de PCRE, la page de manuel des +expressions rationnelles Perl, et l'ouvrage Mastering +Regular Expressions, by Jeffrey Friedl.

+ +

Dans ce document, nous avons pour but de vous fournir suffisamment de +vocabulaire des expressions rationnelles pour vous mettre le pied à +l'étrier, sans être dépassé, en espérant que les directives RewriteRule vous apparaîtront comme des +formules scientifiques, plutôt que comme des incantations magiques.

+ +

Vocabulaire des expressions rationnelles

+ +

Vous trouverez dans ce qui suit le minimum à connaître pour être en +mesure d'écrire des expressions rationnelles et des règles RewriteRule. Ceci ne représente +certainement pas un vocabulaire des expressions rationnelles complet, +mais constitue un bon point de départ, et devrait vous aider à +déchiffrer les expressions rationnelles simples, et à écrire vos propres +expressions.

+ + + + + + + + + + + + + + + + + + + + + + + + + +

Motif	Signification	Exemple
`.`	Correspond à tout caractère unique +	`c.t` correspondra à `cat`, +`cot`, `cut`, etc.
`+`	Répète le caractère de correspondance +précédent une ou plusieurs fois	`a+` correspond à `a`, `aa`, +`aaa`, etc.
`*`	Répète le caractère de correspondance +précédent zéro ou plusieurs fois	`a*` correspond à tout ce à quoi correspond +`a+`, mais correspond aussi à la chaîne vide.
`?`	Rend la correspondance optionnelle.	+`colou?r` correspondra à `color` et `colour`.
`^`	Appelé ancrage, correspond au début de la +chaîne	`^a` correspond à une chaîne qui commence par +`a`
`$`	L'autre ancrage, correspond à la fin de +la chaîne.	`a$` correspond à une chaîne qui se termine par +`a`.
`( )`	Regroupe plusieurs caractères en une +seule entité, et conserve une correspondance à des fins d'utilisation +dans une référence arrière.	`(ab)+` +correspond à `ababab` - à savoir, le `+` +s'applique au groupe. +Pour plus de détails sur les références arrières, voir ci-dessous.
`[ ]`	Une classe de caractères - correspond à +un des caractères de la classe	`c[uoa]t` correspond à `cut`, +`cot` ou `cat`.
`[^ ]`	Négation de la classe de caractères - +correspond à tout caractère ne faisant pas partie de la classe	`c[^/]t` correspond à `cat` ou +`c=t` mais pas à `c/t`

+ +

Avec mod_rewrite, le caractère ! peut +préfixer une expression rationnelle afin d'en exprimer la négation. +Autrement dit, une chaîne ne correspondra que si elle ne correspond pas +à l'expression située après le !.

+ + + +

Disponibilité des références +arrières dans les expressions rationnelles

+ +

Vous devez vous souvenir d'une chose importante : chaque fois + que vous utilisez des parenthèses dans un Modèle ou dans + un des modèles de conditions, des références arrières + sont créées en interne et peuvent être rappelées via les chaînes + $N et %N (voir ci-dessous). Ces + références sont disponibles lors de la création des chaînes de + Substitution et des Chaînes de test. La figure 2 + montre à quels endroits les références arrières sont suceptibles + d'être développées.

+ +

+ [Pas affichable sans support des images]
+ Figure 2: Le cheminement d'une référence arrière à + travers une règle. +

+ + +

Les bases des règles de réécriture

Une règle de réécriture RewriteRule est constituée de trois +arguments séparés par des espaces. Les arguments sont :

Modèle: le modèle des URLs auxquelles la règle doit +s'appliquer;
Substitution: vers quoi la requête correspondante doit être +transformée;
[drapeaux]: options affectant la requête réécrite.

+ +

Le Modèle est toujours une expression +rationnelle comparée au chemin de l'URL de la requête entrante (la +partie située après le nom d'hôte mais avant tout point d'interrogation +qui indique le début d'une chaîne de requête).

+ +

La chaîne de Substitution peut, quant à elle, être de +trois types :

+ +

Un chemin complet du système de fichiers vers une ressource: +
+RewriteRule ^/jeux.* /usr/local/jeux/web +
+
Ceci peut faire correspondre une requête à toute localisation voulue de +votre système de fichiers, un peu comme la directive Alias.
+
Un chemin web vers une ressource: +
+RewriteRule ^/foo$ /bar +
+
Si la directive DocumentRoot a +pour valeur /usr/local/apache2/htdocs, cette règle va faire +correspondre les requêtes pour http://example.com/foo au +chemin /usr/local/apache2/htdocs/bar.
+
Une URL absolue: +
+RewriteRule ^/produits/vues$ http://site2.exemple.com/voirproduits.html [R] +
+
Ceci informe le client qu'il doit effectuer une nouvelle requête vers +l'URL spécifiée.
+

+ +

La chaîne de Substitution peut aussi contenir des +références arrières vers des parties du chemin d'URL entrant +correspondant au Modèle. Considérons ce qui suit :

+RewriteRule ^/produits/(.*)/view$ /var/web/produitsdb/$1 +

La variable $1 sera remplacée par tout texte +correspondant à l'expression située entre les parenthèses dans le +Modèle. Par exemple, une requête pour +http://example.com/produits/r14df/vue correspondra au +chemin /var/web/produitsdb/r14df.

+ +

S'il y a plus d'une expression entre parenthèses, elle seront +accessibles selon leur ordre d'apparition via les variables +$1, $2, $3, etc...

+ + +

Drapeaux de réécriture

Le comportement d'une règle RewriteRule peut être modifié par la +présence d'un ou plusieurs drapeaux en fin de règle. Par exemple, les +conditions de correspondance d'une règle peuvent être rendues +insensibles à la casse par la présence du drapeau [NC] : +

+RewriteRule ^puppy.html petitchien.html [NC] +

+ +

Pour une liste des drapeaux disponibles, leurs significations, et des +exemples, voir le document Drapeaux de +réécriture.

+ +

Conditions de réécriture

Il est possible d'utiliser une ou plusieurs directives RewriteCond pour restreindre les types +de requêtes auxquelles devra s'appliquer la règle RewriteRule suivante. Le premier +argument est une variable décrivant une caractéristique de la requête, +le second argument est une expression rationnelle +qui doit correspondre à la variable, et un troisième argument optionnel +est une liste de drapeaux qui modifient la manière dont la +correspondance est évaluée.

+ +

Par exemple, pour renvoyer toutes les requêtes en provenance d'une +certaine tranche d'adresses IP vers un autre serveur, vous pouvez +utiliser :

+RewriteCond %{REMOTE_ADDR} ^10\.2\. +RewriteRule (.*) http://intranet.exemple.com$1 +

+ +

Si vous spécifiez plus d'une directive RewriteCond, ces directives +doivent toutes être satisfaites pour que la règle RewriteRule suivante s'applique. Par exemple, +pour interdire les requêtes qui contiennent le mot "hack" dans la chaîne +de requête, sauf si elles contiennent aussi un cookie contenant le mot +"go", vous pouvez utiliser :

+RewriteCond %{QUERY_STRING} hack +RewriteCond %{HTTP_COOKIE} !go +RewriteRule .* - [F] +

Notez que le point d'exclamation indique une correspondance négative +; ainsi, la règle n'est appliquée que si le cookie ne contient pas "go"

+ +

Les correspondances dans les expressions rationnelles contenues dans +les directives RewriteCond +peuvent constituer des parties de la chaîne de Substitution +de la règle RewriteRule via +les variables %1, %2, etc... Par +exemple, ce qui suit va diriger la requête vers un répertoire différent +en fonction du nom d'hôte utilisé pour accéder au site :

+RewriteCond %{HTTP_HOST} (.*) +RewriteRule ^/(.*) /sites/%1/$1 +

Si la requête concernait http://example.com/foo/bar, +alors %1 contiendrait example.com et +$1 contiendrait foo/bar.

+ + + +

Tables de réécriture

Voir la directive +RewriteMap.

Fichiers .htaccess

+ +

La réécriture est en général définie au niveau de la configuration du +serveur principal (en dehors de toute section <Directory>) ou dans une section <VirtualHost>. Il s'agit là de la +manière la plus simple de mettre en oeuvre la réécriture et nous la +recommandons. Il est possible, cependant, de mettre en oeuvre la +réécriture au sein d'une section <Directory> ou d'un fichier .htaccess ; ce type de +configuration est cependant plus complexe. Cette technique est appelée +réécriture par répertoire.

+ +

La principale différence avec les réécritures au niveau du serveur réside +dans le fait que le préfixe du chemin du répertoire contenant le fichier +.htaccess est supprimé avant la mise en correspondance dans +la règle RewriteRule. De +plus, on doit utiliser la directive RewriteBase pour s'assurer que la +requête est correctement mise en correspondance.

+ +