This document supplements the mod_rewrite reference documentation. It describes the use of the RewriteMap directive, -and provides examples of each of the various RewriteMap types.

A default value can be specified in the event that nothing is found @@ -108,41 +108,85 @@ in the map:

Per-directory and .htaccess context

-The RewriteMap directive may not be used in -<Directory> sections or .htaccess files. You must +The RewriteMap directive may not be +used in <Directory> sections or +.htaccess files. You must declare the map in server or virtualhost context. You may use the map, -once created, in your RewriteRule and -RewriteCond directives in those scopes. You just can't -declare it in those scopes. -

+once created, in your RewriteRule and +RewriteCond directives in those +scopes. You just can't declare it in those scopes.

The sections that follow describe the various MapTypes that may be used, and give examples of each.

int: Internal Function

+ + +

When a MapType of int is used, the MapSource is one + of the available internal RewriteMap + functions. Module authors can provide + additional internal functions by registering them with the + ap_register_rewrite_mapfunc API. + The functions that are provided by default are: +

+ +

toupper:
+ Converts the key to all upper case.
tolower:
+ Converts the key to all lower case.
escape:
+ Translates special characters in the key to + hex-encodings.
unescape:
+ Translates hex-encodings in the key back to + special characters.

+ +

+ To use one of these functions, create a RewriteMap referencing + the int function, and then use that in your RewriteRule: +

+ +

Redirect a URI to an all-lowercase version of itself

RewriteMap lc int:tolower
+RewriteRule "(.*)" "${lc:$1}" [R]

+ + +

Please note that the example offered here is for + illustration purposes only, and is not a recommendation. If you want + to make URLs case-insensitive, consider using + mod_speling instead. +

+ +

txt: Plain text maps

When a MapType of txt is used, the MapSource is a filesystem path to a - plain-text mapping file, containing space-separated key/value pair - per line. Optionally, a line may be contain a comment, starting with + plain-text mapping file, containing one space-separated key/value pair + per line. Optionally, a line may contain a comment, starting with a '#' character.

For example, the following might be valid entries in a map - file.

A valid text rewrite map file will have the following syntax:

# Comment line MatchingKey SubstValue MatchingKey SubstValue # comment -

When the RewriteMap is invoked the argument is looked for in the +

When the RewriteMap is invoked + the argument is looked for in the first argument of a line, and, if found, the substitution value is returned.

For example, we might use a mapfile to translate product names to +

For example, we can use a mapfile to translate product names to product IDs for easier-to-remember URLs, using the following recipe:

Product to ID configuration

@@ -170,7 +214,8 @@ telephone 328

Thus, when http://example.com/product/television is - requested, the RewriteRule is applied, and the request + requested, the RewriteRule is + applied, and the request is internally mapped to /prods.php?id=993.

Note: .htaccess files

@@ -202,7 +247,7 @@ telephone 328 One of these values will be chosen at random if the key is matched.

For example, you might use the following map +

For example, you can use the following map file and directives to provide a random load balancing between several back-end servers, via a reverse-proxy. Images are sent to one of the servers in the 'static' pool, while everything @@ -219,15 +264,15 @@ dynamic www5|www6

Configuration directives

RewriteMap servers "rnd:/path/to/file/map.txt"
 
-RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
-RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]

+RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L] +RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]

So, when an image is requested and the first of these rules is - matched, RewriteMap looks up the string + matched, RewriteMap looks up the string static in the map file, which returns one of the specified hostnames at random, which is then used in the - RewriteRule target.

+ RewriteRule target.

If you wanted to have one of the servers more likely to be chosen (for example, if one of the server has more memory than the others, @@ -255,7 +300,8 @@ static www1|www1|www2|www3|www4

RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"

The type can be sdbm, gdbm, ndbm or db. +

The type can be sdbm, gdbm, ndbm + or db. However, it is recommended that you just use the httxt2dbm utility that is provided with Apache HTTP Server, as it will use the correct DBM library, matching the one that was used when httpd itself was built.

@@ -269,7 +315,7 @@ $ httxt2dbm -i mapfile.txt -o mapfile.ma

Cached lookups

@@ -293,49 +339,6 @@ by many requests.

int: Internal Function

- - -

When a MapType of int is used, the MapSource is one - of the available internal RewriteMap functions. Module authors can provide - additional internal functions by registering them with the - ap_register_rewrite_mapfunc API. - The functions that are provided by default are: -

- -

toupper:
- Converts the key to all upper case.
tolower:
- Converts the key to all lower case.
escape:
- Translates special characters in the key to - hex-encodings.
unescape:
- Translates hex-encodings in the key back to - special characters.

- -

- To use one of these functions, create a RewriteMap referencing - the int function, and then use that in your RewriteRule: -

- -

Redirect a URI to an all-lowercase version of itself

RewriteMap lc int:tolower
-RewriteRule "(.*)" "${lc:$1}" [R]

- - -

Please note that the example offered here is for - illustration purposes only, and is not a recommendation. If you want - to make URLs case-insensitive, consider using - mod_speling instead. -

- -

prg: External Rewriting Program

When a MapType of prg is used, the MapSource is a @@ -363,8 +366,8 @@ RewriteRule "(.*)" "${lc:$1}" [R]

A simple example is shown here which will replace all dashes with underscores in a request URI.

- -

Rewrite configuration

+ +

Rewrite configuration

RewriteMap d2u "prg:/www/bin/dash2under.pl"

 RewriteRule "-" "${d2u:%{REQUEST_URI}}"

@@ -416,9 +419,9 @@ this process, or if the script itself is restarted.

If a query returns more than one row, a random row from -the result set is used.

+ the result set is used.

Example

RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

Example

RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

@@ -426,15 +429,15 @@ the result set is used.

Summary

The RewriteMap directive can occur more than - once. For each mapping-function use one - RewriteMap directive to declare its rewriting - mapfile.

The RewriteMap directive can + occur more than once. For each mapping-function use one + RewriteMap directive to declare + its rewriting mapfile.

While you cannot declare a map in per-directory context (.htaccess files or - <Directory> blocks) it is possible to - use this map in per-directory context.

+ <Directory> blocks) it is + possible to use this map in per-directory context.