What is matched?

Return-Path: Delivered-To: apmail-httpd-cvs-archive@www.apache.org Received: (qmail 78312 invoked from network); 1 Aug 2007 15:21:57 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 1 Aug 2007 15:21:57 -0000 Received: (qmail 22163 invoked by uid 500); 1 Aug 2007 15:21:57 -0000 Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org Received: (qmail 21964 invoked by uid 500); 1 Aug 2007 15:21:56 -0000 Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@httpd.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@httpd.apache.org Received: (qmail 21949 invoked by uid 99); 1 Aug 2007 15:21:56 -0000 Received: from Unknown (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 01 Aug 2007 08:21:56 -0700 X-ASF-Spam-Status: No, hits=-100.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 01 Aug 2007 15:21:47 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 7AA1E1A981A; Wed, 1 Aug 2007 08:21:32 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r561840 - in /httpd/httpd/trunk/docs/manual/mod: mod_rewrite.html.en mod_rewrite.xml Date: Wed, 01 Aug 2007 15:21:32 -0000 To: cvs@httpd.apache.org From: slive@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070801152132.7AA1E1A981A@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 @@ + 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 @@ 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 @@

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 @@ 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

back-references ($N) to the RewriteRule @@ -1159,6 +1213,7 @@
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 @@ 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:

'chain|C' @@ -1474,38 +1532,6 @@
Although rewrite rules are syntactically permitted in <Location> sections, this should never be necessary and is unsupported.
- - -
Note: Substitution of Absolute URLs
-
- When you prefix a substitution field with - http://thishost[:thisport], mod_rewrite 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.
- -
Remember: An unconditional external - redirect to your own server will not work with the prefix - http://thishost because of this feature. To - achieve such a self-redirect, you have to use the - R-flag.
-
- -
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.
-
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.

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 @@ RewriteRule Defines rules for the rewriting engine RewriteRule - Pattern Substitution + Pattern Substitution [flags] server configvirtual host directory.htaccess FileInfo -The cookie-flag is available in Apache 2.0.40 and later.
The RewriteRule directive is the real @@ -1095,6 +1094,17 @@ 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:
@@ -1127,7 +1137,7 @@
For more information about regular expressions, have a look at the perl regular expression manpage ("perldoc + href="http://www.perldoc.com/perlre.html">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:
@@ -1155,10 +1165,56 @@ 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 @@ -1173,6 +1229,7 @@
2. mapping-function calls (${mapname:key|default})
+
Back-references are identifiers of the form $N (N=0..9), which will be replaced @@ -1192,21 +1249,24 @@ 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 + id="rewriteflags">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:
- 'chain|C' @@ -1496,39 +1556,6 @@ type="section" module="core">Location sections, this should never be necessary and is unsupported.
  - - -Note: Substitution of Absolute URLs -
  - When you prefix a substitution field with - http://thishost[:thisport], mod_rewrite 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.
  - -
  Remember: An unconditional external - redirect to your own server will not work with the prefix - http://thishost because of this feature. To - achieve such a self-redirect, you have to use the - R-flag.
  - - -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.
  -
  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.
  
  Here are all possible substitution combinations and their

What is matched?

Modifying the Query String

Note: Substitution of Absolute URLs

What is matched?