mod_rewrite is very useful in many situations. Yet some behaviors were not so obvious when I started to mess with it. After many tests, I understand it much better, now. Having said that, I do not pretend to know it perfectly. I also make mistakes.

So, although I tested all these on my local server and PowWeb, do not trust what I say blindly. Rather, please use it as a suggestion or bases for your own experiments.

First things first

You need these lines before any rules.

You need this in your .htaccess on some servers. You don't need it on PowWeb because it's already set. You must put this line once before to put RewriteRule. You don't have to put this in many cases. But specifying it can reduce the risk of endless looping.

Also, certain internal redirect rules and conditions will not work well if you don't use this line. So, put it, and forget about adding / at the beginning of the substitute string

REGEX is Perl compatible Regular expression.

ex. RewriteRule ^(abc.*)$ xxx$1 [R]
  ^ == beginning of URL
  $ == end of URL
  . (period) == matches any one character
  * == matches with zero or more of previous character.

RewriteRules may have additional Conditions.

RewriteCond STRING expression [optional flags]
RewriteRule REGEX substitution [optional flags]

For the details of REGEX, expressions, substitutions and options, you should read Apache module mod_rewrite documentation.

1. mod_rewrite documentation
2. URL rewriting Guide

What happens when the rules modify URL (in .htaccess)

When RewriteRule that changes URL is matched, modified URL will go through Next roud of processing from the beginning of the rule sets, again. This is a very important point.

It's because of the way Apache handles per-directory context (.htaccess, or in tab). It has to do per-directory auth and other processes for the newly generated path. In per-server or virtual host context (in httpd.conf), this doesn't happen.

In this example, URL is unchanged. (For this document, URL is the part of address without http://host.com/ and ?QUERY_STRING portion.)

Thus, it will not go through 2nd round of processing (the modification on QUERY_STRING does not affect this), unless it's a URL for a directory and transformed according to the DirectoryIndex directive or when resulting filepath doesn't exist.

RewriteRule ^xxx/(.*)$ yyy/$1

As the 1st rule changes URL, modified URL /xxx/abcSomething will go through next round and checked against from the 1st rule, again.

So, even the 1st rule has [L] (last) option to indicate following rules to be skipped, in the 2nd round, the URL will match the next rule, and modified to /yyy/abcSomething.

Then, this URL will go through 3rd round. But it will not match any rules, and the processing stops there.

How to avoid endless processing

If you make a mistake and processing go into endless loop, Apache will stop after preset numbers of times and issue 500 (Internal Server Error) with a log entry saying:

If you want to see that, try this. (on your home machine...)

ex.

One of the easiest method to avoid endless looping is using %{ENV:REDIRECT_STATUS}

Add loop stoper condition

RewriteRule ^(.*).html xyz/whatever.cgi?$1 [L]

The loop stopper rule for many following rules

RewriteRule ^ - [L]

Often RewriteCond with %{REQUEST_URI} has been used.

ex.

RewriteRule ^(.*)$ xyz/$1

Note 1. We don't need to put / in front of xyz in the right side of RewriteRule line, with RewriteBase /.

RewriteRule ^(.*)$ xyz/$1

RewriteRule ^(.*)$ index.php?p=$1

RewriteRule b.html a.html

RewriteCond %{THE_REQUEST} ^(GET|HEAD) /b.html
RewriteRule b.html a.html

RewriteCond %{QUERY_STRING} __XXX__$
RewriteRule /$ - [L]
RewriteCond %{QUERY_STRING} ^(.*)__XXX__$
RewriteRule ^(.*)$ $1?%1 [L]

# Add key string to the QUERY_STRING
RewriteRule ^(.*)$ $1?%{QUERY_STRING}__XXX__

# Following rules will be checked only onece,
# as long as QUERY_STRING is unmodified or the key string is kept.

# No modification to the QUERY_STRING
RewriteRule ^(other.*)$ rules/$1

# QUERY_STRING is conserved
RewriteRule ^(more.*)$ rules.cgi?$1%{QUERY_STRING}

# key string is placed, explicitly.
RewriteRule ^(yetmore.*)$ rules.cgi?$1__XXX___

I tried to use [E=ENVVAR:STRING] to distinguish the subsequest round but ENV
variables seem to be reset on each round... So, following example for preventing 2nd round does not work.


RewriteRule ^.*$ - [L]

RewriteRule ^.*$ - [L,E=DONE:YES]

RewriteRule ^pattern1$ substitute1
RewriteRule ^pattern2$ substitute2
RewriteRule ^pattern3$ substitute3

RewriteCond %{ENV:DONE} YES
RewriteRule ^patternX$ substituteX

# As this is not usually available to CGI program,
# it is very useful in DIY authentication with CGI.
RewriteRule ^.*$ - [E=HTTP_AUTH:%{HTTP:Authorization}]

# available in RewriteRules.
RewriteRule ^.*$ - [E=HTTP_TIME:%{TIME}]

QUERY_STRING can be used for passing parameters, too.

RewriteRule ^(.*)$ $1?AUTH=%{HTTP:Authorization} [QSA]

RewriteRule ^(.*)$ subdir/$1

# This is not efficient...and may not work sometime
# because the REQUEST_URI may contain "subdir/"
# in a part of QUERY_STRING, and also it matches
# "/sub/sub-subdir" and "/abcdefgsubdir/" and so on.


RewriteRule ^(.*)$ subdir/$1

RewriteEngine on
RewriteBase /

RewriteRule ^blank.txt - [L]

RewriteCond %{HTTP_USER_AGENT}
 (MSIECrawler|Ninja|Microsoft|MSFront|WebCopier|Pockey) [NC]
RewriteRule ^(.*)$  blank.txt [L]

RewriteRule ^/*(([^/]+)/+([^/]+)/+([^/]+)/*(.*)$ index.php?$1=$2&$3=$4 [L]

RewriteRule ^/*([^/]+)/+([^/]+)(.*)/*$ $3?$1=$2 [L,QSA]
RewriteRule ^([^/]+)$ index.php?$1 [L,QSA]

RewriteRule ^/*([^/]+)/+([^/]+)/+([^/]+)/+([^/]+)(.*)/*$ $5?$1=$2&$3=$4 [L,QSA]
RewriteRule ^([^/]+)$ index.php?$1 [L,QSA]

RewriteRule ^/*(([^/]+)/+([^/]+)/*(.*)$ index.php?aa=$1&bb=$2&$3 [L]

RewriteRule ^([^&]*)&(.*)$ $1%26$2 [NE,N]
RewriteRule ^([^&]*)$ whatever.php?title=$1 [L]

• mod_rewrite documentation
• URL rewriting Guide
• Commonly Used htaccess Code examples