CodingForums.com - Mod_Rewrite How-To Guide

Apache's Mod_Rewrite How-To Guide

Helpful Resources

Editorial Note: If you find anything in this guide that is incorrect, or would like content added, please Send a PM to ShaneC. Mod_Rewrite questions should be posted in the Apache Configuration forum.

Note: Guide Assumptions

This guide assumes that you're using the following:

Apache 1.3 or later
PHP
Apache's Mod_Rewrite Module enabled on your server

Important: Make sure Mod_Rewrite is Installed and Enabled

On some web hosts Mod_Rewrite is not enabled by default.

To check if mod_rewrite is installed:

Note: In most PHP configurations you can detect if Mod_Rewrite is installed with the method below. If, however, you're using CGI / SuPHP you will have to check the Apache httpd.conf file manually.

Create a PHP page on your web server. For demonstration purposes, call this page phpinfo.php. This file should read as follows:

PHP Code:


		
			
<?php phpinfo(); ?>

Now, navigate to this page in your browser and look under the Loaded Modules section. This can be located using Ctrl+F in your browser. In this list try and locate mod_rewrite. If it is listed here, you're good to go. If not, you'll need to enable it.

To enable it, you need to locate Apache's configuration file. This file is called httpd.conf.

Note: If you're on a shared host and don't have access to the httpd.conf file for the Apache Server you will need to contact your web host and request they enable the mod_rewrite module.

Once you've located httpd.conf open it and search for the following line. Ensure it is not commented out by removing a # symbol if it is in front of the line:

Enabled: LoadModule rewrite_module modules/mod_rewrite.so

Disabled: #LoadModule rewrite_module modules/mod_rewrite.so

Once you've enabled the line you will need to restart your Apache server in order for it to take effect.

Understanding what Mod Rewrite does

Mod_Rewrite is the process of converting from URLs filled with variables to clean URLs:

URL Before Re-write: http://mydomain.com/index.php?page=search&type=post

URL After Re-write: http://mydomain.com/search/post

Benefits:

Search engine friendly
Easy for users to read
Protects details of how your web application is implemented

The Server (aka Apache) doesn't understand http://mydomain.com/page/about-us/27. To that it will understand it as folders and sub-directories.

Essentially what you are doing is making it so all the links the user sees are the nice, clean ones. The only time the long index.php?p=about...etc. links appear are internally to apache - never seen by the user.

Setting up the Rewrite

Create a file, if there isn't already, in the root of your web directory (/) that is called .htaccess. This is the file that will control the rewrite rules.

For this example, this is how the final .htaccess file will look:

Code:

Options +FollowSymLinks

RewriteEngine On

RewriteBase /



RewriteRule ^news/(.*)$ news.php?article_id=$1 [L]

This will allow us to enter this URL into the address bar: http://mydomain.com/news/357 and have Apache process it like this: http://mydomain.com/news.php?article_id=357.

The First Part : Start the engine

Code:

Options +FollowSymLinks

RewriteEngine On

RewriteBase /

This tells Apache we will be using the Mod Rewrite functionality and enables it at the base of the web root.

You should place this above your rewrite rules every time you use Mod_Rewrite.

The two Options lines at the start are optional, assuming they are already set as such in your httpd.conf file. If you're not sure if your httpd.conf file is set to allow these methods, or you know they aren't included, then include them here in your .htaccess.

The Second Part : Rules to live by

Rewrite Rules are created using Regular Expressions. They tell Apache under what patterns certain actions should be performed.

We will go in depth on them in the next section.

Rewrite Rules: Tell Apache what to do

Rewrite rules take the following format:

Code:

RewriteRule ^{REGEX_PATTERN}$ {PAGE_ADDRESS}{PATTERN_MATCH} [FLAGS]

REGEX_PATTERN

For simplicity sake, this guide assumes you already have a good working knowledge of REGEX. If you don't, I highly recommend you read about Regular Expressions (REGEX) and how to create them. You can also download The Regex Coach for testing your REGEX and seeing if it will match the patterns you'd like it to.

The REGEX Pattern is the Regular Expression string that apache will try to match every time a user types in a URL on your domain. If it matches this expression, then the RewriteRule is followed.

PAGE_ADDRESS

Your page address is exactly that, the actual literal path of the target page on your server.

For example, let's take our earlier instance. I want to be able to type in http://mysite.com/news/NEWS_ID and have my news page process it. Obviously, I don't have all these fancy directories set up to accomodate this. My news page is actually called news.php and is located in the web root (/).

The PAGE_ADDRESS in this example would then be news.php?news_id=, assuming the variable I want to pass into the PHP script from the URL is news_id. It could just as easily be newsID or omgTheNews.

I would then evaluate this in my news.php script as:

PHP Code:


		
			
<?php

echo( "The News ID you've specified is: " . $_REQUEST['news_id'] );
exit();

?>

PATTERN_MATCH

In REGEX, pattern matches are reported as $n, where N is the number of the match.

For example, lets say I have a Regular expression like this:

Code:

^search/(.*)/(.*)/apples/(.*)/oranges/(.*)$

If I then typed in the URL: http://mydomain.com/search/OMG/THIS/apples/IS/oranges/COOL

REGEX would report the following matches:

$1 = "OMG"
$2 = "THIS"
$3 = "IS"
$4 = "COOL"

In summary:

(.*) - This is REGEX essentially meaning that it accepts any character into that spot within the link
$1... $2... $n - This signals the REGEX expression you are relating to. So the first instance of (.*) is $1, the second instance is $2, and so on.

TYING THIS TOGETHER:

Let's say I wanted to use the Regular Expression I just specified (^search/(.*)/(.*)/apples/(.*)/oranges/(.*)$) in my website and I wanted it to redirect to a search.php. In search.php, though, I only want the fourth match set as the search ID.

This would be my RewriteRule:

Code:

RewriteRule ^search/(.*)/(.*)/apples/(.*)/oranges/(.*)$ search.php?search_id=$4 [L]

We will address what the L means in the upcoming section.

If I were to now proceed to the web address http://mydomain.com/search/OMG/THIS/apples/IS/oranges/COOL search.php would be passed the variable search_id with a value of "COOL".

Rewrite Rules: Flag them down

Flags are your way of further customizing what your RewriteRules do. There are many different flags available, see the Mod Rewrite Cheat Sheet for a detailed listing, but we'll only cover the common ones here.

[L] - Last
If this has been applied to a Rule then the Rewrite Engine will stop executing any remaining rules that follow.

[R] - Redirect
This will execute a redirect and send a status code as well as the new location to the user's browser. This will then cause the client browser to update the address bar with the new destination. This flag can, optionally, take in a status code by invoking it as such R=301, where 301 can be any valid Redirection Status Code.

[QSA] - Query String Append
On dynamic pages the query string contains GET data (ie. everything after the ?). If you do not include a query string in the destination then the original query is automatically transferred. If you do specify a query string destination then this overwrites the original. If you wish to add to the query string and keep original data intact, you must use the QSA flag.

[NC] - No Case
Makes the comparison case insensitive

INVOKING FLAGS

Invoking flags is done easily. Simply encase them in square brackets ("[" and "]") and separate them by a comma.

For example, if I wanted to apply a Last and No Case flag to a rule:
[L,NC]

Extra Learning and Reference

For a more detailed tutorial, complete with more examples, see the Easy Mod Rewrite Guide.

Moreover, if you have any questions then you're at the right place! Simply start a topic stating your problem/question and we'll do our best to help. Please try to be as clear as possible, and post all relevant lines of your code as well as your .htaccess file.

Good Luck!