1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
|
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
<!-- English Revision : 832080 -->
<!-- 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
http://www.apache.org/licenses/LICENSE-2.0
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="flags.xml.meta">
<parentdocument href="./">Rewrite</parentdocument>
<title>Les drapeaux du module Apache mod_rewrite</title>
<summary>
<p>Ce document décrit les drapeaux disponibles dans la directive
<directive module="mod_rewrite">RewriteRule</directive>, en fournissant
des explications détaillées et des exemples. Vous n'y trouverez pas
une liste exhaustive de tous les drapeaux disponibles, c'est pourquoi
vous devez aussi consulter la documentation de référence.</p>
</summary>
<seealso><a href="../mod/mod_rewrite.html">Documentation du module</a></seealso>
<seealso><a href="tech.html">Détails techniques</a></seealso>
<seealso><a href="rewrite_guide.html">Guide de réécriture - exemples
utiles</a></seealso>
<seealso><a href="rewrite_guide_advanced.html">Guide de réécriture
avancée - exemples utiles avancés</a></seealso>
<section id="introduction"><title>Introduction</title>
<p>Le comportement des directives <directive
module="mod_rewrite">RewriteRule</directive> peut être modifié par un ou
plusieurs drapeaux. Les drapeaux sont situés en fin de règle, entourés
de crochets, et séparés le cas échéant par des virgules.</p>
<example>
RewriteRule modèle cible [drapeau1,drapeau2,drapeau3]
</example>
<p>Les drapeaux ont tous une forme courte, comme <code>CO</code>, ainsi
qu'une forme longue, comme <code>cookie</code>. Certains drapeaux
peuvent avoir un ou plusieurs arguments. Les drapeaux sont insensibles à
la casse.</p>
</section>
<section id="flags"><title>Les drapeaux</title>
<p>Chaque drapeau possède une forme longue et une forme courte. Bien que
la forme courte soit la plus couramment utilisée, nous vous recommandons
de vous familiariser avec les drapeaux sous leur forme longue, afin de
bien mémoriser ce que chaque drapeau est supposé faire.</p>
<p>Chaque drapeau disponible est présenté ici, avec un exemple
d'utilisation.</p>
<section id="flag_b"><title>B</title>
<p>Avec le drapeau [B], la directive <directive
module="mod_rewrite">RewriteRule</directive> échappe les caractères
non-alphanumériques avant d'appliquer la transformation.</p>
</section>
<section id="flag_c"><title>C|chain</title>
<p>Le drapeau [C] ou [chain] indique que la règle <directive
module="mod_rewrite">RewriteRule</directive> est chaînée avec la
suivante. Autrement dit, si la règle s'applique, elle est traitée
normalement et passe le contrôle à la règle suivante. Par contre, si
elle ne s'applique pas, la règle suivante, ainsi que toutes les règles
chaînées qui suivent, seront sautées.</p>
</section>
<section id="flag_co"><title>CO|cookie</title>
<p>Le drapeau [CO], ou [cookie], vous permet de définir un cookie
lorsqu'une règle <directive module="mod_rewrite">RewriteRule</directive>
s'applique. Il possède cinq arguments dont trois sont obligatoires et
deux optionnels.</p>
<p>Vous devez déclarer un nom et une valeur pour définir le cookie,
ainsi que le domaine pour lequel vous souhaitez que le cookie soit
valide. Vous pouvez aussi définir la durée de vie du cookie, ainsi que
le chemin pour lequel il doit être renvoyé.</p>
<p>Par défaut, la durée de vie du cookie correspond à la session du
navigateur en cours.</p>
<p>Par défaut, le chemin pour lequel le cookie sera valide est "/" -
c'est à dire, pour tout le site web.</p>
<p>Voici un exemple :</p>
<example>
RewriteEngine On<br />
RewriteRule ^/index\.html - [CO=frontdoor:yes:.apache.org:1440:/]
</example>
<p>Dans l'exemple ci-dessus, la règle ne réécrit
pas la requête. La cible de réécriture "-"
indique à mod_rewrite de transmettre la requête sans
modification. Par contre, il
définit un cookie nommé 'frontdoor' avec une valeur 'yes'. Le cookie est
valide pour tout hôte situé dans le domaine <code>.apache.org</code>. Sa
durée de vie est limitée à 1440 minutes (24 heures), et il sera renvoyé
pour tous les URIs.</p>
</section>
<section id="flag_dpi"><title>DPI|discardpathinfo</title>
<p>Avec le drapeau DPI, la partie PATH_INFO de l'URI
réécrit est supprimée.</p>
</section>
<section id="flag_e"><title>E|env</title>
<p>Avec le drapeau [E], ou [env], vous pouvez définir la valeur d'une
variable d'environnement. Notez que certaines variables d'environnement
peuvent être définies après le traitement de la règle, annulant par
la-même ce que vous avez défini. Voir le <a href="../env.html">document
sur les variables d'environnement</a> pour plus de détails sur le
fonctionnement des variables d'environnement.</p>
<p>L'exemple suivant définit une variable d'environnement nommée 'image'
avec une valeur de '1' si l'URI de la requête correspond à un fichier
image. Cette variable d'environnement est ensuite utilisée pour exclure
une telle requête du journal des accès.</p>
<example>
RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
CustomLog logs/access_log combined env=!image
</example>
<p>Notez que le même effet peut être obtenu à l'aide de la directive
<directive module="mod_setenvif">SetEnvIf</directive>. Cette technique
est présentée à titre d'exemple et non de recommandation.</p>
</section>
<section id="flag_f"><title>F|forbidden</title>
<p>L'utilisation du drapeau [F] permet de faire envoyer par Apache au
client un code de statut "403 Forbidden". Le même effet peut être obtenu à
l'aide de la directive <directive module="mod_access">Deny</directive>,
mais ce drapeau offre plus de souplesse dans l'attribution d'un statut
Forbidden.</p>
<p>La règle suivante va interdire la téléchargement de fichiers
<code>.exe</code> depuis votre serveur.</p>
<example>
RewriteRule \.exe - [F]
</example>
<p>Cet exemple utilise la syntaxe "-" pour la cible de réécriture, ce
qui signifie que l'URI de la requête n'est pas modifié. Il n'y a aucune
raison de réécrire un URI, si vous avez l'intention d'interdire la
requête.</p>
</section>
<section id="flag_g"><title>G|gone</title>
<p>Le drapeau [G] permet de faire envoyer par Apache un code de statut
"410 Gone" avec la réponse. Ce code indique qu'une ressource qui était
disponible auparavant ne l'est plus actuellement.</p>
<p>Comme dans le cas du drapeau [F], on utilise en général la syntaxe
"-" pour la cible de réécriture lorsqu'on utilise le drapeau [G] :</p>
<example>
RewriteRule ancienne-ressource - [G,NC]
</example>
</section>
<section id="flag_h"><title>H|handler</title>
<p>Force le traitement de la requête résultante par le gestionnaire
spécifié. Par exemple, on peut utiliser ce drapeau pour forcer
l'interprétation de tous les fichiers sans extension par le gestionnaire
php :</p>
<example>
RewriteRule !\. - [H=application/x-httpd-php]
</example>
<p>
L'expression rationnelle ci-dessus - <code>!\.</code> - correspond à
toute requête qui ne contient pas le caractère <code>.</code>.
</p>
<p>On peut aussi utiliser ce drapeau pour forcer l'utilisation d'un
certain gestionnaire en fonction de certaines conditions. Par exemple,
l'extrait suivant utilisé dans un contexte de niveau serveur permet de
faire en sorte que les fichiers <code>.php</code> soient
<em>affichés</em> par <code>mod_php</code> dans le cas où ils font
l'objet d'une requête avec l'extension <code>.phps</code> :
</p>
<example>
RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
</example>
<p>L'expression rationnelle ci-dessus -
<code>^(/source/.+\.php)s$</code> - va correspondre à toute requête qui
débutera par <code>/source/</code>, continuera par 1 ou n caractères
puis par <code>.phps</code>. La référence arrière $1 fait référence à la
correspondance capturée entre parenthèses de l'expression
rationnelle.</p>
</section>
<section id="flag_l"><title>L|last</title>
<p>Lorsque le drapeau [L] est présent, <module>mod_rewrite</module>
arrête le traitement du jeu de règles. Cela signifie dans la plupart des
situations que si la règle s'applique, aucune autre règle ne sera
traitée.</p>
<p>Si vous utilisez des règles <directive
module="mod_rewrite">RewriteRule</directive> dans des fichiers
<code>.htaccess</code> ou des sections <directive type="section"
module="core">Directory</directive>, il est important d'avoir quelques
notions sur la manière dont les règles sont traitées. Pour simplifier,
une fois les règles traitées, la requête réécrite est passée à nouveau
au moteur d'interprétation des URLs afin que ce dernier puisse la
traiter. Il est possible qu'au cours du traitement de la requête
réécrite, le fichier <code>.htaccess</code> ou la section <directive
type="section" module="core">Directory</directive> soient à nouveau
rencontrés, entraînant un nouveau traitement du jeu de règles depuis le
début. Cette situation se présente le plus souvent lorsqu'une des règles
provoque une redirection - interne ou externe - ce qui réinitialise le
traitement de la requête.</p>
<p>Si vous utilisez des directives <directive
module="mod_rewrite">RewriteRule</directive> dans un de ces contextes,
il importe par conséquent de prévoir explicitement des étapes permettant
d'éviter un bouclage infini sur les règles,
et de ne pas compter seulement sur
le drapeau [L] pour terminer l'exécution d'une série de règles, comme
décrit ci-dessous.</p>
<p>Dans l'exemple donné ici, toute requête est réécrite en
<code>index.php</code>, la requête originale étant ajoutée comme chaîne
de requête en argument à <code>index.php</code> ; cependant, la
directive <directive
module="mod_rewrite">RewriteCond</directive> permet de s'assurer que si
la requête concerne déjà <code>index.php</code>, la directive <directive
module="mod_rewrite">RewriteRule</directive> sera sautée.</p>
<example>
RewriteCond %{REQUEST_URI} !=index\.php<br />
RewriteRule ^(.*) index.php?req=$1 [L]
</example>
</section>
<section id="flag_n"><title>N|next</title>
<p>Le drapeau [N] provoque un redémarrage du traitement des règles
depuis le début ; à utiliser avec précautions car il peut provoquer un
bouclage infini.
</p>
<p>
Le drapeau [Next] peut servir, par exemple,
à remplacer de manière répétitive
une chaîne de caractère ou une lettre dans une requête. Dans l'exemple
suivant, chaque occurence de A sera remplacée par B dans la requête, et
ceci jusqu'il n'y ait plus de A à remplacer.
</p>
<example>
RewriteRule (.*)A(.*) $1B$2 [N]
</example>
<p>Vous pouvez vous représenter ce traitement comme une boucle
<code>while</code> : tant que le modèle de la règle correspond (c'est à
dire, tant que l'URI contient un <code>A</code>),
effectuer la substitution (c'est à dire, remplacer le <code>A</code> par
un <code>B</code>).</p>
</section>
<section id="flag_nc"><title>NC|nocase</title>
<p>Avec le drapeau [NC], le modèle de la règle <directive
module="mod_rewrite">RewriteRule</directive> est comparé à la requête de
manière insensible à la casse. C'est à dire que cette comparaison
s'effectue sans tenir compte des majuscules/minuscules dans l'URI
comparé.</p>
<p>Dans l'exemple suivant, toute requête pour un fichier image sera
transmise par Apache à votre serveur d'images dédié. La correspondance est
insensible à la casse, si bien que par exemple, <code>.jpg</code> aussi
bien que <code>.JPG</code> seront acceptés.</p>
<example>
RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
</example>
</section>
<section id="flag_ne"><title>NE|noescape</title>
<p>Par défaut, les caractères spéciaux, comme <code>&</code> et
<code>?</code>, sont convertis en leur équivalent
hexadécimal. Le drapeau [NE] permet d'éviter cette conversion.
</p>
<example>
RewriteRule ^/ancre/(.+) /grosse-page.html#$1 [NE,R]
</example>
<p>
Dans l'exemple ci-dessus, <code>/anchor/xyz</code> est réécrit en
<code>/bigpage.html#xyz</code>. En l'absence du drapeau [NE], le #
aurait été converti en son équivalent hexadécimal, <code>%23</code>, ce
qui aurait provoqué un code d'erreur "404 Not Found".
</p>
</section>
<section id="flag_ns"><title>NS|nosubreq</title>
<p>Le drapeau [NS] empêche la règle de s'appliquer aux sous-requêtes.
Par exemple, une page incluse au moyen d'une SSI (Server
Side Include) est une sous-requête, et vous ne voudrez peut-être pas que
la réécriture s'applique à ces sous-requêtes.</p>
<p>
Les images, scripts java, ou fichiers css, chargés en tant que partie
d'une page html, ne sont pas des sous-requêtes - le navigateur les
appelle sous forme de requêtes HTTP à part entière.
</p>
</section>
<section id="flag_p"><title>P|proxy</title>
<p>L'utilisation du drapeau [P] entraîne le traitement de la requête par
le module <module>mod_proxy</module>, et ceci via une requête de
mandataire. Par exemple, si vous voulez que toutes les requêtes d'images
soient traitées par un serveur d'images annexe, vous pouvez utiliser
une règle de ce style :</p>
<example>
RewriteRule (.*)\.(jpg|gif|png) http://images.exemple.com$1.$2 [P]
</example>
<p>L'utilisation du drapeau [P] provoque aussi l'effet du drapeau [L] -
autrement dit, la requête est immédiatement envoyée au mandataire, et
toute règle ultérieure sera ignorée.</p>
</section>
<section id="flag_pt"><title>PT|passthrough</title>
<p>
Par défaut, la cible (ou chaîne de substitution) d'une règle
RewriteRule est sensée être un chemin de fichier. Avec le drapeau [PT],
par contre, elle est traitée comme un URI. Autrement dit, avec le
drapeau [PT], le résultat de la règle <directive
module="mod_rewrite">RewriteRule</directive> est passé à nouveau au
système de mise en correspondance des URLs avec le système de fichiers,
de façon à ce que les systèmes de mise en correspondance basés sur les
chemins de fichiers, comme la directive <directive
module="mod_alias">Alias</directive>, par exemple, puissent avoir une
chance d'accomplir leur tâche.
</p>
<p>
Si par exemple, vous avez un <directive
module="mod_alias">Alias</directive> pour /icons, et une règle <directive
module="mod_rewrite">RewriteRule</directive> qui renvoie vers /icons,
vous devez utiliser le drapeau [PT] pour être sûr que l'<directive
module="mod_alias">Alias</directive> sera bien évalué.
</p>
<example>
Alias /icons /usr/local/apache/icons<br />
RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
</example>
<p>
Dans l'exemple précédent, en l'absence du drapeau [PT], l'Alias aurait
été ignoré, ce qui aurait provoqué une erreur 'File not found'.
</p>
</section>
<section id="flag_qsa"><title>QSA|qsappend</title>
<p>
Quand l'URI de remplacement contient une chaîne de requête, le
comportement par défaut de la règle <directive
module="mod_rewrite">RewriteRule</directive> est de supprimer la <code>
query string</code> (il s'agit des paramètres éventuellement passés dans l'URL après le
caractère <code>?</code>, usuellement pour les formulaires traités par la
méthode HTTP <code>GET</code>) existante, et de la remplacer par celle nouvellement créée.
Avec le drapeau [QSA], les chaînes de requête peuvent être combinées.
</p>
<p>Considérons la règle suivante :</p>
<example>
RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
</example>
<p>Avec le drapeau [QSA], une requête pour
<code>/pages/123?one=two</code> sera réécrite en
<code>/page.php?page=123&one=two</code>. Sans le drapeau [QSA], la
même requête sera réécrite en <code>/page.php?page=123</code> -
autrement dit, la chaîne de requête (<code>query string</code>) existante sera supprimée.
</p>
</section>
<section id="flag_r"><title>R|redirect</title>
<p>
L'utilisation du drapeau [R] provoque l'envoi d'une redirection au
navigateur. Si une URL pleinement qualifiée (FQDN - fully qualified domain name)
est spécifiée (c'est à dire incluant <code>http://nom-du-serveur/</code>),
une redirection sera effectuée vers cette adresse. Dans le cas contraire,
c'est le nom du serveur local qui sera utilisé pour générer l'URL envoyée avec la
redirection.
</p>
<p>
Un code de statut entre 300 et 399 peut être spécifié, le code 302 étant
utilisé par défaut si aucun code n'est spécifié.
</p>
<p>
Vous utiliserez presque toujours [R] en conjonction avec [L] (c'est à
dire [R,L]), car employé seul, le drapeau [R] préfixe l'URI avec
<code>http://cet-hôte[:ce-port]</code>, mais passe ensuite cette adresse
à la règle suivante, ce qui provoquera le plus souvent des
avertissements 'Invalid URI in request'.
</p>
</section>
<section id="flag_s"><title>S|skip</title>
<p>Le drapeau [S] sert à sauter des règles que vous ne voulez pas voir
exécuter. Ceci peut s'interpréter comme une instruction
<code>goto</code> dans votre jeu de règles de réécriture. Dans
l'exemple suivant, nous ne voulons exécuter la règle <directive
module="mod_rewrite">RewriteRule</directive> que si l'URI demandé ne
correspond pas à un fichier existant.</p>
<example>
# La requête concerne-t-elle un fichier qui n'existe pas ?<br />
RewriteCond %{REQUEST_FILENAME} !-f<br />
RewriteCond %{REQUEST_FILENAME} !-d<br />
# Si c'est la cas, on saute les deux règles de réécriture suivantes<br />
RewriteRule .? - [S=2]<br />
<br />
RewriteRule (.*\.gif) images.php?$1<br />
RewriteRule (.*\.html) docs.php?$1
</example>
<p>Cette technique trouve son utilité dans le fait qu'une directive
<directive module="mod_rewrite">RewriteCond</directive> ne s'applique
qu'à la règle qui la suit immédiatement. Ainsi, si vous voulez
qu'une directive <code>RewriteCond</code> s'applique à plusieurs règles
<code>RewriteRule</code>, vous pouvez utiliser le drapeau [Skip].</p>
</section>
<section id="flag_t"><title>T|type</title>
<p>Définit le type MIME de la réponse résultante renvoyée. L'effet est
identique à celui de la directive <directive
module="mod_mime">AddType</directive>.</p>
<p>Par exemple, vous pouvez utiliser la technique suivante pour servir
du code source Perl en tant que plein texte, s'il est requis d'une
certaine manière :</p>
<example>
# Sert les fichier .pl en tant que plein texte<br />
RewriteRule \.pl$ - [T=text/plain]
</example>
<p>Ou encore, si vous possédez une caméra qui produit des fichiers
images jpeg sans extension, vous pouvez forcer le renvoi de ces images
avec le type MIME correct en se basant sur le nom du fichier :</p>
<example>
# Les fichiers dont le nom contient 'IMG' sont des images jpg.<br />
RewriteRule IMG - [T=image/jpg]
</example>
<p>Notez cependant qu'il s'agit d'un exemple trivial, et que le problème
aurait pu être résolu en utilisant à la place la directive <directive
type="section" module="core">FilesMatch</directive>. Il faut toujours
envisager la possibilité d'une solution alternative à un problème avant
d'avoir recours à la réécriture, qui sera toujours moins efficace qu'une
solution alternative.</p>
</section>
</section>
</manualpage>
|
