What is mod_rewrite?

It's an Apache httpd (web server) module that takes user's requests for pages and diverts them to a resource of a different name (and perhaps type). Why might we want to do this? See previous article for some reasons and alternatives

Here's a simple example of a rewrite rule:

RewriteRule ^train_running.html$ running.html

And that tells the web server to divert requests to train_running.html to running.html instead. We've used rewrite rules as simple as this one to divert links that people have kindly made to our site - but got wrong - to the correct resource:

RewriteRule ^5704.html$ J704.html

But there's much more to mod_rewrite than that as you'll see if you look at the official manual. Actually, there's so much more that I'll give you some further examples - each taken from our web site.

When reading these examples, please bear in mind that you can place them in your httpd.conf main Apache Configuration file if you wish them to propagate through the whole of your site, or in an individual .htaccess file in the directories to which you wish them to apply. Your server administrator has the ability to enable / disable .htaccess, and what may and may not be placed in it

One final introductory note - the incoming URL is specified in the form or a regular expression (a pattern). At its most basic, most characters match one for one to the URL but there are a number of "specials" such as anchors ^ and $ that mean "starting with" and "ending with", character groups such as . which means "any character" and counts such as * which means "0 or more of the preceding item". Round brackets have multiple meanings within regular expressions; you'll see them in my examples below, used to capture parts of the incoming URL to substitute it into the rewritten one. We offer a day's course on Regular Expressions.

Collapsing a whole directory of web pages to a single script

RewriteRule ^(.*)\.html$ /share/index.php?pagename=$1

All requests that end in .html in the area that the .htaccess or httpd.conf file controls are to be passed on to a single PHP script in the /share/ directory called index.php. The name of the page that was passed in to this PHP script is to be placed in a request parameter called pagename.

This is the mechanism we use in our "wiki" ... where (after validation to avoid injection attacks), the following SQL query is run:

mysql_query("select * from sharedata where pagename = '$_REQUEST[pagename]'");

and the fields from the database are used to populate a single template.

Taking all .htm and .html files and passing them on, including GET data filled in to forms

^(.*)\.htm 8.php?pagename=index&sharename=$1&%{QUERY_STRING}

This is an extended example of passing all .htm (and .html) URLs in a directory on to a single script, with various parameters being passed in too, and any data that was submitted via the GET method appended on to the end. Note that by leaving off the $ on the pattern for the incoming URL, you're able to overcome any ".htm or .html" issues. We do the same thing for .php / .php3 / .php4 / .php5 ...

Diverting the home page of a directory

RewriteRule ^$ 8.php?pagename=index&sharename=index&%{QUERY_STRING}

The Regular expression here is "start with and ends right away", so that's a request for a directory rather than anything in a directory.

Referring image requests on to a database via a program

RewriteRule ^(.*)\.jpg /pix/feeder.php?image=$1&%{QUERY_STRING}

All .jpg requests are passed on to a PHP script, with the image name passed in as a parameter. Why do we do this?

• it saves a directory with a large number of pictures getting cluttered
• it allows us to monitor where images are loaded from (the referer) so highlighting any images hotlinked from other web sites
• it allows us to generate dynamic images (for example, this diagram of current train cancellations on First Great Western ;-) )
• it allows us to feed out low res or high res alternatives
• it allows us t maintain image data with the image
• and it allows us to use selected URLs to generate a random image.


Handling a special case - something NOT to rewrite

RewriteRule ^rooms.html rooms.html?%{QUERY_STRING} [L]

Where you have a whole directory / pattern being rewritten and you want to make exceptions, you can do so. In this example, there really is a file called rooms.html that you want to serve! The [L] modifier means "Last" and instructs the httpd web server that it should skip the following rules if this rule has been applied - very useful indeed in preventing some utterly confusing situations!

Rewriting that calls up a page from another server

RewriteRule ^info.php http://www.wellho.info/ [L,P]

This example - with a complete URL in the target position and a [P] modifier, proxies (see mod_proxy) the request on to a different URL on a different computer. Your web server actually becomes a client as it retrieves the page from the other system, and in turn it passes it back to your client. So the following two links will return the same .html source:

http://www.wellho.net/demo/info.php
http://www.wellho.info/

Indeed they do return the same source, but you'll need to be very careful indeed of any site-relative links, references to style sheets and images, etc - but mod_proxy is a story for another day!

Other directives in mod_rewrite

As well as RewriteRule directives, you'll also need to make use of a RewriteEngine directive to turn the facility on. The RewriteCond directive allows you to apply a condition to the following RewriteRule, and the RewriteLog allows you to produce a log file of rewrite requests. You can use a RewriteMap directive to call in a separate file of mappings, and that can even include random proxy forwards; what sounds (at first) like a crazy idea actually provides a neat way of spreading your processor load on heavy web based applications around a number of servers - there's a complete example here of forwarding Java requests from Apache httpd to multiple instances of Tomcat.

We cover the configuration of Apache httpd on our Linux Web Server course ... and there's a lot more that you can do other than just mod_rewrite!
(written 2008-12-20, updated 2013-01-02)

 G996 - Well House Consultants - Newsletter Scripts
  [1001] .pdf files - upload via PHP, store in MySQL, retrieve - (2006-12-19)
  [1066] Final, Finally and Finalize - three special words in Java - (2007-02-05)
  [1123] mysqldump and mysqlrestore - (2007-03-30)
  [1217] What are factory and singleton classes? - (2007-06-04)
  [1321] Resetting session based tests in PHP - (2007-08-26)
  [1387] Error logging to file not browser in PHP - (2007-10-11)
  [1487] Efficient PHP applications - framework and example - (2007-12-28)
  [1505] Script to present commonly used images - PHP - (2008-01-13)
  [1601] Replacing the last comma with an and - (2008-04-04)
  [1665] Factory method example - Perl - (2008-06-04)
  [1743] First class functions in Lua lead to powerful OO facilities - (2008-08-07)
  [1813] Ajax - going Asyncronous and what it means - (2008-09-28)
  [2046] Finding variations on a surname - (2009-02-17)
  [2145] Using the internet to remotely check for power failure at home (PHP) - (2009-04-29)
  [2259] Grouping rows for a summary report - MySQL and PHP - (2009-06-27)
  [2360] Error Handling in Lua with assert and pcall - (2009-08-13)
  [2433] Controlling, supressing, enabling PHP error messages - (2009-10-02)
  [2539] Changing Images - (2009-12-17)
  [3179] Oops - I typed ci not vi, and have lost my file ... - (2011-02-21)

A607 - Web Application Deployment - Apache httpd mod_rewrite
  [631] Apache httpd to Tomcat - jk v proxy - (2006-03-03)
  [755] Using different URLs to navigate around a single script - (2006-06-11)
  [934] Clustering, load balancing, mod_rewrite and mod_proxy - (2006-11-21)
  [1006] Apache httpd and Apache Tomcat together tips - (2006-12-24)
  [1009] Passing GET parameters through Apache mod_rewrite - (2006-12-27)
  [1207] Simple but effective use of mod_rewrite (Apache httpd) - (2007-05-27)
  [1376] Choosing between mod_proxy and mod_rewrite - (2007-10-02)
  [1381] Using a MySQL database to control mod_rewrite via PHP - (2007-10-06)
  [1636] What to do if the Home Page is missing - (2008-05-08)
  [1731] Apache httpd, MySQL, PHP - installation procedure - (2008-08-01)
  [1771] More HowTo diagrams - MySQL, Tomcat and Java - (2008-08-24)
  [1778] Pointing all the web pages in a directory at a database - (2008-08-30)
  [2094] If you have a spelling mistake in your URL / page name - (2009-03-21)
  [2555] Bookkeeping - (2009-12-29)
  [2728] Redirecting a home page using mod_rewrite - (2010-04-17)
  [2768] Carrying a long URL around - looking for memorable shorts - (2010-05-17)
  [2773] Dynamically watching your web site via a PHP wrapper - (2010-05-21)
  [2900] Redirecting a page - silent, temporary or permanent? - (2010-08-03)
  [2981] How to set up short and meaningfull alternative URLs - (2010-10-02)
  [3197] Finding and diverting image requests from rogue domains - (2011-03-08)
  [3339] Simplest ever proxy configuration? - (2011-06-28)
  [3568] Telling which ServerAlias your visitor used - useful during merging domains - (2012-01-04)
  [3753] Adding a passcode to a directory - (2012-06-05)
  [3862] Forwarding a whole domain, except for a few directories - Apache http server - (2012-09-17)

A603 - Web Application Deployment - Further httpd Configuration
  [345] Spotting a denial of service attack - (2005-06-12)
  [466] Separating 'per instance' data from binaries and web sites - (2005-10-16)
  [526] Apache httpd - serving web documents from different directories - (2005-12-12)
  [550] 2006 - Making business a pleasure - (2006-01-01)
  [649] Denial of Service ''attack'' - (2006-03-17)
  [662] An unhelpful error message from Apache httpd - (2006-03-30)
  [853] To list a directory under httpd on a web server, or not? - (2006-09-02)
  [1080] httpd.conf or .htaccess? - (2007-02-14)
  [1121] Sharing the load with Apache httpd and perhaps Tomcat - (2007-03-29)
  [1351] Compressing web pages sent out from server. Is it worth it? - (2007-09-14)
  [1355] .php or .html extension? Morally Static Pages - (2007-09-17)
  [1377] Load Balancing with Apache mod_jk (httpd/Tomcat) - (2007-10-02)
  [1551] Which modules are loaded in my Apache httpd - (2008-02-23)
  [1554] Online hotel reservations - Melksham, Wiltshire (near Bath) - (2008-02-24)
  [1564] Default file (MiMe types) for Apache httpd and Apache Tomcat - (2008-03-04)
  [1566] Strange behaviour of web directory requests without a trailing slash - (2008-03-06)
  [1619] User and Group settings for Apache httpd web server - (2008-04-22)
  [1707] Configuring Apache httpd - (2008-07-12)
  [1762] WEB-INF (Tomcat) and .htaccess (httpd) - (2008-08-20)
  [1767] mod_proxy and mod_proxy_ajp - httpd - (2008-08-22)
  [1939] mod_proxy_ajp and mod_proxy_balancer examples - (2008-12-13)
  [1955] How to avoid duplicating web page maintainance - (2008-12-20)
  [1974] Moving a directory on your web site - (2009-01-03)
  [2060] Database connection Pooling, SSL, and command line deployment - httpd and Tomcat - (2009-03-01)
  [2272] Monitoring and loading tools for testing Apache Tomcat - (2009-07-07)
  [2478] How did I do THAT? - (2009-10-26)
  [3133] An image from a website that occasionally comes out as hyroglyphics - (2011-01-14)
  [3449] Apache Internal Dummy Connection - what is it and what should I do with it? - (2011-09-19)
  [3635] Parse error: parse error, unexpected T_STRING on brand new web site - why? - (2012-03-03)
  [3955] Building up from a small PHP setup to an enterprise one - (2012-12-16)
  [4001] Helping search engines with appropriate 400 error codes - (2013-02-11)
  [4307] Identifying and clearing denial of service attacks on your Apache server - (2014-09-27)

Back to End of Training, 2008

Previous and next or Horse's mouth home

Forward to How to avoid duplicating web page maintainance

PHP - Parse error: syntax error, unexpected $end ...
Why are cooks bad tempered?
Images for Christmas
mod_rewrite for newcomers
End of Training, 2008
Small Print
Whisky - Setting and reading cookies from Perl
Copyright of Training Notes and Web Site
Nuclear Physics comes to our web site