intro.xml.fr revision 1093a264c81aa1041581ab059905fb8f7cdfc5e2
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- English Revision : 815946 -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<manualpage metafile="intro.xml.meta">
<parentdocument href="./">Rewrite</parentdocument>
<title>Introduction au module Apache mod_rewrite</title>
<summary>
<p>Ce document est un complément à la <a
href="/mod/mod_rewrite.html">documentation de référence</a> du module
<module>mod_rewrite</module>. Il décrit les concepts de base dont la
connaissance est nécessaire pour l'utilisation de
<module>mod_rewrite</module>. D'autres documents entrent d'avantage dans
les détails, mais celui-ci devrait aider le débutant à se mouiller les
pieds.
</p>
</summary>
module</a></seealso>
courants</a></seealso>
problèmes plus complexes</a></seealso>
<section id="introduction"><title>Introduction</title>
<p>Le module Apache <module>mod_rewrite</module> 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.</p>
<p>Ce document a pour ambition d'être suffisamment explicite pour
permettre la compréhension, et non la copie en aveugle, de ce qui suit.
</p>
<p>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
<module>mod_rewrite</module>. Pour les tâches simples, voir
<module>mod_alias</module> et la documentation sur la <a
href="/urlmapping.html">Mise en correspondance des URLs avec le
système de fichiers</a>.</p>
<p>Enfin, avant de procéder, assurez-vous d'avoir configuré la directive
<directive module="mod_rewrite">RewriteLog</directive>. 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 <module>mod_rewrite</module>, car il vous indiquera
exactement la manière dont chaque règle est traitée.</p>
<note>
<p>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.</p>
</note>
</section>
<section id="regex"><title>Expressions rationnelles</title>
<p>mod_rewrite utilise le vocabulaire des <a
href="http://pcre.org/">Expressions rationnelles compatibles Perl</a>.
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 <a
href="http://perldoc.perl.org/perlre.html">page de manuel des
expressions rationnelles Perl</a>, et l'ouvrage <a
href="http://www.oreilly.com/catalog/regex2/index.html">Mastering
Regular Expressions, by Jeffrey Friedl</a>.</p>
<p>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 <directive
module="mod_rewrite">RewriteRule</directive> vous apparaîtront comme des
formules scientifiques, plutôt que comme des incantations magiques.</p>
<section id="regexvocab"><title>Vocabulaire des expressions rationnelles</title>
<p>Vous trouverez dans ce qui suit le minimum à connaître pour être en
mesure d'écrire des expressions rationnelles et des règles <directive
module="mod_rewrite">RewriteRule</directive>. 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.</p>
<table>
<tr>
<th>Motif</th>
<th>Signification</th>
<th>Exemple</th>
</tr>
<tr><td><code>.</code></td><td>Correspond à tout caractère unique
<code>cot</code>, <code>cut</code>, etc.</td></tr>
<tr><td><code>+</code></td><td>Répète le caractère de correspondance
précédent une ou plusieurs fois</td>
<td><code>a+</code> correspond à <code>a</code>, <code>aa</code>,
<code>aaa</code>, etc.</td></tr>
<tr><td><code>*</code></td><td>Répète le caractère de correspondance
précédent zéro ou plusieurs fois</td>
<td><code>a*</code> correspond à tout ce à quoi correspond
<code>a+</code>, mais correspond aussi à la chaîne vide.</td></tr>
<tr><td><code>?</code></td><td>Rend la correspondance optionnelle.</td><td>
<code>colou?r</code> correspondra à <code>color</code> et <code>colour</code>.</td>
</tr>
<tr><td><code>^</code></td><td>Appelé ancrage, correspond au début de la
chaîne</td>
<td><code>^a</code> correspond à une chaîne qui commence par
<code>a</code></td></tr>
<tr><td><code>$</code></td><td>L'autre ancrage, correspond à la fin de
la chaîne.</td>
<td><code>a$</code> correspond à une chaîne qui se termine par
<code>a</code>.</td></tr>
<tr><td><code>( )</code></td><td>Regroupe plusieurs caractères en une
seule entité, et conserve une correspondance à des fins d'utilisation
dans une référence arrière.</td>
<td><code>(ab)+</code>
correspond à <code>ababab</code> - à savoir, le <code>+</code>
s'applique au groupe.
Pour plus de détails sur les références arrières, voir <a
href="#InternalBackRefs">ci-dessous</a>.</td></tr>
<tr><td><code>[ ]</code></td><td>Une classe de caractères - correspond à
un des caractères de la classe</td>
<td><code>c[uoa]t</code> correspond à <code>cut</code>,
<code>cot</code> ou <code>cat</code>.</td></tr>
<tr><td><code>[^ ]</code></td><td>Négation de la classe de caractères -
correspond à tout caractère ne faisant pas partie de la classe</td>
<td><code>c[^/]t</code> correspond à <code>cat</code> ou
<code>c=t</code> mais pas à <code>c/t</code></td></tr>
</table>
<p>Avec <module>mod_rewrite</module>, le caractère <code>!</code> 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 <code>!</code>.</p>
</section>
<section id="InternalBackRefs"><title>Disponibilité des références
arrières dans les expressions rationnelles</title>
<p>Vous devez vous souvenir d'une chose importante : chaque fois
que vous utilisez des parenthèses dans un <em>Modèle</em> ou dans
un des <em>modèles de conditions</em>, des références arrières
sont créées en interne et peuvent être rappelées via les chaînes
<code>$N</code> et <code>%N</code> (voir ci-dessous). Ces
références sont disponibles lors de la création des chaînes de
<em>Substitution</em> et des <em>Chaînes de test</em>. La figure 2
montre à quels endroits les références arrières sont suceptibles
d'être développées.</p>
<p class="figure">
height="179" alt="[Pas affichable sans support des images]" /><br />
<dfn>Figure 2:</dfn> Le cheminement d'une référence arrière à
travers une règle.
</p>
</section>
</section>
<section id="rewriterule"><title>Les bases des règles de réécriture</title>
<p>Une règle de réécriture <directive
module="mod_rewrite">RewriteRule</directive> est constituée de trois
arguments séparés par des espaces. Les arguments sont :</p>
<ol>
<li><var>Modèle</var>: le modèle des URLs auxquelles la règle doit
s'appliquer;</li>
<li><var>Substitution</var>: vers quoi la requête correspondante doit être
transformée;</li>
<li><var>[drapeaux]</var>: options affectant la requête réécrite.</li>
</ol>
<p>Le <var>Modèle</var> est toujours une <a href="#regex">expression
rationnelle</a> 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).</p>
<p>La chaîne de <var>Substitution</var> peut, quant à elle, être de
trois types :</p>
<dl>
<dt>Un chemin complet du système de fichiers vers une ressource</dt>
<dd>
<example>
</example>
<p>Ceci peut faire correspondre une requête à toute localisation voulue de
votre système de fichiers, un peu comme la directive <directive
module="mod_alias">Alias</directive>.</p>
</dd>
<dt>Un chemin web vers une ressource</dt>
<dd>
<example>
RewriteRule ^/foo$ /bar
</example>
<p>Si la directive <directive module="core">DocumentRoot</directive> a
</dd>
<dt>Une URL absolue</dt>
<dd>
<example>
</example>
<p>Ceci informe le client qu'il doit effectuer une nouvelle requête vers
l'URL spécifiée.</p>
</dd>
</dl>
<p>La chaîne de <var>Substitution</var> peut aussi contenir des
<em>références arrières</em> vers des parties du chemin d'URL entrant
correspondant au <var>Modèle</var>. Considérons ce qui suit :</p>
<example>
</example>
<p>La variable <code>$1</code> sera remplacée par tout texte
correspondant à l'expression située entre les parenthèses dans le
<var>Modèle</var>. Par exemple, une requête pour
<p>S'il y a plus d'une expression entre parenthèses, elle seront
accessibles selon leur ordre d'apparition via les variables
<code>$1</code>, <code>$2</code>, <code>$3</code>, etc...</p>
</section>
<section id="flags"><title>Drapeaux de réécriture</title>
<p>Le comportement d'une règle <directive
module="mod_rewrite">RewriteRule</directive> 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 <code>[NC]</code> :
</p>
<example>
RewriteRule ^puppy.html petitchien.html [NC]
</example>
<p>Pour une liste des drapeaux disponibles, leurs significations, et des
exemples, voir le document <a href="rewrite_flags.html">Drapeaux de
réécriture</a>.</p>
</section>
<section id="rewritecond"><title>Conditions de réécriture</title>
<p>Il est possible d'utiliser une ou plusieurs directives <directive
module="mod_rewrite">RewriteCond</directive> pour restreindre les types
de requêtes auxquelles devra s'appliquer la règle <directive
module="mod_rewrite">RewriteRule</directive> suivante. Le premier
argument est une variable décrivant une caractéristique de la requête,
le second argument est une <a href="#regex">expression rationnelle</a>
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.</p>
<p>Par exemple, pour renvoyer toutes les requêtes en provenance d'une
certaine tranche d'adresses IP vers un autre serveur, vous pouvez
utiliser :</p>
<example>
RewriteCond %{REMOTE_ADDR} ^10\.2\.<br />
RewriteRule (.*) http://intranet.exemple.com$1
</example>
<p>Si vous spécifiez plus d'une directive <directive
module="mod_rewrite">RewriteCond</directive>, ces directives
doivent toutes être satisfaites pour que la règle <directive
module="mod_rewrite">RewriteRule</directive> 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 :</p>
<example>
RewriteCond %{QUERY_STRING} hack<br />
RewriteCond %{HTTP_COOKIE} !go<br />
RewriteRule .* - [F]
</example>
<p>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"</p>
<p>Les correspondances dans les expressions rationnelles contenues dans
les directives <directive module="mod_rewrite">RewriteCond</directive>
peuvent constituer des parties de la chaîne de <var>Substitution</var>
de la règle <directive module="mod_rewrite">RewriteRule</directive> via
les variables <code>%1</code>, <code>%2</code>, 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 :</p>
<example>
RewriteCond %{HTTP_HOST} (.*)<br />
RewriteRule ^/(.*) /sites/%1/$1
</example>
</section>
<section id="rewritemap"><title>Tables de réécriture</title>
<p>Voir la directive
<directive module="mod_rewrite">RewriteMap</directive>.</p>
</section>
<section id="htaccess"><title>Fichiers .htaccess</title>
<p>La réécriture est en général définie au niveau de la configuration du
serveur principal (en dehors de toute section <directive type="section"
module="core">Directory</directive>) ou dans une section <directive
type="section" module="core">VirtualHost</directive>. 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 <directive type="section"
module="core">Directory</directive> ou d'un fichier <a
configuration est cependant plus complexe. Cette technique est appelée
réécriture par répertoire.</p>
<p>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
<code>.htaccess</code> est supprimé avant la mise en correspondance dans
la règle <directive module="mod_rewrite">RewriteRule</directive>. De
plus, on doit utiliser la directive <directive
module="mod_rewrite">RewriteBase</directive> pour s'assurer que la
requête est correctement mise en correspondance.</p>
</section>
</manualpage>