The Rewrite Mod is often noted as the Swiss Army Knife of htaccess URL manipulation, a tool with unlimited functionality and flexibility though also one with a lot of complexity.

On that note it is also probably the most confusing feature for an htaccess novice, so don’t expect to understand this entire module in just one day.

The Rewrite Mod uses regular expression rules to rewrite requested URLs on the fly. It allows you to apply an unlimited amount of rules that can contain an unlimited amount of rule conditions to provide a really flexible and powerful URL manipulation tool. The rules rely on various server variables, environmental variables, HTTP headers, time stamps and even external database lookups.

So that my break down of the Rewrite Mod does become a never ending page I am going to break this article into three parts; rewrite directives, RewriteCond & RewriteRule, regular experessions & rewrite examples.

Part 1 – Rewrite Directives

RewriteEngine
This directive enables (on) or disables (off) the runtime rewriting engine. It allows you to turn your rewriting rules & conditions off instead of commenting them out.

RewriteOptions
This directive can set one of two options for the current per-server or per-directory configuration. The Option strings can be one of the following:

inherit
This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context this means that the maps, conditions and rules of the main server are inherited. In per-directory context this means that conditions and rules of the parent directory’s .htaccess configuration are inherited.

MaxRedirects=number
In order to prevent infinant redirects issued by per-directory RewriteRules, the mod_rewrite will abort a rewrite request after reaching a maximum number of such redirects and will respond with an 500 Internal Server Error. The default value is 10 redirects per request.

RewriteLog
This directive sets the name of the file to which the server logs any rewriting actions it performs. If the name does not begin with a slash (‘/’) then it is assumed to be relative to the Server Root.

RewriteLogLevel
This directive sets the level of the rewriting logfile. The default level 0 means no logging, while 9 or more means that all actions are logged.

Keep in mind that setting a high value will slow down your server dramatically! I only ever set the level greater than 2 for debugging!

RewriteLock
This directive sets the filename for a synchronization lockfile which mod_rewrite needs to communicate with RewriteMaps. Set the lockfile to a local path, and not on a mounted drive, when you want to use a rewriting map-program.

RewriteMap
I will elaborate more on this directive in a future post as it has some great features that should be explained in detail. Basically this directive defines a Rewriting Map which can be used inside rule substitution string. It defines a MapName and the lookup source. The map source can be standard plain text (txt), Randomized Plain Text (rnd), Hash File (dbm), Internal Function (int), or External Rewriting Program (prg).

Here is an example of a plain text map. Enter RewriteMap, then the map name, the type of map (this would be txt for plain text), and the root path to the file.

You would then include the mapname into the rewriterule like the following example:

RewriteBase
This directive sets the base URL for rewrites. The local directory prefix is stripped at this stage of processing and your rewriting rules act only on the remainder of the path. At the end it is automatically added back to the path.

RewriteBase can be used only once within a configuration.

RewriteCond
I am only going to give a brief overview on the RewriteCond and RewriteRule as I will explain more about the workings in part 2 and 3 with examples and scenarios.

The RewriteCond directive defines the conditions that would flag the use of the RewriteRule. There can be one or more conditions that effect a RewriteRule, and the RewriteRule will only be used if the conditions are met.

The basic syntax is “RewriteCond TestString CondPattern”.

The TestString is a condition variable use to match against the condition pattern. And the condPattern, or condition pattern, is a perl compatible regular expression with a few special extras. I’ll cover these in more detail in part 3.

The follow example checks the user agent, or browser type, to see if it is a Mozilla browser. If it is a match then the rule shows the specific page.

RewriteRule
This direction is where all the great action happens. This directive can be setup more than once though each instance can only define a single rewrite rule. The order of the rules is important as this will be the order that the rules are applied at run-time.

The basic syntax is “RewriteRule Pattern Substitution”

The “pattern” is a perl compatible regular expression. It is applied to the current URL.
The “substitution” is the string which replaces the original URL which the Pattern matched.

The following RewriteRule will change “example.com/test/” to “index.php?page=test”