You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by sl...@apache.org on 2007/08/01 17:21:32 UTC
svn commit: r561840 - in /httpd/httpd/trunk/docs/manual/mod:
mod_rewrite.html.en mod_rewrite.xml
Author: slive
Date: Wed Aug 1 08:21:31 2007
New Revision: 561840
URL: http://svn.apache.org/viewvc?view=rev&rev=561840
Log:
Some updates to the RewriteRule docs, mostly focusing on clearly
describing what can be in the substitution string. Included is
a description of how mod_rewrite decides whether to treat the
substitution as a file-system or URL-path.
PR: 22529
Modified:
httpd/httpd/trunk/docs/manual/mod/mod_rewrite.html.en
httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml
Modified: httpd/httpd/trunk/docs/manual/mod/mod_rewrite.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_rewrite.html.en?view=diff&rev=561840&r1=561839&r2=561840
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_rewrite.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_rewrite.html.en Wed Aug 1 08:21:31 2007
@@ -1062,12 +1062,11 @@
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
- <em>Pattern</em> <em>Substitution</em></code></td></tr>
+ <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
</table>
<p>The <code class="directive">RewriteRule</code> directive is the real
rewriting workhorse. The directive can occur more than once,
@@ -1082,6 +1081,17 @@
subsequent patterns are applied to the output of the last matched
RewriteRule.</p>
+<div class="note"><h3>What is matched?</h3>
+ <p>The <em>Pattern</em> will initially be matched against the part of the
+ URL after the hostname and port, and before the query string. If you wish
+ to match against the hostname, port, or query string, use a
+ <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
+ <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
+ <code>%{QUERY_STRING}</code> variables respectively.</p>
+</div>
+
+
+
<p>Some hints on the syntax of <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
expressions</a>:</p>
@@ -1113,7 +1123,7 @@
</pre></div>
<p>For more information about regular expressions, have a look at the
- perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
+ perl regular expression manpage ("<a href="http://www.perldoc.com/perlre.html">perldoc
perlre</a>"). If you are interested in more detailed
information about regular expressions and their variants
(POSIX regex etc.) the following book is dedicated to this topic:</p>
@@ -1141,10 +1151,54 @@
cannot use <code>$N</code> in the substitution string!
</div>
- <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
- rewrite rule is the string which is substituted for (or
- replaces) the original URL which <em>Pattern</em>
- matched. In addition to plain text, it can include</p>
+ <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
+ rewrite rule is the string that replaces the original URL-path that
+ was matched by <em>Pattern</em>. The <em>Substitution</em> may
+ be a:</p>
+
+ <dl>
+
+ <dt>file-system path</dt>
+
+ <dd>Designates the location on the file-system of the resource
+ to be delivered to the client.</dd>
+
+ <dt>URL-path</dt>
+
+ <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
+ resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ tries to guess whether you have specified a file-system path
+ or a URL-path by checking to see if the first segement of the
+ path exists at the root of the file-system. For example, if
+ you specify a <em>Substitution</em> string of
+ <code>/www/file.html</code>, then this will be treated as a
+ URL-path <em>unless</em> a directory named <code>www</code>
+ exists at the root or your file-system, in which case it will
+ be treated as a file-system path. If you wish other
+ URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
+ resulting URL-path, use the <code>[PT]</code> flag as
+ described below.</dd>
+
+ <dt>Absolute URL</dt>
+
+ <dd>If an absolute URL is specified,
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
+ hostname matches the current host. If it does, the scheme and
+ hostname are stripped out and the resulting path is treated as
+ a URL-path. Otherwise, an external redirect is performed for
+ the given URL. To force an external redirect back to the
+ current host, see the <code>[R]</code> flag below.</dd>
+
+ <dt><code>-</code> (dash)</dt>
+
+ <dd>A dash indicates that no substitution should be performed
+ (the existing path is passed through untouched). This is used
+ when a flag (see below) needs to be applied without changing
+ the path.</dd>
+
+ </dl>
+
+ <p>In addition to plain text, the <em>Substition</em> string can include</p>
<ol>
<li>back-references (<code>$N</code>) to the RewriteRule
@@ -1159,6 +1213,7 @@
<li><a href="#mapfunc">mapping-function</a> calls
(<code>${mapname:key|default}</code>)</li>
</ol>
+
<p>Back-references are identifiers of the form
<code>$</code><strong>N</strong>
(<strong>N</strong>=0..9), which will be replaced
@@ -1178,20 +1233,23 @@
or it is explicitly terminated by a
<code><strong>L</strong></code> flag.</p>
- <p>There is a special substitution string named
- '<code>-</code>' which means: <strong>NO
- substitution</strong>! This is useful in providing
- rewriting rules which <strong>only</strong> match
- URLs but do not substitute anything for them. It is commonly used
- in conjunction with the <strong>C</strong> (chain) flag, in order
- to apply more than one pattern before substitution occurs.</p>
+ <div class="note"><h3>Modifying the Query String</h3>
+ <p>By default, the query string is passed through unchanged. You
+ can, however, create URLs in the substitution string containing
+ a query string part. Simply use a question mark inside the
+ substitution string to indicate that the following text should
+ be re-injected into the query string. When you want to erase an
+ existing query string, end the substitution string with just a
+ question mark. To combine new and old query strings, use the
+ <code>[QSA]</code> flag.</p>
+ </div>
- <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">flags</a> for <em>Substitution</em> by
+ <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
appending <strong><code>[</code><em>flags</em><code>]</code></strong>
as the third argument to the <code>RewriteRule</code>
- directive. <em>Flags</em> is a comma-separated list of any of the
- following flags: </p>
+ directive. <em>Flags</em> is a comma-separated list, surround by square
+ brackets, of any of the following flags: </p>
<ul>
<li>'<strong><code>chain|C</code></strong>'
@@ -1474,38 +1532,6 @@
<p>Although rewrite rules are syntactically permitted in <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections, this
should never be necessary and is unsupported.</p>
-</div>
-
-<div class="note"><h3>Note: Substitution of Absolute URLs</h3>
- <p>
- When you prefix a substitution field with
- <code>http://thishost[:thisport]</code>, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will automatically strip that
- out. This auto-reduction on URLs with an implicit
- external redirect is most useful in
- combination with a mapping-function which generates the
- hostname part.</p>
-
- <p><strong>Remember:</strong> An unconditional external
- redirect to your own server will not work with the prefix
- <code>http://thishost</code> because of this feature. To
- achieve such a self-redirect, you have to use the
- <strong>R</strong>-flag.</p>
-</div>
-
-<div class="note"><h3>What is matched?</h3>
- <p>The <em>Pattern</em> will initially be matched against the part of the
- URL after the hostname and port, and before the query string. If you wish
- to match against the hostname, port, or query string, use a
- <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
- <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
- <code>%{QUERY_STRING}</code> variables respectively.</p>
- <p>You can, however, create URLs in the substitution string containing a
- query string part. Simply use a question mark inside the substitution
- string, to indicate that the following text should be re-injected into the
- query string. When you want to erase an existing query string,
- end the substitution string with just a question mark. To
- combine new and old query strings, use the
- <code>[QSA]</code> flag.</p>
</div>
<p>Here are all possible substitution combinations and their
Modified: httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml?view=diff&rev=561840&r1=561839&r2=561840
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml Wed Aug 1 08:21:31 2007
@@ -1075,11 +1075,10 @@
<name>RewriteRule</name>
<description>Defines rules for the rewriting engine</description>
<syntax>RewriteRule
- <em>Pattern</em> <em>Substitution</em></syntax>
+ <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<override>FileInfo</override>
-<compatibility>The cookie-flag is available in Apache 2.0.40 and later.</compatibility>
<usage>
<p>The <directive>RewriteRule</directive> directive is the real
@@ -1095,6 +1094,17 @@
subsequent patterns are applied to the output of the last matched
RewriteRule.</p>
+<note><title>What is matched?</title>
+ <p>The <em>Pattern</em> will initially be matched against the part of the
+ URL after the hostname and port, and before the query string. If you wish
+ to match against the hostname, port, or query string, use a
+ <directive module="mod_rewrite">RewriteCond</directive> with the
+ <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
+ <code>%{QUERY_STRING}</code> variables respectively.</p>
+</note>
+
+
+
<p>Some hints on the syntax of <glossary ref="regex">regular
expressions</glossary>:</p>
@@ -1127,7 +1137,7 @@
<p>For more information about regular expressions, have a look at the
perl regular expression manpage ("<a
- href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
+ href="http://www.perldoc.com/perlre.html">perldoc
perlre</a>"). If you are interested in more detailed
information about regular expressions and their variants
(POSIX regex etc.) the following book is dedicated to this topic:</p>
@@ -1155,10 +1165,56 @@
cannot use <code>$N</code> in the substitution string!
</note>
- <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
- rewrite rule is the string which is substituted for (or
- replaces) the original URL which <em>Pattern</em>
- matched. In addition to plain text, it can include</p>
+ <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
+ rewrite rule is the string that replaces the original URL-path that
+ was matched by <em>Pattern</em>. The <em>Substitution</em> may
+ be a:</p>
+
+ <dl>
+
+ <dt>file-system path</dt>
+
+ <dd>Designates the location on the file-system of the resource
+ to be delivered to the client.</dd>
+
+ <dt>URL-path</dt>
+
+ <dd>A <directive
+ module="core">DocumentRoot</directive>-relative path to the
+ resource to be served. Note that <module>mod_rewrite</module>
+ tries to guess whether you have specified a file-system path
+ or a URL-path by checking to see if the first segement of the
+ path exists at the root of the file-system. For example, if
+ you specify a <em>Substitution</em> string of
+ <code>/www/file.html</code>, then this will be treated as a
+ URL-path <em>unless</em> a directory named <code>www</code>
+ exists at the root or your file-system, in which case it will
+ be treated as a file-system path. If you wish other
+ URL-mapping directives (such as <directive
+ module="mod_alias">Alias</directive>) to be applied to the
+ resulting URL-path, use the <code>[PT]</code> flag as
+ described below.</dd>
+
+ <dt>Absolute URL</dt>
+
+ <dd>If an absolute URL is specified,
+ <module>mod_rewrite</module> checks to see whether the
+ hostname matches the current host. If it does, the scheme and
+ hostname are stripped out and the resulting path is treated as
+ a URL-path. Otherwise, an external redirect is performed for
+ the given URL. To force an external redirect back to the
+ current host, see the <code>[R]</code> flag below.</dd>
+
+ <dt><code>-</code> (dash)</dt>
+
+ <dd>A dash indicates that no substitution should be performed
+ (the existing path is passed through untouched). This is used
+ when a flag (see below) needs to be applied without changing
+ the path.</dd>
+
+ </dl>
+
+ <p>In addition to plain text, the <em>Substition</em> string can include</p>
<ol>
<li>back-references (<code>$N</code>) to the RewriteRule
@@ -1173,6 +1229,7 @@
<li><a href="#mapfunc">mapping-function</a> calls
(<code>${mapname:key|default}</code>)</li>
</ol>
+
<p>Back-references are identifiers of the form
<code>$</code><strong>N</strong>
(<strong>N</strong>=0..9), which will be replaced
@@ -1192,21 +1249,24 @@
or it is explicitly terminated by a
<code><strong>L</strong></code> flag.</p>
- <p>There is a special substitution string named
- '<code>-</code>' which means: <strong>NO
- substitution</strong>! This is useful in providing
- rewriting rules which <strong>only</strong> match
- URLs but do not substitute anything for them. It is commonly used
- in conjunction with the <strong>C</strong> (chain) flag, in order
- to apply more than one pattern before substitution occurs.</p>
+ <note><title>Modifying the Query String</title>
+ <p>By default, the query string is passed through unchanged. You
+ can, however, create URLs in the substitution string containing
+ a query string part. Simply use a question mark inside the
+ substitution string to indicate that the following text should
+ be re-injected into the query string. When you want to erase an
+ existing query string, end the substitution string with just a
+ question mark. To combine new and old query strings, use the
+ <code>[QSA]</code> flag.</p>
+ </note>
<p>Additionally you can set special <a name="rewriteflags"
- id="rewriteflags">flags</a> for <em>Substitution</em> by
+ id="rewriteflags">actions</a> to be performed by
appending <strong><code>[</code><em>flags</em><code>]</code></strong>
as the third argument to the <code>RewriteRule</code>
- directive. <em>Flags</em> is a comma-separated list of any of the
- following flags: </p>
+ directive. <em>Flags</em> is a comma-separated list, surround by square
+ brackets, of any of the following flags: </p>
<ul>
<li>'<strong><code>chain|C</code></strong>'
@@ -1496,39 +1556,6 @@
type="section" module="core">Location</directive> sections, this
should never be necessary and is unsupported.</p>
-</note>
-
-<note><title>Note: Substitution of Absolute URLs</title>
- <p>
- When you prefix a substitution field with
- <code>http://thishost[:thisport]</code>, <module
- >mod_rewrite</module> will automatically strip that
- out. This auto-reduction on URLs with an implicit
- external redirect is most useful in
- combination with a mapping-function which generates the
- hostname part.</p>
-
- <p><strong>Remember:</strong> An unconditional external
- redirect to your own server will not work with the prefix
- <code>http://thishost</code> because of this feature. To
- achieve such a self-redirect, you have to use the
- <strong>R</strong>-flag.</p>
-</note>
-
-<note><title>What is matched?</title>
- <p>The <em>Pattern</em> will initially be matched against the part of the
- URL after the hostname and port, and before the query string. If you wish
- to match against the hostname, port, or query string, use a
- <directive module="mod_rewrite">RewriteCond</directive> with the
- <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
- <code>%{QUERY_STRING}</code> variables respectively.</p>
- <p>You can, however, create URLs in the substitution string containing a
- query string part. Simply use a question mark inside the substitution
- string, to indicate that the following text should be re-injected into the
- query string. When you want to erase an existing query string,
- end the substitution string with just a question mark. To
- combine new and old query strings, use the
- <code>[QSA]</code> flag.</p>
</note>
<p>Here are all possible substitution combinations and their