MOD REWRITE Guide & Common Requests

*** The regular expressions used in rewrites are used to determine what is rewritten, not how it is rewritten. While you may not find an example that matches your needs verbatim, a quick modification to the regular expression will get you what you need. However, the example will provide you with the information on how the match is rewritten.

The following two rule sets differ only in what files are matched, not how the match is rewritten.

Code:

rewrite all HTML files

RewriteRule ^(.+)\.html$ $1.php

Code:

rewrite HTML files with numeric name (eg 1.html)

RewriteRule ^([0-9]+)\.html$ $1.php

Apache's Official Documentation
Apache's URL Rewriting Guide

mod_rewrite Cheat Sheet

1. open install_directory/conf/httpd.conf
2. uncomment or add the following line
   Code:

   LoadModule rewrite_module modules/mod_rewrite.so

3. Apache 1.3 users may need to uncomment or add the following line:
   Code:

   AddModule mod_rewrite.c

4. restart Apache

NOTE: the use of mod_rewrite requires Apache 1.3 or Apache 2.0+

NOTE: to prevent an error from affecting your entire domain, it is recommended that you create a sub-directory in your web root and run this test in that folder by using its .htaccess file.

RewriteEngine On

NOTE: When placing Rewrite* directives in .htaccess, you must have FileInfo privileges. In other words, AllowOverride FileInfo must be in httpd.conf for the directory (or one of its parents) in which .htaccess exists.

NOTE: When placing Rewrite* directives in .htaccess, you must enable FollowSymLinks. In other words, Options FollowSymLinks must be in httpd.conf for the directory (or one of its parents) in which .htaccess exists, or you must add it to .htaccess.

NOTE: .htaccess is the default access file on all Apache servers; it can be or could have been changed using the AccessFileName directive.

NOTE: not all Rewrite* directives are allowed in all contexts.

*** According to the documentation on .htaccess, it's always more efficient and secure to use httpd.conf instead of .htaccess. Using mod_rewrite in .htaccess is potentially more inefficient than other modules/directives because, according to Internal Processing » API Phases, by the time Apache gets to the point in an HTTP request where it reads .htaccess files, it's officially too late for a rewrite to occur. To solve this, mod_rewrite undoes some of Apache's work, does what it needs, then asks Apache to start its work over again.

RewriteEngine On

<Directory /usr/foo/public_html>
  RewriteEngine On
</Directory>

RewriteRule ^(.+)\.html$ $1.php

domain.com/foo.html -> domain.com/foo.php

RewriteRule ^(.+\.html)$ http://anotherdomain.com/$1 [R]

domain.com/foo.html -> anotherdomain.com/foo.html

NOTE: External redirects can also be obtained using Apache's mod_alias through the Redirect and RedirectMatch directive. These do not require mod_rewrite to be enabled. If you find yourself using a RewriteRule that results in an external redirect, and there is no corresponding RewriteCond, Redirect or RedirectMatch is the recommended alternative.

In the following example, RedirectMatch is used to create an external redirect equivalent to the previous mod_rewrite rule set.

Code:

RedirectMatch ^(.+\.html)$ http://anotherdomain.com$1

RewriteRule ^(.+)\.gif$ $1.jpg

domain.com/foo.gif -> domain.com/foo.jpg

domain.com/bar/baz.gif -> domain.com/bar/baz.jpg

RewriteCond %{REQUEST_URI} ^/png/
RewriteRule ^(.+)\.jpg$ $1.png

domain.com/foo.jpg -> domain.com/foo.jpg

domain.com/png/foo.jpg -> domain.com/png/foo.png

NOTE: There is no need to prepend "/png/"; mod_rewrite will do this for you.

domain.com/png/foo.gif -> domain.com/png/foo.jpg
domain.com/png/foo.jpg -> domain.com/png/foo.png

/home/foo/public_html/.htaccess
/home/foo/public_html/foo.php
/home/foo/public_html/real/
/home/foo/public_html/real/directory/

RewriteRule ^(.+)\.html$ foo.php?qs=$1

domain.com/bar.html -> domain.com/foo.php?qs=bar.html

domain.com/real/directory/bar.html -> domain.com/foo.php?qs=real/directory/bar.html

domain.com/bar.html -> Server Error: 404 Not Found

domain.com/real/directory/bar.html -> domain.com/foo.php?qs=bar.html

RewriteCond %{REQUEST_URI} ^(.+)$
RewriteRule ^.+\.html$ foo.php?qs=%1

domain.com/real/directory/bar.html -> domain.com/foo.php?qs=/real/directory/bar.html

/home/foo/public_html

RewriteRule ^(.*)$ /foo.php?qs=$1

foo.html

/foo.html

NOTE: in this example, <VirtualHost> also includes the following directive:

Code:

DocumentRoot /home/foo/public_html

foo.html

/home/foo/public_html/foo.html

/home/foo/public_html/foo.html

NOTE: RewriteLog and RewriteLogLevel can only be used in httpd.conf.

RewriteRule ^(.+)\.html$ $1.php [L]

domain.com/foo.html -> domain.com/foo.php

NOTE: PHP is exposed in the HTTP headers by default.

RewriteRule ^(.+\.html)$ $1 [T=application/x-httpd-php]

domain.com/foo.html -> domain.com/foo.html

NOTE: A better solution might be to put the following line in .htaccess instead of using mod_rewrite.

Code:

AddType application/x-httpd-php .php .html

The only advantage to mod_rewrite over the above code is that mod_rewrite allows the addition of RewriteCond directives or a more specific regular expression to specify which HTML files should be parsed as PHP.

RewriteRule ^([^/]+)/([^/]+)/?$ foo.php?name1=$1&name2=$2

domain.com/foo/bar -> domain.com/foo.php?name1=foo&name2=bar

NOTE: In order to use this method, one needs to know the number and order of the values being used in order to properly match that value with the correct name during the rewrite.

NOTE: This method is limited to nine pseudo-folder values.

domain.com/Georgia/Atlanta -> domain.com/info.php?state=Georgia&city=Atlanta

RewriteCond %{QUERY_STRING} ^$
RewriteRule ^(.+)/([^/]+)/([^/]+)$ $1?$2=$3 [QSA,E=TEST:$1]

RewriteCond %{ENV:TEST} ^(.+)/([^/]+)/([^/]+)$
RewriteRule ^.*$ %1?%2=%3 [QSA,E=TEST:%1,N]

RewriteCond %{ENV:TEST} ^([^/]+)/(.+)$ [OR]
RewriteCond %{REQUEST_URI} ^/([^/]+)/(.+)$
RewriteRule ^.*$ foo.php?%1=%2 [QSA,L]

domain.com/name1/value1/name2/value2/nameN/valueN -> domain.com/foo.php?name1=value1&name2=value2&nameN=valueN

In terms of extremely over-simplified code, it's the equivalent to this:

Code:

$i = 0;
while($i < $n)
  {
  $i++;
  }
print $i;

When a request is made for a single name/value pseudo-folder, the first RewriteRule is skipped b/c the Pattern doesn't match the initial request (the pattern requires characters (.+) and a preceeding forward slash (/) to match), so the [E] flag is never encountered, so the TEST environment variable gets no value. This causes the second RewriteCond to fail because the CondPattern does not match the TestString (the environment variable), which in turn causes the second RewriteRule to fail. The third RewriteCond also fails for the same reason the second RewriteCond did, but the fourth RewriteCond does not fail, the name and value are matched, and the request is rewritten using those matches.

Code:

domain.com/name1/value1 -> 
test name1/value1 with ^(.+)/([^/]+)/([^/]+)$: fails
environment variable TEST = ''

test name1/value1 with ^.*$: passes
test environment variable value '' with ^(.+)/([^/]+)/([^/]+)$: fails

test name1/value1 with ^.*$: passes
test environment variable value '' with ^([^/]+)/(.+)$: fails OR
test request uri value /name1/value1 with ^/([^/]+)/(.+)$: passes
domain.com/foo.php?name1=value1

A request for multiple name/value pseudo-folders is a little more involved. The first RewriteRule will only be effective the first time around (yes, I said first time) and is used to initially set the TEST environment variable. This first RewriteRule does two things: it rewrites the original request with a query string for the last name/value pair, and it sets the TEST environment variable to the original request less the last name/value pseudo-folders. The second RewriteRule is designed to always match the request (remember, according to Internal Processing, the second RewriteRule works on the rewritten result of the first RewriteRule) and run the second RewriteCond. The second RewriteCond checks the TEST environment variable created by the first RewriteRule to see if it has multiple name/value pseudo-folders remaining. If it does, the request is again rewritten with a query string for that last name/value pair, and the TEST environment variable is rewritten. The [QSA] flag tells mod_rewrite that this found name/value pair should be appended to the previously found name/value pair instead of replacing it. The [N] flag tells mod_rewrite to start over at the first RewriteRule (remember, I said the first RewriteRule would be visited again). This time, however, the first RewriteRule is skipped because QUERY STRING now has a value (mod_rewrite internally creates QUERY STRING when we rewrite a requst with a query string). This process of working with the rewritten request in the second RewriteRule and skipping the first RewriteRule is repeated until the second RewriteCond's CondPattern no longer matches the TEST environment variable, which occurs when only one name/value pair remains. What happens then has already been explained above.

Code:

domain.com/name1/value1/name2/value2/name3/value3 -> 
test name1/value1/name2/value2/name3/value3 with ^(.+)/([^/]+)/([^/]+)$: passes
test QUERY STRING with ^$: passes
name1/value1/name2/value2?name3=value3 ->
environment variable TEST = name1/value1/name2/value2
environment variable QUERY STRING = name3=value3 (mod_rewrite implicitly handles)

test name1/value1/name2/value2 with ^.*$: passes
test environment variable value 'name1/value1/name2/value2' with ^(.+)/([^/]+)/([^/]+)$: passes
name1/value1?name2=value2 ->
environment variable TEST = name1/value1
environment variable QUERY STRING = name2=value2&name3=value3 ([QSA] flag appends)

*** [N] flag restarts process ***

test name1/value1 with ^.*$: passes
test environment variable value 'name1/value1' with ^([^/]+)/(.+)$: passes
domain.com/foo.php?name1=value1&name2=value2&name3=value3 ([QSA] flag again)

NOTE: RewriteMap could also be used to accomplish this goal by passing the request to an external script.

NOTE: ForceType is another alternative.