RewriteMap directive

Description: Defines a key to value mapping function
Syntax: RewriteMap MapName MapType:MapSource
Context: server config, virtual host, directory, .htaccess

 

RewriteMap directive is used to define a key-to-value lookup function. This is useful when you need to map large amount of values since it is much faster than doing it with rule matching. Performance of map function rely on a size of map file insignificantly. There are three types of mapping:

  • txt: mapping using text file map;
  • rnd: random value select from multiple choices;
  • int: internal functions.

MapName is the name of mapping function that will be used to refer to this map from RewriteRule command. Make sure that every mapping is defined with a unique name. You can call mapping function in the Substitution value of RewriteRule directive using the following syntax:

${ MapName : LookupKey | DefaultValue }

If this construction is found in Substitution, ISAPI_Rewrite will lookup for the key in the map and if one is found, substitute the construct by its value. If no key is found, optional DefaultValue will be used. If no DefaultValue is specified, it will be substituted by an empty string.

Here is an example of declaring maps:

RewriteMap examplemap txt:C:/path/to/file/map.txt

Path to MapSource file coule be either absolute or relative. Relative path are calculeted from the folder with current configuration file, i.e. from the configuration file path where this map has been declared.

Then you may use this map in RewriteRule as follows:

RewriteRule ^/ex/(.*) ${examplemap:$1}

The following combinations for MapType and MapSource can be used:

txt: Plain text mapping. The source is a Windows file system path to a valid text file. Text file should be of the following format:

#This is a comment

key1 value1 #Another comment
key2 value2
keyN valueN

rnd: Random multiple values lookup. Source is the path to a text file of the following format:

#This is a comment

key1 value1|value2|value3
key2 value4|value5|value6|valueN

int: Internal function call. Source should be one of the following pre-defined internal functions:

  • toupper: Converts the key to all upper case.
  • tolower: Converts the key to all lower case.
  • escape: Encode special characters to hex values.
  • unescape: Unencode hex values to special characters.