When people think of .htaccess configuration the first thing that pops into most people’s minds is URL manipulation with mod_rewrite. People typically get frustrated with mod_rewrite’s complexity. This tutorial will walk you through everything you need to know for the most common mod_rewrite tasks.

When people think of .htaccess configuration the first thing that pops into
most people’s minds is URL manipulation with mod_rewrite. Thoughts on
mod_rewrite vary quite a bit. To get a quick feel for what the world thinks
for it I just ran a twitter search on “mod_rewrite” and picked a few from the
front pages at the time I started this article:

mldk: Aargh! .htaccess and mod_rewrite can be such
a pain in the —!

bsterzenbach: Man do I love mod_rewrite. I
could work with it the rest of my life and still not master it – so powerful

mikemackay: Still loving the total
flexibility of mod_rewrite – coming to the rescue again. Often so
overlooked…and easier than you might think too!

hostpc: I hate mod_rewrite. Can’t get this dang
application to work properly

awanderingmind: Oh Wordpress and
Apache, how thou dost vex me. Mod_rewrite be damned!

danielishiding: Why won’t mod_rewrite
work! Damn it!

A few things I noticed are that people clearly recognize the power of
mod_rewrite but are often frustrated by the syntax. Thats not surprising
considering the front page of Apache’s mod_rewrite documentation says
basically the same thing:

Despite the tons of examples and docs, mod_rewrite is voodoo. Damned cool
voodoo, but still voodoo.” — Brian Moore

What a turn off! So, in this article I’m really going to take things down a
notch. I’m going to try and address not only mod_rewrite’s syntax but try and
provide a workflow that you can use to debug and solve your mod_rewrite
problems. I’m also going to give you a few useful real-world examples.

However, before I start I’m going to give a warning. With many subjects, this
one in particular, you won’t learn unless you try on your own! That is one of
the reasons I’m going to focus on teaching a debug workflow. As usual I’ll
show you how to get your system setup if you don’t already have the module
loaded. I urge you to work through the examples on your own server, preferably
in a test environment. The more experience and success that you have the
easier it will be to expand on that knowledge to more advanced examples and
applications. Enjoy.

What is mod_rewrite?

mod_rewrite is an Apache module that allows for
server-side manipulation of requested URLs. Incoming URLs are checked against
a series of rules. The rules contain a regular expression to detect a
particular pattern. If the pattern is found in the URL, and the proper
conditions are met, the pattern is replaced with a provided substitution
string or action. This process continues until there are no more rules left or
the process is explicitly told to stop.

This is summarized in these three points:

• There are a list of rules that are processed in order.
• If a rule matches it checks the conditions for that rule.
• If everything is a go it makes a substitution or action.

Advantages of mod_rewrite

There are some obvious advantages of using a URL rewriting tool like this but
there are some things that are probably not as obvious.

The main reason people use mod_rewrite are to transform ugly, cryptic URLs into
what are known as “friendly URLs” or “clean URLs.” The new URLs are
friendly in more ways then one. They are user friendly often making it much
easier for humans to understand at a glance and possibly manipulate on their
own. As an added bonus these URLs are also more search engine friendly.
Creating friendly URLs is one search engine optimization technique. URLs are an
effective way to describe the content its linking to. Take the following example:

Not so friendly: http://example.com/user.php?id=4512
Much friendlier: http://example.com/user/4512/
Even better:     http://example.com/user/Joe/

Not only is the final link easier on the eyes, its possible for search engines to
extract semantic meaning from it. This basic kind of URL rewriting is one way
that mod_rewrite is used. However, as you will see it can do a lot more
then just these simple transformations.

Expanding on the same example, some people claim there are security benefits
by having mod_rewrite tranform your URLs. Given the same example, imagine
the following attack on the user id:

http://example.com/user.php?id=AHHHHHH

http://example.com/user/AHHHHHH/

In the first example the php script is explicitly being invoked and must handle
the invalid id number. A poorly written script would likely fail and in a more
extreme case (in a poorly written web application) bad input could cause data
corruption. However, if the user is only ever shown the friendlier URLs they
wouldn’t even know that the user.php page existed. They might only know about
the friendly URL structure. Trying the same attack in that case would likely fail
before it even reaches the php script. This is because at the core of mod_rewrite is
regular expression pattern matching. In the example case above you would have
been expecting a number, for example (\d+), not characters like a-z. The
rewrite would have failed as soon as it found letters instead of numbers.

This extra layer of abstraction is nice from a security perspective. You could
even prevent direct access to the original PHP scripts if you wanted. However,
I am in no way condoning using mod_rewrite as a replacement for the usual
security measures. You should always have server-side validation in your
scripts.

Enabling mod_rewrite on the Server

Just like enabling .htaccess support, enabling mod_rewrite or any apache module
must be done from the global configuration file (httpd.conf). Just as before,
since mod_rewrite usage is so widespread hosting companies nearly always have
it enabled. However, if you suspect that your hosting company does not have it
enabled, and we will test for that below, you should contact them and they will
likely enable it.

If you rolled your own Apache installation its worth noting that mod_rewrite
needs to be included when compiled Apache, as it is not done so by default.
However, its so common that nearly all installation guides, including
Apache’s show how in their example. However, pre-packaged versions will
have it enabled. If you’re reading this there is probably a 99% chance that
mod_rewrite is compiled on your Apache, so you can just proceed to the next
step.

If you’re the administrator for your webserver and you want to make sure that
you load the module you should look in the httpd.conf file. In the
configuration file there will be a large section which just loads a whole
bunch of modules. The following line will likely appear in the file. If it
is, great! If its commented out, meaning there is a # symbol at the start
of the line then remove the # to be left with:

LoadModule rewrite_module modules/mod\_rewrite.so

Olders version of Apache 1.3, may require you to add the following directive,
after the LoadModule directive.

# Only in Apache 1.3
AddModule mod\_rewrite.c

However, this seems to have disappeared in Apache 2 and later. Only the
LoadModule directive is required.

If you had to modify the configuration file at all then you will have to
restart the web server. As always you should remember to make a backup of the
original file in case you need to revert back to it later.

Testing for mod_rewrite

You can test if mod_rewrite is enabled/working in a number of ways. One of the
simplest ways is to view the output from PHP’s phpinfo function. Create this
very simple PHP page, open it in your browser and search for “mod_rewrite” in
the output.

<?php phpinfo(); ?>

mod_rewrite should show up in the “Loaded Modules” section of the page like so:

However, if you’re not using PHP (although I will for the rest of the tutorial)
there are some others ways to check. Apache comes with a number of command
line tools. I mentioned the htpasswd tool in the first tutorial for Basic
Authentication. You can use other tools like apachectl or httpd to directly
test for the module. There are command line switches that allow
you to check all of the loaded modules in the existing installation. You
can execute the following to get a listing of all of the loaded modules.

 shell> apachectl -t -D DUMP_MODULES 

Here I show the help page for the command. I then run the command and
search for “rewrite” in the results and it shows there was a line of output
that matched!

Finally, if you are still unsure if its enabled, like before just give it a
shot and see what happens! I’ll go over the syntax later but here would be
a very bare bones test to see if its working. The following .htaccess file
would redirect any request in the given folder to the good.html file. That
means if mod_rewrite is working you should see good.html. If mod_rewrite
is not working then you will see index.html which shows a warning.

# Redirect everything in this directory to "good.html"
RewriteEngine on
RewriteRule .* good.html

Here are the Good and Bad result pages:

Inside .htaccess

As always, anything that you can put in a .htaccess file can also be put inside
the global configuration file. With mod_rewrite there is a small differences
if you put a rule in one or the other. Most noticeably:

if you’re putting […] rules in an .htaccess file […] the directory
prefix (/) is removed from the REQUEST_URI variable, as all requests are
automatically assumed to be relative to the current directory.
– Apache Documentation

Just something to keep in mind if you see examples online or if you’re trying
an example yourself, beware of the leading slash! I will attempt to clarify
this below when we got through some examples together.

Regular Expressions

This tutorial does not intend to teach you regular expressions. For those of
you that know regular expressions, the regular expressions used in mod_rewrite
seem to vary between versions of Apache. In Apache 2.0 they seem to be
Perl Compatible Regular Expressions (PCRE). This means that many of the
shortcuts you are used to, such as \w meaning [A-Za-z0-9_], \d meaning
[0-9], and much more do exist. However, my hosting company uses Apache 1.3
and the regular expressions are more limited.

If you don’t know regular expressions here are some useful tutorials that will
bring you up to speed quickly.

• Nettuts very own Jeffrey’s Crash Course
• The Absolute Bare Minimum Every Programmer Should Know About Regular Expressions
• Quick And Practical Tutorial
• Smashing Magazine Links on Regular Expressions

And a few references that everyone should know about:

• Popular Added Bytes Cheatsheet For Regular Expressions
• Added Bytes Cheatsheet for mod_rewrite
• Explain Regular Expressions

If you haven’t spent the time to learn regular expressions I highly suggest
that you take the time to learn them. As is usually the case, they are not as
complex as you may think they are. I selected the links above from my years of
experience working with regular expressions. I feel that these guides do a very
good job of getting the basics across. Regular Expressions are crucial to know
if you want to effectively use mod_rewrite, and they are also useful to know
for many different aspects of general development, such as “find/replace” in
your favorite code editor!

Getting a Feel for it.

Okay, you’ve waited patiently enough, lets run through a quick example. This is
included in the linked source files. Here is the code from the .htaccess file:

# Enable Rewriting
RewriteEngine on

# Rewrite user URLs
#   Input:  user/NAME/
#   Output: user.php?id=NAME
RewriteRule ^user/(\w+)/?$ user.php?id=$1

Before I can explain any of it I have to give you more information about the
other files in the directory.

The directory contains an index.php and a user.php file. The index just has
some links, of various formats, to the user page. The php code is purely debug
to show that the page was accessed and what the given “id” parameter contained.
Here is user.php code:

<?php

// Get the username from the url
$id = $_GET['id'];

?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>Simple mod\_rewrite example</title>
    <style type="text/css"> .green { color: green; } </style>
</head>
<body>
  <h1>You Are on user.php!</h1>
  <p>Welcome: <span class="green"><?php echo $id; ?></span></p>
</body>
</html>

This example has a few different parts. First, notice that URL Rewriting must
be enabled via the RewriteEngine directive! If your .htaccess file is going
to use rewrite rules you should always include this line, otherwise you can’t
be sure if its enabled or not! As a rule of thumb, always include it and make
sure that you only have it once per .htaccess file. The string “on” is case
insensitive. So when you see other examples on the net that show “On”, that
is equally acceptable.

The first RewriteRule is for handling the user.php page. As the comments
indicate we are rewriting the friendly URL into the format of the normal URL.
To do that, when the friendly URL comes in as input we are actually
transforming it into the standard query string URL. Breaking it down we get:

The Rule:
RewriteRule ^user/(\w+)/?$ user.php?id=$1

Pattern to Match:
^              Beginning of Input
user/          The REQUEST_URI starts with the literal string "user/"
(\w+)          Capture any word characters, put in $1
/?             Optional trailing slash "/"
$              End of Input

Substitute with:
user.php?id=   Literal string to use.
$1             The first (capture) noted above.

Here are some examples and an explanation for each:

So the first example goes through unaffected by the RewriteRule and works
just fine. The second and third examples match the RewriteRule, are
rewritten accordingly and end up working just fine. The last example does not
match the rule and proceeds untouched. The server doesn’t have a
user directory and fails trying to find it. This is as expected because
user/joe/x is a bad URL in the first place!

This example was rather easy to understand. However, there were a lot of
minute details that I glossed over. To do anything more complex I want to
clarify exactly what is happening. In the next section I’m going to walk
through exactly what happens and we will take a look at a more complex
example that touches on all the core aspects of rewriting.

NOTE: If this example didn’t work for you its possible that your Apache or
mod_rewrite versions are not PCRE compatible. Try changing ^user/(\w+)/?$
into ^user/([a-z]+)/?$. Notice that I did not use the \w shorthand. If
this version works for you then you will have to avoid the regex shortcuts
and instead use their longer equivalents (see the Regular Expressions section
above).

Flow of Execution in Detail

The flow of execution through the rewrite rules is simple but its not exactly
straightforward. So, I’m going to break it down into painful detail. It all
starts with the user making a request to your server. They type a URL into
their browser’s address bar, their browser translates that into an HTTP request
to send to the server, Apache receives that request, and parses it into pieces.
Here is an example:

Note that whenever I mention one of Apache’s variables I use a weird syntax:
%{APACHE_VAR}. That is just because its similar to the syntax that
mod_rewrite uses to access the variables. However, it is the name inside the
braces that is important.

So what part does mod_rewrite deal with? If you’re working inside a .htaccess
file, then you’re working with the REMOTE_URI portion but without the leading slash!
I mentioned this before, and its something that is very confusing for most
people when they start out. If you’re working from inside the global
configuration file, then you would leave the leading slash in.

To be as specific as possible, buried in the Apache Documentation is
this description of the “URL Part” that mod_rewrite acts on:

The Pattern is always a regular expression matched against the URL-Path of
the incoming request (the part after the hostname but before any question
mark indicating the beginning of a query string).
Apache Documentation

To remove any ambiguity, highlighted in gold in these two URLs below is the
“URL Part” that mod_rewrite acts on inside a .htaccess file:

For the rest of this section I’ll be using these two URLs to describe the flow
of execution. I will refer to the first url as the “green” URL and the second
as the “blue” URL. Also I will be using “URL Part” throughout this analysis,
meaning the REMOTE_URI without the leading slash.

For those readers that want to be 100% technical these two things that I am
calling URLs are actually URIs. The definition of a Uniform Resource
Identifier (URI) differs from a Uniform Resource Locator (URL). A URI is just
an indicator of where a resource is. This means that multiple URIs can point
to the same resource but are themselves different addresses. Following a URI
might take any number of hops or redirections until it actually arrives at the
resource. A URL however, is a stricter term that identifies the exact location
of a resource. This subtle difference has blurred over time such that nobody
cares about the difference. I will continue to use the term URL because people
are more comfortable with it.

So, now we know what the rewrite rules are going to be acting on. Once Apache
has parsed the request it translates that to the file it thinks is needed and
proceeds to fetch that file. At this point it will traverse directories and
encounter the .htaccess files. Assuming the .htaccess file enables the
RewriteEngine any RewriteRule could change the URL. A drastic enough change
(such as one that points Apache to another directory instead of the original
directory it was heading towards) will cause Apache to issue a sub-request
and proceed to fetch the new file.

In most cases sub-requests are invisible to you. This implementation detail
is not important to know for the majority of the simple rewrites that you will
ever write or use. What is more important to know is how Apache processes
the rewrite rules inside a .htaccess file.

The rules in a .htaccess file are processed in the order that they appear.
Note that each RewriteRule is acting on the “URL Part” that is similar to
the REMOTE_URI. When a rule makes a substitution, the modified “URL Part”
will be handed to the next rule. That means that the URL that a rule is
processing may have been edited by a previous rule! The URL is continually
being updated by each rule that it matches. This is important!

Here is a flow chart that tries to provide a visualization of the generic
flow of execution across multiple rules in a .htaccess file:

Note that at the top of the flow chart the value going into the rewrite rules
is that “URL Part” and if the substitution is successful the modified part
proceeds into the next rule.

I mentioned rewriting conditions earlier but I didn’t go into detail. Each
RewriteCond is associated with a single RewriteRule. The conditions appear
before the rule they are associated with, but only get evaluated if the rule’s
pattern matched. As the flow chart shows, if a rewrite rule’s pattern matches
then Apache will check to see if there are any conditions for that rule. If there
are no conditions then it will make the substitution and continue. If there
are conditions then it will only make the substitution if all of the
conditions are true. Lets visualize this in a concrete example.

The URLs that I’m working with are actually part of the “Profile Example” that
I’ve included in the source code download in the “profile_example” directory.
This is similar to the previous example with the user.php but it now has a
profile.php page, an added rewrite rule, and a condition! Lets take a look at
the code and Apache’s flow of execution through it:

Here there are two rules. Rule #1 is the same as the user example we saw
before. Rule #2 is new and notice that it has a Condition. The “URL Part” we
have been discussing goes through the rules in order, top to bottom. So it will
first go through Rule #1 and then Rule #2.

The key to understanding this example is to first understand the goal. In this
example I am going to allow friendly profile URLs but I’m actually going to
explicitly forbid access to the php page directly. Note, some people might say
that this is a bad idea. They might say that as a developer this will make
things harder for you to debug. Thats true, I don’t actually recommend doing a
trick like this, but it makes for an excellent example! More practical uses for
mod_rewrite will show up later in this tutorial.

So, with that in mind lets see what happens with our green URL. This one we want
to be successful.

Up at the top you see Apache’s THE_REQUEST variable. I put this at the top
because, unlike many of the Apache variables we will deal with, during the
duration of the request this variables value will never change! That is one
of the reasons why Rule #2 uses %{THE_REQUEST}. Underneath THE_REQUEST we
see the green “URL Part” going into the first rule:

• The URL matches the pattern.
• There are no conditions, so it continues.
• The substitution is made.
• There are no flags, so it continues.

After making it through the first rule, the URL has changed. The total URL has
been rewritten to profile.php?id=joe which Apache then breaks down and
updates many of its variables. The ?id=joe portion gets hidden from us and
profile.php, the new “URL Part”, continues into the second rule. It is our
first encounter with conditions:

• The URL matches the pattern.
• There are conditions so we will try the conditions.
• THE_REQUEST does not contains profile.php so the condition fails.
• Because a condition failed we ignore the substitution and flags.
• The URL is unchanged by this rule.

At this point we made it through all the rewrites and the profile.php?id=joe
page will be fetched properly.

Here is how the execution looks for the blue URL, the one we want to fail:

Again I put the THE_REQUEST value at the top. The blue “URL Part” enters
Rule #1:

• The URL does not match the pattern.
• Everything else is ignored and the URL proceeds unchanged.

The first rule was easy. As is often the case a URL that you have won’t match
a rule’s patten and will proceed untouched. Now it enters Rule #2:

• The URL matches the pattern.
• There are conditions so we will try the conditions.
• THE_REQUEST contains profile.php so the condition passes.
• All the conditions passed we can make the substitution.
• ”-” is a special substition that means don’t change anything.
• There are flags on the rule so we process the flags
• There is a F flag which means return a forbidden response.
• A 403 Forbidden response is sent to the client.

A few things are worth re-iterating. In order for the substitution to work, all
of the conditions have to pass. In this case there is only one, and it passes
so the substitution happens. Note that - is a special substitution that
doesn’t change anything. This is useful when you just want to use flags to do
something for you, which is exactly what we want to do in this case.

Here is the familiar table breakdown of example URLs and their responses:

Syntax

While going over the syntax of RewriteRule and RewriteCond I would suggest
that you first download the AddedBytes Cheatsheet. This is because
the cheatsheet lists the most useful server variables, flags, has regular
expression tips, and even a few examples. There is just so much there that it
would be difficult to put it inline.

Lets start with RewriteRule. You can always visit
Apache’s Documentation on RewriteRule if you need to do something
really specific. Here is my overview:

The cheatsheet shows what types of flags are available. Many tutorials cover these
flags in detail, and I’ll go through the flags that I see most commonly used in
the examples below.

Here is Apache’s Documentation on RewriteCond and my overview:

Debug Workflow

Whenever you’re working with mod_rewrite and creating new rules, always
start with a simple, dumbed down version of the rule and work your way
up towards the final version. Never try to do everything at once. The same
thing applies for conditions. Add rules and conditions one at a time.
Test often!

The key concept I am trying to get across with this approach is that this will
let you know quickly if a change you made doesn’t work properly or causes
something to work incorrectly. When doing too much at once inevitably you will
run into an error and you will have to revert all of the changes you made to
track down what the problem was. This is a very roller coaster approach and
will likely lead to frustration. However, if you’re always steadily advancing,
and each step along the way moving to workable checkpoints you’re in much,
much better shape.

People often ignore this advice, create a complex rule, and it ends up not
working. Hours later they find out the problem was not in the complex portion,
but instead it was just a simple mistake in the regular expression that could
have been caught much earlier had they carefully constructed the rule like
I’ve explained above. The same goes for deconstructing a rule to reverse
engineer a problem. This approach will seriously reduce frustration!

In the Examples

In the examples below I will always assume the website’s domain is
example.com. This domain name is important because it affects the
HTTP_HOST variable as well as specifying a redirect URL to another file on
your website. Keep this in mind in case you intend to modify any of the examples
for your own website. If so, simply replace “example.com” with your domain.
For example, Nettuts would replace “example.com” with “nettuts.com”.

Removing www

This is the most classic rewrite rule. This will make it so anyone who comes
to your website via http://www.example.com they will get a hard redirect and
thus the Location Bar in their browser will update accordingly.

RewriteEngine on
RewriteCond %{HTTP_HOST} ^www\.example\.com$ [NC]
RewriteRule ^(.*)$ http://example.com/$1 [R=301,L]

The rule matches anything, and saves everything as $1. The important part
in this example is the condition. The condition checks the HTTP_HOST variable
to see if it started with “www.” If this condition is true, the rewrite
happens:

• The substitution is a full URL (it starts with http://)
• The substitution contains $1 which was captured earlier
• The [R=301] flag redirects the browser to the rewritten URL, this is a hard
  redirect in the sense that it causes the browser to load the new page and
  update its Location Bar with the new URL.
• The [L] flag means that this is the last rule to parse, the rewrite engine,
  should stop.

If the incoming URL had been “http://www.example.com/user/index.html” then
HTTP_HOST would have been www.example.com and the rewrite would happen
creating http://example.com/user/index.html.

If the incoming URL had been “http://example.com/user/index.html” then
HTTP_HOST would have been example.com, the condition would have failed
and the rewrite engine would proceed with the URL unchanged.

Forbid Hotlinking

Hotlinking, referred to as Inline Linking on Wikipedia, is the term
used to describe one site leeching off of another site. Usually one site, the
Leecher, will include a link to some media file (lets say an image or video)
that is hosted on another site, the Content Host. In this scenario, the
Content Host’s servers are wasting bandwidth serving content to some other
website.

For many people, its fine if other sites cross link to their content. However,
many people would rather prevent hotlinking so as not to pay for the extra
bandwidth required to send the content to someone else’s site.

The most common, and basic approach to preventing hotlinking is to whitelist
a number of websites, and block everything else. To find out who is asking
for the content from your site you can check the referrer. The HTTP_REFERER
header (yes that is how it is spelled) is set by the browser or client that
is requesting the resource. In the end this is not 100% reliable, however it
is more then effective at stopping the majority of hotlinking. So, verify
if the referrer is in a whilelist of acceptable referrers. If the referrer
is not acceptable (blank or someone else’s site) then you can send them
a forbidden warning:

# Give Hotlinkers a 403 Forbidden warning.
RewriteEngine on
RewriteCond %{HTTP_REFERER} !^http://example\.net/?.*$ [NC]
RewriteCond %{HTTP_REFERER} !^http://example\.com/?.*$ [NC]
RewriteRule \.(gif|jpe?g|png|bmp)$ - [F,NC]

Here the RewriteRule is checking for a request of a file with any popular
image extension. Such as .gif, .png, or .jpg. You could add other extensions
to this list if you want to protect .flv, .swf, or other files.

The domains that are allowed to access the content are “example.net” and
“example.com”. In either of these two cases a Rewrite Conditions will fail
and the substitution won’t happen. If any other domain makes an attempt, lets
say “sample.com” attempts, then all the Rewrite Conditions will pass, the
substitution will happen, and the [F] forbidden action will trigger.

Give Hotlinkers a Warning Image

The previous example returns a 404 Forbidden warning when someone trys to
hotlink content from your server. You can actually go one step further, and
send the hotlinker any resource of your choice. For example you can send
a useful warning image can just be some text stating “hotlinking is not
allowed”. This way the other person can realize their mistake and host a copy
on their own server. The only change is to actually go through with the rewrite
substitution and provide a choosen image instead of the one being requested:

# Redirect Hotlinkers to "warning.png"
RewriteEngine on
RewriteCond %{HTTP_REFERER} !^http://example\.net/?.*$
RewriteCond %{HTTP_REFERER} !^http://example\.com/?.*$   [NC]
RewriteRule \.(gif|jpe?g|png|bmp)$ http://example.com/warning.png [R,NC]

Note that this is an example of what I call a “hard” or “external” redirect.
The RewriteRule has a URL in the substitution portion and it also has the [R]
flag.

Custom 404

One trick that you can do with htaccess is check to see if the current “URL Part”
leads to an actual file or directory on the web server. This is a good way to
create a custom 404 “File not Found” page. For example, if a user trys to
fetch a page in a particular directory that doesn’t exist you can redirect them
to any page you want, such as the index page or a custom 404 page.

# Generic 404 to show the "custom_404.html" page
# If the requested page is not a file or directory
# Silent Redirect: the user's URL bar is unchanged.
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule .* custom_404.html [L]

This is a great example of mod_rewrite’s file test operators. They are
identical to file tests in bash shell scripts and even Perl scripts. Here
the condition checks if the REQUEST_FILENAME is not a file and not a
directory. In the case where it is neither, then then there is no such
file for the request.

If the incoming request filename can’t be found then this loads
a “custom404.html” page. Note that there is no [R] flag, so this
is a silent redirect, not a hard redirect. The user’s Location Bar
will not change, but the contents of the page will be
“custom404.html”. Short and simple.

Safety First

If you have mod_rewrite snippets that you use often and want to easily
distribute to other servers or environments you may want to be careful. As
was mentioned, any invalid directive in a .htaccess file will likely cause
internal server errors. So if an environment you move the snippet to doesn’t
have mod_rewrite you could temporarily break it.

One solution to this problem is the “check” for the mod_rewrite module. This
is possible with any module. Just wrap your mod_rewrite code in an
<IfModule> block and you’ll be all set:

<IfModule mod_rewrite.c>

  # Turn on
  RewriteEngine on

  # Always remove www (with a hard redirect)
  RewriteCond %{HTTP_HOST} ^www\.example\.com$ [NC]
  RewriteRule ^(.*)$ http://example.com/$1 [R=301,L]

  # Generic 404 for anyplace on the site
  # ...

</IfModule>

Conclusion

I hope that this tutorial proves that mod_rewrite isn’t all that scary, and in
fact its quirks and speed bumps can be avoided with careful development
practices.

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for more daily web development tuts and articles.