Apache HTTP Server Version 2.2
Apache HTTP Server Version 2.2
This document supplements the mod_rewrite
reference documentation. It
describes the basic concepts necessary for use of
mod_rewrite. Other documents go into greater detail,
but this doc should help the beginner get their feet wet.
Introduction Regular Expressions RewriteRule basics Rewrite Flags Rewrite conditions Rewrite maps .htaccess files Environment Variables
The Apache module mod_rewrite is a very powerful and
sophisticated module which provides a way to do URL manipulations. With
it, you can do nearly all types of URL rewriting that you may need. It
is, however, somewhat complex, and may be intimidating to the beginner.
There is also a tendency to treat rewrite rules as magic incantation,
using them without actually understanding what they do.
This document attempts to give sufficient background so that what follows is understood, rather than just copied blindly.
mod_rewrite uses the Perl Compatible Regular Expression vocabulary. In this document, we do not attempt to provide a detailed reference to regular expressions. For that, we recommend the PCRE man pages, the Perl regular expression man page, and Mastering Regular Expressions, by Jeffrey Friedl.
In this document, we attempt to provide enough of a regex vocabulary
to get you started, without being overwhelming, in the hope that
RewriteRules will be scientific
formulae, rather than magical incantations.
The following are the minimal building blocks you will need, in order
to write regular expressions and RewriteRules. They certainly do not
represent a complete regular expression vocabulary, but they are a good
place to start, and should help you read basic regular expressions, as
well as write your own.
| Character | Meaning | Example |
|---|---|---|
. | Matches any character | c.t will match cat,
cot, cut, etc. |
+ | Repeats the previous match one or more times | a+ matches a, aa,
aaa, etc |
* | Repeats the previous match zero or more times. | a* matches all the same things
a+ matches, but will also match an empty string. |
? | Makes the match optional. | |
. | Matches any character | colou?r will match color and
colour. |
^ | Called an anchor, matches the beginning of the string | ^a matches a string that begins with
a |
$ | The other anchor, this matches the end of the string. | a$ matches a string that ends with
a. |
( ) | Groups several characters into a single unit, and captures a match for use in a backreference. | (ab)+
matches ababab - that is, the + applies to the group.
For more on backreferences see below. |
[ ] | A character class - matches one of the characters | c[uoa]t matches cut,
cot or cat. |
! | Not | Negates a match - that is, ensures that it does not match. |
One important thing here has to be remembered: Whenever you
use parentheses in Pattern or in one of the
CondPattern, back-references are internally created
which can be used with the strings $N and
%N (see below). These are available for creating
the strings Substitution and TestString.
Figure 2 shows to which locations the back-references are
transferred for expansion.
![[Needs graphics capability to display]](../images/mod_rewrite_fig2.gif)
Figure 2: The back-reference flow through a rule.
Basic anatomy of a RewriteRule, with exhaustively annotated simple examples.
Discussion of the flags to RewriteRule, and when and why one might use them.
Discussion of RewriteCond, looping, and other related concepts.
Discussion of RewriteMap, including simple, but heavily annotated, examples.
Discussion of the differences between rewrite rules in httpd.conf and in .htaccess files.
This module keeps track of two additional (non-standard)
CGI/SSI environment variables named SCRIPT_URL
and SCRIPT_URI. These contain the
logical Web-view to the current resource, while the
standard CGI/SSI variables SCRIPT_NAME and
SCRIPT_FILENAME contain the physical
System-view.
Notice: These variables hold the URI/URL as they were initially requested, i.e., before any rewriting. This is important because the rewriting process is primarily used to rewrite logical URLs to physical pathnames.
SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html SCRIPT_FILENAME=/u/rse/.www/index.html SCRIPT_URL=/u/rse/ SCRIPT_URI=http://en1.engelschall.com/u/rse/