1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="flags.xml.meta">
24 <parentdocument href="./">Rewrite</parentdocument>
26 <title>RewriteRule Flags</title>
29 <p>This document discusses the flags which are available to the
30 <directive module="mod_rewrite">RewriteRule</directive> directive,
31 providing detailed explanations and examples.</p>
34 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
35 <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
36 <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
37 <seealso><a href="access.html">Controlling access</a></seealso>
38 <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
39 <seealso><a href="proxy.html">Proxying</a></seealso>
40 <seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
41 <seealso><a href="advanced.html">Advanced techniques</a></seealso>
42 <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
44 <section id="introduction"><title>Introduction</title>
45 <p>A <directive module="mod_rewrite">RewriteRule</directive> can have
46 its behavior modified by one or more flags. Flags are included in
47 square brackets at the end of the rule, and multiple flags are separated
49 <highlight language="config">
50 RewriteRule pattern target [Flag1,Flag2,Flag3]
53 <p>Each flag (with a few exceptions) has a short form, such as
54 <code>CO</code>, as well as a longer form, such as <code>cookie</code>.
55 While it is most common to use
56 the short form, it is recommended that you familiarize yourself with the
57 long form, so that you remember what each flag is supposed to do.
58 Some flags take one or more arguments. Flags are not case sensitive.</p>
60 <p>Flags that alter metadata associated with the request (T=, H=, E=)
61 have no affect in per-directory and htaccess context, when a substitution
62 (other than '-') is performed during the same round of rewrite processing.
65 <p>Presented here are each of the available flags, along with an example
66 of how you might use them.</p>
69 <section id="flag_b"><title>B (escape backreferences)</title>
70 <p>The [B] flag instructs <directive
71 module="mod_rewrite">RewriteRule</directive> to escape non-alphanumeric
72 characters before applying the transformation.</p>
73 <p>In 2.4.10 and later, you can limit the escaping to specific characters
74 in backreferences by listing them: <code>[B=#?;]</code>. Note: The space
75 character can be used in the list of characters to escape, but it cannot be
76 the last character in the list.</p>
78 <p><code>mod_rewrite</code> has to unescape URLs before mapping them,
79 so backreferences are unescaped at the time they are applied.
80 Using the B flag, non-alphanumeric characters in backreferences
81 will be escaped. For example, consider the rule:</p>
83 <highlight language="config">
84 RewriteRule "^search/(.*)$" "/search.php?term=$1"
87 <p>Given a search term of 'x & y/z', a browser will encode it as
88 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B
89 flag, this rewrite rule will map to 'search.php?term=x & y/z', which
90 isn't a valid URL, and so would be encoded as
91 <code>search.php?term=x%20&y%2Fz=</code>, which is not what was intended.</p>
93 <p>With the B flag set on this same rule, the parameters are re-encoded
94 before being passed on to the output URL, resulting in a correct mapping to
95 <code>/search.php?term=x%20%26%20y%2Fz</code>.</p>
97 <p>Note that you may also need to set <directive
98 module="core">AllowEncodedSlashes</directive> to <code>On</code> to get this
99 particular example to work, as httpd does not allow encoded slashes in URLs, and
100 returns a 404 if it sees one.</p>
102 <p>This escaping is particularly necessary in a proxy situation,
103 when the backend may break if presented with an unescaped URL.</p>
105 <p>An alternative to this flag is using a <directive module="mod_rewrite"
106 >RewriteCond</directive> to capture against %{THE_REQUEST} which will capture
107 strings in the encoded form.</p>
110 <section id="flag_bnp"><title>BNP|backrefnoplus (don't escape space to +)</title>
111 <p>The [BNP] flag instructs <directive
112 module="mod_rewrite">RewriteRule</directive> to escape the space character
113 in a backreference to %20 rather than '+'. Useful when the backreference
114 will be used in the path component rather than the query string.</p>
117 <section id="flag_c"><title>C|chain</title>
118 <p>The [C] or [chain] flag indicates that the <directive
119 module="mod_rewrite">RewriteRule</directive> is chained to the next
120 rule. That is, if the rule matches, then it is processed as usual and
121 control moves on to the next rule. However, if it does not match, then
122 the next rule, and any other rules that are chained together, are
127 <section id="flag_co"><title>CO|cookie</title>
128 <p>The [CO], or [cookie] flag, allows you to set a cookie when a
129 particular <directive module="mod_rewrite">RewriteRule</directive>
130 matches. The argument consists of three required fields and four optional
133 <p>The full syntax for the flag, including all attributes, is as
137 [CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]
140 <p>If a literal ':' character is needed in any of the cookie fields, an
141 alternate syntax is available. To opt-in to the alternate syntax, the cookie
142 "Name" should be preceded with a ';' character, and field separators should be
143 specified as ';'.</p>
146 [CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly]
149 <p>You must declare a name, a value, and a domain for the cookie to be set.</p>
153 <dd>The domain for which you want the cookie to be valid. This may be a
154 hostname, such as <code>www.example.com</code>, or it may be a domain,
155 such as <code>.example.com</code>. It must be at least two parts
156 separated by a dot. That is, it may not be merely <code>.com</code> or
157 <code>.net</code>. Cookies of that kind are forbidden by the cookie
161 <p>You may optionally also set the following values:</p>
165 <dd>The time for which the cookie will persist, in minutes.</dd>
166 <dd>A value of 0 indicates that the cookie will persist only for the
167 current browser session. This is the default value if none is
171 <dd>The path, on the current website, for which the cookie is valid,
172 such as <code>/customers/</code> or <code>/files/download/</code>.</dd>
173 <dd>By default, this is set to <code>/</code> - that is, the entire
177 <dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
178 the cookie will only be permitted to be translated via secure (https)
182 <dd>If set to <code>HttpOnly</code>, <code>true</code>, or
183 <code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
184 which means that the cookie is inaccessible to JavaScript code on
185 browsers that support this feature.</dd>
188 <p>Consider this example:</p>
190 <highlight language="config">
192 RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]
195 <p>In the example give, the rule doesn't rewrite the request.
196 The "-" rewrite target tells mod_rewrite to pass the request
197 through unchanged. Instead, it sets a cookie
198 called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
199 in the <code>.example.com</code> domain. It is set to expire in 1440
200 minutes (24 hours) and is returned for all URIs.</p>
204 <section id="flag_dpi"><title>DPI|discardpath</title>
205 <p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
207 <p>This flag is available in version 2.2.12 and later.</p>
208 <p>In per-directory context, the URI each <directive>RewriteRule</directive>
209 compares against is the concatenation of the current values of the URI
212 <p>The current URI can be the initial URI as requested by the client, the
213 result of a previous round of mod_rewrite processing, or the result of
214 a prior rule in the current round of mod_rewrite processing.</p>
216 <p>In contrast, the PATH_INFO that is appended to the URI before each
217 rule reflects only the value of PATH_INFO before this round of
218 mod_rewrite processing. As a consequence, if large portions
219 of the URI are matched and copied into a substitution in multiple
220 <directive>RewriteRule</directive> directives, without regard for
221 which parts of the URI came from the current PATH_INFO, the final
222 URI may have multiple copies of PATH_INFO appended to it.</p>
224 <p>Use this flag on any substitution where the PATH_INFO that resulted
225 from the previous mapping of this request to the filesystem is not of
226 interest. This flag permanently forgets the PATH_INFO established
227 before this round of mod_rewrite processing began. PATH_INFO will
228 not be recalculated until the current round of mod_rewrite processing
229 completes. Subsequent rules during this round of processing will see
230 only the direct result of substitutions, without any PATH_INFO
234 <section id="flag_e"><title>E|env</title>
235 <p>With the [E], or [env] flag, you can set the value of an environment
236 variable. Note that some environment variables may be set after the rule
237 is run, thus unsetting what you have set. See <a href="../env.html">the
238 Environment Variables document</a> for more details on how Environment
241 <p>The full syntax for this flag is:</p>
243 <highlight language="config">
248 <p><code>VAL</code> may contain backreferences (<code>$N</code> or
249 <code>%N</code>) which are expanded.</p>
251 <p>Using the short form</p>
257 <p>you can set the environment variable named <code>VAR</code> to an
266 <p>allows to unset a previously set environment variable named
267 <code>VAR</code>.</p>
269 <p>Environment variables can then be used in a variety of
270 contexts, including CGI programs, other RewriteRule directives, or
271 CustomLog directives.</p>
273 <p>The following example sets an environment variable called 'image' to a
274 value of '1' if the requested URI is an image file. Then, that
275 environment variable is used to exclude those requests from the access
278 <highlight language="config">
279 RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1]
280 CustomLog "logs/access_log" combined env=!image
283 <p>Note that this same effect can be obtained using <directive
284 module="mod_setenvif">SetEnvIf</directive>. This technique is offered as
285 an example, not as a recommendation.</p>
288 <section id="flag_end"><title>END</title>
289 <p>Using the [END] flag terminates not only the current round of rewrite
290 processing (like [L]) but also prevents any subsequent rewrite
291 processing from occurring in per-directory (htaccess) context.</p>
293 <p>This does not apply to new requests resulting from external
297 <section id="flag_f"><title>F|forbidden</title>
298 <p>Using the [F] flag causes the server to return a 403 Forbidden status
299 code to the client. While the same behavior can be accomplished using
300 the <directive module="mod_access_compat">Deny</directive> directive, this
301 allows more flexibility in assigning a Forbidden status.</p>
303 <p>The following rule will forbid <code>.exe</code> files from being
304 downloaded from your server.</p>
306 <highlight language="config">
307 RewriteRule "\.exe" "-" [F]
310 <p>This example uses the "-" syntax for the rewrite target, which means
311 that the requested URI is not modified. There's no reason to rewrite to
312 another URI, if you're going to forbid the request.</p>
314 <p>When using [F], an [L] is implied - that is, the response is returned
315 immediately, and no further rules are evaluated.</p>
319 <section id="flag_g"><title>G|gone</title>
320 <p>The [G] flag forces the server to return a 410 Gone status with the
321 response. This indicates that a resource used to be available, but is no
322 longer available.</p>
324 <p>As with the [F] flag, you will typically use the "-" syntax for the
325 rewrite target when using the [G] flag:</p>
327 <highlight language="config">
328 RewriteRule "oldproduct" "-" [G,NC]
331 <p>When using [G], an [L] is implied - that is, the response is returned
332 immediately, and no further rules are evaluated.</p>
336 <section id="flag_h"><title>H|handler</title>
337 <p>Forces the resulting request to be handled with the specified
338 handler. For example, one might use this to force all files without a
339 file extension to be parsed by the php handler:</p>
341 <highlight language="config">
342 RewriteRule "!\." "-" [H=application/x-httpd-php]
346 The regular expression above - <code>!\.</code> - will match any request
347 that does not contain the literal <code>.</code> character.
350 <p>This can be also used to force the handler based on some conditions.
351 For example, the following snippet used in per-server context allows
352 <code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
353 if they are requested with the <code>.phps</code> extension:</p>
355 <highlight language="config">
356 RewriteRule "^(/source/.+\.php)s$" "$1" [H=application/x-httpd-php-source]
359 <p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
360 match any request that starts with <code>/source/</code> followed by 1 or
361 n characters followed by <code>.phps</code> literally. The backreference
362 $1 referrers to the captured match within parenthesis of the regular
366 <section id="flag_l"><title>L|last</title>
367 <p>The [L] flag causes <module>mod_rewrite</module> to stop processing
368 the rule set. In most contexts, this means that if the rule matches, no
369 further rules will be processed. This corresponds to the
370 <code>last</code> command in Perl, or the <code>break</code> command in
371 C. Use this flag to indicate that the current rule should be applied
372 immediately without considering further rules.</p>
374 <p>If you are using <directive
375 module="mod_rewrite">RewriteRule</directive> in either
376 <code>.htaccess</code> files or in
377 <directive type="section" module="core">Directory</directive> sections,
378 it is important to have some understanding of how the rules are
379 processed. The simplified form of this is that once the rules have been
380 processed, the rewritten request is handed back to the URL parsing
381 engine to do what it may with it. It is possible that as the rewritten
382 request is handled, the <code>.htaccess</code> file or
383 <directive type="section" module="core">Directory</directive> section
384 may be encountered again, and thus the ruleset may be run again from the
385 start. Most commonly this will happen if one of the rules causes a
386 redirect - either internal or external - causing the request process to
389 <p>It is therefore important, if you are using <directive
390 module="mod_rewrite">RewriteRule</directive> directives in one of these
391 contexts, that you take explicit steps to avoid rules looping, and not
392 count solely on the [L] flag to terminate execution of a series of
393 rules, as shown below.</p>
395 <p> An alternative flag, [END], can be used to terminate not only the
396 current round of rewrite processing but prevent any subsequent
397 rewrite processing from occurring in per-directory (htaccess)
398 context. This does not apply to new requests resulting from external
401 <p>The example given here will rewrite any request to
402 <code>index.php</code>, giving the original request as a query string
403 argument to <code>index.php</code>, however, the <directive
404 module="mod_rewrite">RewriteCond</directive> ensures that if the request
405 is already for <code>index.php</code>, the <directive
406 module="mod_rewrite">RewriteRule</directive> will be skipped.</p>
408 <highlight language="config">
410 RewriteCond "%{REQUEST_URI}" !=/index.php
411 RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]
415 <section id="flag_n"><title>N|next</title>
417 The [N] flag causes the ruleset to start over again from the top, using
418 the result of the ruleset so far as a starting point. Use
419 with extreme caution, as it may result in loop.
422 The [Next] flag could be used, for example, if you wished to replace a
423 certain string or letter repeatedly in a request. The example shown here
424 will replace A with B everywhere in a request, and will continue doing
425 so until there are no more As to be replaced.
427 <highlight language="config">
428 RewriteRule "(.*)A(.*)" "$1B$2" [N]
430 <p>You can think of this as a <code>while</code> loop: While this
431 pattern still matches (i.e., while the URI still contains an
432 <code>A</code>), perform this substitution (i.e., replace the
433 <code>A</code> with a <code>B</code>).</p>
435 <p>In 2.5.0 and later, this module returns an error after 10,000 iterations to
436 protect against unintended looping. An alternative maximum number of
437 iterations can be specified by adding to the N flag. </p>
438 <highlight language="config">
439 # Be willing to replace 1 character in each pass of the loop
440 RewriteRule "(.+)[><;]$" "$1" [N=32000]
441 # ... or, give up if after 10 loops
442 RewriteRule "(.+)[><;]$" "$1" [N=10]
447 <section id="flag_nc"><title>NC|nocase</title>
448 <p>Use of the [NC] flag causes the <directive
449 module="mod_rewrite">RewriteRule</directive> to be matched in a
450 case-insensitive manner. That is, it doesn't care whether letters appear
451 as upper-case or lower-case in the matched URI.</p>
453 <p>In the example below, any request for an image file will be proxied
454 to your dedicated image server. The match is case-insensitive, so that
455 <code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
458 <highlight language="config">
459 RewriteRule "(.*\.(jpg|gif|png))$" "http://images.example.com$1" [P,NC]
463 <section id="flag_ne"><title>NE|noescape</title>
464 <p>By default, special characters, such as <code>&</code> and
465 <code>?</code>, for example, will be converted to their hexcode
466 equivalent. Using the [NE] flag prevents that from happening.
469 <highlight language="config">
470 RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]
474 The above example will redirect <code>/anchor/xyz</code> to
475 <code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
476 being converted to its hexcode equivalent, <code>%23</code>, which will
477 then result in a 404 Not Found error condition.
482 <section id="flag_ns"><title>NS|nosubreq</title>
483 <p>Use of the [NS] flag prevents the rule from being used on
484 subrequests. For example, a page which is included using an SSI (Server
485 Side Include) is a subrequest, and you may want to avoid rewrites
486 happening on those subrequests. Also, when <module>mod_dir</module>
487 tries to find out information about possible directory default files
488 (such as <code>index.html</code> files), this is an internal
489 subrequest, and you often want to avoid rewrites on such subrequests.
490 On subrequests, it is not always useful, and can even cause errors, if
491 the complete set of rules are applied. Use this flag to exclude
492 problematic rules.</p>
494 <p>To decide whether or not to use this rule: if you prefix URLs with
495 CGI-scripts, to force them to be processed by the CGI-script, it's
496 likely that you will run into problems (or significant overhead)
497 on sub-requests. In these cases, use this flag.</p>
500 Images, javascript files, or css files, loaded as part of an HTML page,
501 are not subrequests - the browser requests them as separate HTTP
506 <section id="flag_p"><title>P|proxy</title>
507 <p>Use of the [P] flag causes the request to be handled by
508 <module>mod_proxy</module>, and handled via a proxy request. For
509 example, if you wanted all image requests to be handled by a back-end
510 image server, you might do something like the following:</p>
512 <highlight language="config">
513 RewriteRule "/(.*)\.(jpg|gif|png)$" "http://images.example.com/$1.$2" [P]
516 <p>Use of the [P] flag implies [L] - that is, the request is immediately
517 pushed through the proxy, and any following rules will not be
521 You must make sure that the substitution string is a valid URI
522 (typically starting with <code>http://</code><em>hostname</em>) which can be
523 handled by the <module>mod_proxy</module>. If not, you will get an
524 error from the proxy module. Use this flag to achieve a
525 more powerful implementation of the <directive
526 module="mod_proxy">ProxyPass</directive> directive,
527 to map remote content into the namespace of the local server.</p>
529 <note type="warning">
530 <title>Security Warning</title>
531 <p>Take care when constructing the target URL of the rule, considering
532 the security impact from allowing the client influence over the set of
533 URLs to which your server will act as a proxy. Ensure that the scheme
534 and hostname part of the URL is either fixed, or does not allow the
535 client undue influence.</p>
538 <note type="warning">
539 <title>Performance warning</title>
540 <p>Using this flag triggers the use of <module>mod_proxy</module>, without handling of persistent connections. This
541 means the performance of your proxy will be better if you set it up with <directive module="mod_proxy">ProxyPass</directive> or
542 <directive module="mod_proxy">ProxyPassMatch</directive></p>
543 <p>This is because this flag triggers the use of the default worker, which does not handle connection pooling.</p>
544 <p>Avoid using this flag and prefer those directives, whenever you can.</p>
547 <p>Note: <module>mod_proxy</module> must be enabled in order
548 to use this flag.</p>
552 <section id="flag_pt"><title>PT|passthrough</title>
555 The target (or substitution string) in a RewriteRule is assumed to be a
556 file path, by default. The use of the [PT] flag causes it to be treated
557 as a URI instead. That is to say, the
558 use of the [PT] flag causes the result of the <directive
559 module="mod_rewrite">RewriteRule</directive> to be passed back through
560 URL mapping, so that location-based mappings, such as <directive
561 module="mod_alias">Alias</directive>, <directive
562 module="mod_alias">Redirect</directive>, or <directive
563 module="mod_alias">ScriptAlias</directive>, for example, might have a
564 chance to take effect.
568 If, for example, you have an
569 <directive module="mod_alias">Alias</directive>
570 for /icons, and have a <directive
571 module="mod_rewrite">RewriteRule</directive> pointing there, you should
572 use the [PT] flag to ensure that the
573 <directive module="mod_alias">Alias</directive> is evaluated.
576 <highlight language="config">
577 Alias "/icons" "/usr/local/apache/icons"
578 RewriteRule "/pics/(.+)\.jpg$" "/icons/$1.gif" [PT]
582 Omission of the [PT] flag in this case will cause the Alias to be
583 ignored, resulting in a 'File not found' error being returned.
586 <p>The <code>PT</code> flag implies the <code>L</code> flag:
587 rewriting will be stopped in order to pass the request to
588 the next phase of processing.</p>
590 <p>Note that the <code>PT</code> flag is implied in per-directory
592 <directive type="section" module="core">Directory</directive> sections
593 or in <code>.htaccess</code> files. The only way to circumvent that
594 is to rewrite to <code>-</code>.</p>
598 <section id="flag_qsa"><title>QSA|qsappend</title>
600 When the replacement URI contains a query string, the default behavior
601 of <directive module="mod_rewrite">RewriteRule</directive> is to discard
602 the existing query string, and replace it with the newly generated one.
603 Using the [QSA] flag causes the query strings to be combined.
606 <p>Consider the following rule:</p>
608 <highlight language="config">
609 RewriteRule "/pages/(.+)" "/page.php?page=$1" [QSA]
612 <p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
613 mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
614 flag, that same request will be mapped to
615 <code>/page.php?page=123</code> - that is, the existing query string
620 <section id="flag_qsd"><title>QSD|qsdiscard</title>
622 When the requested URI contains a query string, and the target URI does
623 not, the default behavior of <directive
624 module="mod_rewrite">RewriteRule</directive> is to copy that query
625 string to the target URI. Using the [QSD] flag causes the query string
629 <p>This flag is available in version 2.4.0 and later.</p>
632 Using [QSD] and [QSA] together will result in [QSD] taking precedence.
636 If the target URI has a query string, the default behavior will be
637 observed - that is, the original query string will be discarded and
638 replaced with the query string in the <code>RewriteRule</code> target
644 <section id="flag_r"><title>R|redirect</title>
646 Use of the [R] flag causes a HTTP redirect to be issued to the browser.
647 If a fully-qualified URL is specified (that is, including
648 <code>http://servername/</code>) then a redirect will be issued to that
649 location. Otherwise, the current protocol, servername, and port number
650 will be used to generate the URL sent with the redirect.
654 <em>Any</em> valid HTTP response status code may be specified,
655 using the syntax [R=305], with a 302 status code being used by
656 default if none is specified. The status code specified need not
657 necessarily be a redirect (3xx) status code. However,
658 if a status code is outside the redirect range (300-399) then the
659 substitution string is dropped entirely, and rewriting is stopped as if
660 the <code>L</code> were used.</p>
662 <p>In addition to response status codes, you may also specify redirect
663 status using their symbolic names: <code>temp</code> (default),
664 <code>permanent</code>, or <code>seeother</code>.</p>
667 You will almost always want to use [R] in conjunction with [L] (that is,
668 use [R,L]) because on its own, the [R] flag prepends
669 <code>http://thishost[:thisport]</code> to the URI, but then passes this
670 on to the next rule in the ruleset, which can often result in 'Invalid
671 URI in request' warnings.
676 <section id="flag_s"><title>S|skip</title>
677 <p>The [S] flag is used to skip rules that you don't want to run. The
678 syntax of the skip flag is [S=<em>N</em>], where <em>N</em> signifies
679 the number of rules to skip (provided the <directive module="mod_rewrite">
680 RewriteRule</directive> and any preceding <directive module="mod_rewrite">
681 RewriteCond</directive> directives match). This can be thought of as a
682 <code>goto</code> statement in your rewrite ruleset. In the following
683 example, we only want to run the <directive module="mod_rewrite">
684 RewriteRule</directive> if the requested URI doesn't correspond with an
687 <highlight language="config">
688 # Is the request for a non-existent file?
689 RewriteCond "%{REQUEST_FILENAME}" !-f
690 RewriteCond "%{REQUEST_FILENAME}" !-d
691 # If so, skip these two RewriteRules
692 RewriteRule ".?" "-" [S=2]
694 RewriteRule "(.*\.gif)" "images.php?$1"
695 RewriteRule "(.*\.html)" "docs.php?$1"
698 <p>This technique is useful because a <directive
699 module="mod_rewrite">RewriteCond</directive> only applies to the
700 <directive module="mod_rewrite">RewriteRule</directive> immediately
701 following it. Thus, if you want to make a <code>RewriteCond</code> apply
702 to several <code>RewriteRule</code>s, one possible technique is to
703 negate those conditions and add a <code>RewriteRule</code> with a [Skip] flag. You can
704 use this to make pseudo if-then-else constructs: The last rule of
705 the then-clause becomes <code>skip=N</code>, where N is the
706 number of rules in the else-clause:</p>
707 <highlight language="config">
708 # Does the file exist?
709 RewriteCond "%{REQUEST_FILENAME}" !-f
710 RewriteCond "%{REQUEST_FILENAME}" !-d
711 # Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
712 RewriteRule ".?" "-" [S=3]
714 # IF the file exists, then:
715 RewriteRule "(.*\.gif)" "images.php?$1"
716 RewriteRule "(.*\.html)" "docs.php?$1"
717 # Skip past the "else" stanza.
718 RewriteRule ".?" "-" [S=1]
720 RewriteRule "(.*)" "404.php?file=$1"
724 <p>It is probably easier to accomplish this kind of configuration using
725 the <directive type="section">If</directive>, <directive
726 type="section">ElseIf</directive>, and <directive
727 type="section">Else</directive> directives instead.</p>
731 <section id="flag_t"><title>T|type</title>
732 <p>Sets the MIME type with which the resulting response will be
733 sent. This has the same effect as the <directive
734 module="mod_mime">AddType</directive> directive.</p>
736 <p>For example, you might use the following technique to serve Perl
737 source code as plain text, if requested in a particular way:</p>
739 <highlight language="config">
740 # Serve .pl files as plain text
741 RewriteRule "\.pl$" "-" [T=text/plain]
744 <p>Or, perhaps, if you have a camera that produces jpeg images without
745 file extensions, you could force those images to be served with the
746 correct MIME type by virtue of their file names:</p>
748 <highlight language="config">
749 # Files with 'IMG' in the name are jpg images.
750 RewriteRule "IMG" "-" [T=image/jpg]
753 <p>Please note that this is a trivial example, and could be better done
754 using <directive type="section" module="core">FilesMatch</directive>
755 instead. Always consider the alternate
756 solutions to a problem before resorting to rewrite, which will
757 invariably be a less efficient solution than the alternatives.</p>
760 If used in per-directory context, use only <code>-</code> (dash)
761 as the substitution <em>for the entire round of mod_rewrite processing</em>,
762 otherwise the MIME-type set with this flag is lost due to an internal
763 re-processing (including subsequent rounds of mod_rewrite processing).
764 The <code>L</code> flag can be useful in this context to end the
765 <em>current</em> round of mod_rewrite processing.</p>