From fc5122253ab7368941ab610077bc5948911b9117 Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Wed, 1 Aug 2007 15:21:31 +0000 Subject: [PATCH] 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 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@561840 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_rewrite.html.en | 124 ++++++++++++++++----------- docs/manual/mod/mod_rewrite.xml | 127 +++++++++++++++++----------- 2 files changed, 152 insertions(+), 99 deletions(-) diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en index 9951886790..030fcce8a8 100644 --- a/docs/manual/mod/mod_rewrite.html.en +++ b/docs/manual/mod/mod_rewrite.html.en @@ -1062,12 +1062,11 @@ later + PatternSubstitution [flags] -
Description:Defines rules for the rewriting engine
Syntax:RewriteRule - Pattern Substitution
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_rewrite
Compatibility:The cookie-flag is available in Apache 2.0.40 and later.

The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once, @@ -1082,6 +1081,17 @@ later subsequent patterns are applied to the output of the last matched RewriteRule.

+

What is matched?

+

The Pattern 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 + RewriteCond with the + %{HTTP_HOST}, %{SERVER_PORT}, or + %{QUERY_STRING} variables respectively.

+
+ + +

Some hints on the syntax of regular expressions:

@@ -1113,7 +1123,7 @@ later

For more information about regular expressions, have a look at the - perl regular expression manpage ("perldoc + perl regular expression manpage ("perldoc perlre"). 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:

@@ -1141,10 +1151,54 @@ contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string! -

The substitution of a - rewrite rule is the string which is substituted for (or - replaces) the original URL which Pattern - matched. In addition to plain text, it can include

+

The Substitution of a + rewrite rule is the string that replaces the original URL-path that + was matched by Pattern. The Substitution may + be a:

+ +
+ +
file-system path
+ +
Designates the location on the file-system of the resource + to be delivered to the client.
+ +
URL-path
+ +
A DocumentRoot-relative path to the + resource to be served. Note that mod_rewrite + 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 Substitution string of + /www/file.html, then this will be treated as a + URL-path unless a directory named www + 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 Alias) to be applied to the + resulting URL-path, use the [PT] flag as + described below.
+ +
Absolute URL
+ +
If an absolute URL is specified, + mod_rewrite 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 [R] flag below.
+ +
- (dash)
+ +
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.
+ +
+ +

In addition to plain text, the Substition string can include

  1. back-references ($N) to the RewriteRule @@ -1159,6 +1213,7 @@ cannot use $N in the substitution string!
  2. mapping-function calls (${mapname:key|default})
+

Back-references are identifiers of the form $N (N=0..9), which will be replaced @@ -1178,20 +1233,23 @@ cannot use $N in the substitution string! or it is explicitly terminated by a L flag.

-

There is a special substitution string named - '-' which means: NO - substitution! This is useful in providing - rewriting rules which only match - URLs but do not substitute anything for them. It is commonly used - in conjunction with the C (chain) flag, in order - to apply more than one pattern before substitution occurs.

+

Modifying the Query String

+

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 + [QSA] flag.

+
-

Additionally you can set special flags for Substitution by +

Additionally you can set special actions to be performed by appending [flags] as the third argument to the RewriteRule - directive. Flags is a comma-separated list of any of the - following flags:

+ directive. Flags is a comma-separated list, surround by square + brackets, of any of the following flags: