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é le niveau de +journalisation de mod_rewrite à un des niveaux de trace +via la directive LogLevel. Bien que +ceci risque de vous submerger sous une énorme quantité d'informations, +le débogage des problèmes avec la configuration de +mod_rewrite est à ce prix car vous verrez alors +exactement comment chaque règle est traitée.

+ +

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`.
`\`	Echappe le caractère suivant	`\.` correspondra à `.` (le point) et non à + tout caractère unique comme expliqué plus haut
`^`	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 de la chaîne de substitution d'une directive + RewriteRule ou de la + chaîne de test d'une directive RewriteCond.

Les captures dans les modèles de directives RewriteRule sont paradoxalement + disponibles dans toutes les directives RewriteCond qui précèdent, car + les expressions des directives RewriteRule sont évaluées avant + les conditions individuelles.

+ +

La figure 1 montre à quels endroits les + références arrières sont suceptibles + d'être développées, et illustre le flux des comparaisons + effectuées par les règles RewriteRule et + RewriteCond. Dans les chapitres suivants, nous examinerons comment + utiliser ces références arrières, donc ne vous affolez pas si + elles vous paraissent un peu exotiques au premier abord.

+ +

+ Flux des comparaisons effectuées par les règles RewriteRule et RewriteCond
+ Figure 1 : Le cheminement d'une référence arrière à + travers une règle.
+ Dans cet exemple, une requête pour /test/1234 serait + transformée en + /admin.foo?page=test&id=1234&host=admin.example.com. +

+ + +

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 une expression +rationnelle. Au sein de la première règle de réécriture, ou jusqu'à +ce qu'une substitution survienne, elle est 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 paramètres de +requête) ou, dans un contexte de répertoire, au chemin de la +requête relativement au répertoire pour lequel la +règle est définie. Lorsqu'une substitution a eu lieu, les +règles suivantes effectuent leurs comparaisons par rapport à la valeur +substituée.

+ +

+
+ Figure 2 : Syntaxe de la directive RewriteRule. +

+ +

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

+ +

1. Un chemin complet du système de fichiers vers une ressource

RewriteRule "^/games" "/usr/local/games/web/puzzles.html"

+ +

Ceci peut faire correspondre une requête à toute localisation voulue de +votre système de fichiers, un peu comme la directive Alias.

2. Un chemin web vers une ressource

RewriteRule "^/games$" "/puzzles.html"

+ +

Si la directive DocumentRoot a +pour valeur /usr/local/apache2/htdocs, cette règle va faire +correspondre les requêtes pour http://example.com/games au +chemin /usr/local/apache2/htdocs/puzzles.html.

3. Une URL absolue

RewriteRule "^/produits/vues$" "http://site2.example.com/voirproduits.html" [R]

+ +

Ceci informe le client qu'il doit effectuer une nouvelle requête vers +l'URL spécifiée.

+ +

Notez que 1 et 2 +possèdent exactement la même syntaxe. Par contre, dans le cas de +1, le niveau racine du chemin cible (par exemple +/usr/) existe dans le système de fichiers, alors que ce n'est pas +le cas avec 2 (par exemple, il n'y a pas de répertoire +/bar/ au niveau de la racine du système de fichiers).

+ +

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.

+ +

+
+ Figure 3 : Syntaxe de la directive RewriteCond +

+ + +

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.example.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

+ +

La directive RewriteMap +permet en quelque sorte de faire appel à une fonction externe pour +effectuer la réécriture à votre place. Tout ceci est décrit plus en +détails dans la Documentation +supplémentaire sur 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.

+ +