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.

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.

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

1. Modèle: le modèle des URLs auxquelles la règle doit s'appliquer;
2. Substitution: vers quoi la requête correspondante doit être transformée;
3. [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).

Figure 2 : Syntaxe de la directive RewriteRule.

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

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

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] :

Pour une liste des drapeaux disponibles, leurs significations, et des exemples, voir le document Drapeaux 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 :

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 :

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 :

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

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.

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.