more .htaccess tips and tricks..

<ifModule>
more clever stuff here
</ifModule>
 

redirecting and rewriting

"The great thing about mod_rewrite is it gives you all the configurability and flexibility of Sendmail. The downside to mod_rewrite is that it gives you all the configurability and flexibility of Sendmail."

- Brian Behlendorf, Apache Group
 

One of the more powerful tricks of the .htaccess hacker is the ability to rewrite URLs. This enables us to do some mighty manipulations on our links; useful stuff like transforming very long URL's into short, cute URLs, transforming dynamic ?generated=page&URL's into /friendly/flat/links, redirect missing pages, preventing hot-linking, performing automatic language translation, and much, much more.

Make no mistake, mod_rewrite is complex. This isn't the subject for a quick bite-size tech-snack, probably not even a week-end crash-course, I've seen guys pull off some real cute stuff with mod_rewrite, but with kudos-hat tipped firmly towards that bastard operator from hell, Ralf S. Engelschall, author of the magic module itself, I have to admit that a great deal of it still seems so much voodoo to me.

The way that rules can work one minute and then seem not to the next, how browser and other in-between network caches interact with rules and testing rules is often baffling, maddening. When I feel the need to bend my mind completely out of shape, I mess around with mod_rewrite!

After all this, it does work, and while I'm not planning on taking that week-end crash-course any time soon, I have picked up a few wee tricks myself, messing around with webservers and web sites, this place..

The plan here is to just drop some neat stuff, examples, things that have proven useful, and work on a variety of server setups; there are apache's all over my LAN, I keep coming across old .htaccess files stuffed with past rewriting experiments that either worked; and I add them to my list, or failed dismally; and I'm surprised that more often these days, I can see exactly why!

Very little here is my own invention. Even the bits I figured out myself were already well documented, I just hadn't understood the documents, or couldn't find them. Sometimes, just looking at the same thing from a different angle can make all the difference, so perhaps this humble stab at URL Rewriting might be of some use. I'm writing it for me, of course. but I do get some credit for this..

# time to get dynamic, see..
RewriteRule ^(.*)\.htm $1.php
 

beginning rewriting..

Whenever you use mod_rewrite (the part of apache that does all this magic), you need to do..


..before any ReWrite rules. note: +FollowSymLinks must be enabled for any rules to work, this is a security requirement of the rewrite engine. Normally it's enabled in the root and you shouldn't have to add it, but it doesn't hurt to do so, and I'll insert it into all the examples on this page, just in case*.

The next line simply switches on the rewrite engine for that folder. if this directive is in you main .htaccess file, then the ReWrite engine is theoretically enabled for your entire site, but it's wise to always add that line before you write any redirections, anywhere.

* Although highly unlikely, your host may have +FollowSymLinks enabled at the root level, yet disallow its addition in .htaccess; in which case, adding +FollowSymLinks will break your setup (probably a 500 error), so just remove it, and your rules should work fine.

Important: While some of the directives on this page may appear split onto two lines, in your .htaccess file, they must exist completely on one line. If you drag-select and copy the directives on this page, they should paste just fine into any text editor.
 

simple rewriting

Simply put, Apache scans all incoming URL requests, checks for matches in our .htaccess file and rewrites those matching URLs to whatever we specify. something like this..

all requests to whatever.htm will be sent to whatever.php:
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^(.*)\.htm$ $1.php [NC]

Handy for anyone updating a site from static htm (you could use .html, or .htm(.*), .htm?, etc) to dynamic php pages; requests to the old pages are automatically rewritten to our new urls. no one notices a thing, visitors and search engines can access your content either way. leave the rule in; as an added bonus, this enables us to easily split php code and its included html structures into two separate files, a nice idea; makes editing and updating a breeze. The [NC] part at the end means "No Case", or "case-insensitive"; more on the switches, later.

Folks can link to whatever.htm or whatever.php, but they always get whatever.php in their browser, and this works even if whatever.htm doesn't exist! But I'm straying..

As it stands, it's a bit tricky; folks will still have whatever.htm in their browser address bar, and will still keep bookmarking your old .htm URL's. Search engines, too, will keep on indexing your links as .htm, some have even argued that serving up the same content from two different places could have you penalized by the search engines. This may or not bother you, but if it does, mod_rewrite can do some more magic..

this will do a "real" external redirection:
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^(.+)\.htm$ http://corz.org/$1.php [R,NC]

This time we instruct mod_rewrite to do a proper external rewrite, aka, "redirection". Now, instead of just background rewriting on-the-fly, the user's browser is physically redirected to a new URI, and whatever.php appears in their browser's address bar - search engines and other spidering entities will automatically update their links to the .php versions; everyone wins. You can take your time with the updating, too.

Note: if you use [R] alone, it defaults to sending an HTTP "MOVED TEMPORARILY" redirection, aka, "302". But you can send other codes, like so..

this performs the exact same as the previous example RewriteRule.
RewriteRule ^(.+)\.htm$ http://corz.org/$1.php [R=302,NC]

Okay, I sent the exact same code, but I didn't have to. For details of the many 30* response codes you can send, see here. Most people seem to want to send 301, aka, "MOVED PERMENENTLY".

Note: if you add an "L" flag to the mix; meaning "Last Rule", e.g. [R=302,NC,L]; Apache will stop processing rules for this request at that point, which may or may not be what you want. Either way, it's useful to know.
 

not-so-simple rewriting ... flat links and more

You may have noticed, the above examples use regular expression to match variables. What that simply means is.. match the part inside (.+) and use it to construct "$1" in the new URL. In other words, (.+) = $1 you could have multiple (.+) parts and for each, mod_rewrite automatically creates a matching $1, $2, $3, etc, in your target (aka. 'substitution') URL. This facility enables us to do all sorts of tricks, and the most common of those, is the creation of "flat links"..

Even a cute short link like http://mysite/grab?file=my.zip is too ugly for some people, and nothing less than a true old-school solid domain/path/flat/link will do. Fortunately, mod_rewrite makes it easy to convert URLs with query strings and multiple variables into exactly this, something like..

a more complex rewrite rule:
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^files/([^/]+)/([^/]+).zip /download.php?section=$1&file=$2 [NC]

would allow you to present this link as..

  http://mysite/files/games/hoopy.zip

and in the background have that transparently translated, server-side, to..

  http://mysite/download.php?section=games&file=hoopy

which some script could process. You see, many search engines simply don't follow our ?generated=links, so if you create generating pages, this is useful. However, it's only the dumb search engines that can't handle these kinds of links; we have to ask ourselves.. do we really want to be listed by the dumb search engines? Google will handle a good few parameters in your URL without any problems, and the (hungry hungry) msn-bot stops at nothing to get that page, sometimes again and again and again…

I personally feel it's the search engines that should strive to keep up with modern web technologies, in other words; we shouldn't have to dumb-down for them. But that's just my opinion. Many users will prefer /files/games/hoopy.zip to /download.php?section=games&file=hoopy but I don't mind either way. As someone pointed out to me recently, presenting links as standard/flat/paths means you're less likely to get folks doing typos in typed URL's, so something like..

an even more complex rewrite rule:
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^blog/([0-9]+)-([a-z]+) http://corz.org/blog/index.php?archive=$1-$2 [NC]

would be a neat trick, enabling anyone to access my blog archives by doing..

 http://corz.org/blog/2003-nov

in their browser, and have it automagically transformed server-side into..

 http://corz.org/blog/index.php?archive=2003-nov

which corzblog would understand. It's easy to see that with a little imagination, and a basic understanding of posix regular expression, you can perform some highly cool URL manipulations.

Here's the very basics of regexp (expanded from the apache mod_rewrite documentation)..
 

Escaping:

\char escape that particular char

    For instance to specify special characters.. [].()\ etc.

Text:

.             Any single character  (on its own = the entire URI)
[chars]       Character class: One of following chars
[^chars]      Character class: None of following chars
text1|text2   Alternative: text1 or text2 (i.e. "or")

    e.g. [^/] matches any character except /
         (foo|bar)\.html matches foo.html and bar.html

Quantifiers:

? 0 or 1 of the preceding text
* 0 or N of the preceding text  (hungry)
+ 1 or N of the preceding text

    e.g. (.+)\.html? matches foo.htm and foo.html
         (foo)?bar\.html matches bar.html and foobar.html

Grouping:

(text)  Grouping of text

    Either to set the borders of an alternative or
    for making backreferences where the nth group can 
    be used on the target of a RewriteRule with $n

	e.g.  ^(.*)\.html foo.php?bar=$1

Anchors:

^    Start of line anchor
$    End   of line anchor

    An anchor explicitly states that the character right next to it MUST 
    be either the very first character ("^"), or the very last character ("$")
    of the URI string to match against the pattern, e.g.. 
	
	^foo(.*) matches foo and foobar but not eggfoo
	(.*)l$ matches fool and cool, but not foo
 

shortening URLs

One common use of mod_rewrite is to shorten URL's. Shorter URL's are easier to remember and, of course, easier to type. An example..

beware the regular expression:
Options +FollowSymlinks
RewriteEngine On
RewriteRule ^grab(.*) /public/files/download/download.php$1

this rule would transform this user's URL..

  http://mysite/grab?file=my.zip

server-side, into..

  http://mysite/public/files/download/download.php?file=my.zip

which is a wee trick I use for my distro machine, among other things. everyone likes short URL's, and so will you; using this technique, you can move /public/files/download/ to anywhere else in your site, and all the old links still work fine; simply alter your .htaccess file to reflect the new location. edit one line, done - nice - means even when stuff is way deep in your site you can have cool links like this.. and this; links which are not only short, but flat..
 

capturing variables

Slapping (.*) onto the end of the request part of a ReWriteRule is just fine when using a simple $_GET variable, but sometimes you want to do trickier things, like capturing particular variables and converting them into other variables in the target URL. Or something else..

When capturing variables, the first thing you need to know about, is the [QSA] flag, which simply tags all the original variables back onto the end of the target url. This may be all you need. The second thing, is %{QUERY_STRING}, an Apache server string we can capture variables from, using simple RewriteCond (aka. conditional ) statements.

RewriteCond is very like doing if...then...do in many programming languages. If a certain condition is true, then do the rewrite that follows..

In the following example, the RewriteCond statement checks that the query string has the foo variable set, and captures its value while it's there. In other words, only requests for /grab that have the variable foo set, will be rewritten, and while we're at it, we'll also switch foo, for bar, just because we can..

capturing a $_GET variable:
Options +FollowSymlinks
RewriteEngine On
RewriteCond %{QUERY_STRING} foo=(.*)
RewriteRule ^grab(.*) /page.php?bar=%1

would translate a link/user's request for..

http://domain.com/grab?foo=bar

server-side, into..

http://domain.com/page.php?bar=bar

Which is to say, the user's browser would be fed page.php (without an [R] flag in the RewriteRule, their address bar would still read /grab?foo=bar). The variable bar would be available to your script, with its value set to bar. This variable has been magically created, by simply using a regular ? in the target of the RewriteRule, and tagging on the first captured backreference, %1.. ?bar=%1

Note how we use the % character, to specify variables captured in RewriteCond statements, aka "Backreferences". This is exactly like using $1 to specify numbered backreferences captured in RewriteRule patterns, except for strings captured inside a RewriteCond statement, we use % instead of $. Simple.

You can use the [QSA] flag in addition to these query string manipulations, merge them. In the next example, the value of foo becomes the directory in the target URL, and the variable file is magically created. The original query string is then tagged back onto the end of the whole thing..
QSA Overkill!
Options +FollowSymlinks
RewriteEngine On
RewriteCond %{QUERY_STRING} foo=(.+)
RewriteRule ^grab/(.*) /%1/index.php?file=$1 [QSA]

So a request for..

http://domain.com/grab/foobar.zip?level=5&foo=bar

is translated, server-side, into..

http://domain.com/bar/index.php?file=foobar.zip&level=5&foo=bar

Depending on your needs, you could even use flat links and dynamic variables together, something like this could be useful..


By the way, you can easily do the opposite, strip a query string from a URL, by simply putting a ? right at the end of the taget part. This example does exactly that, whilst leaving the actual URI intact..

just a demo!
Options +FollowSymlinks
RewriteEngine On
RewriteCond %{QUERY_STRING} .
RewriteRule foo.php(.*) /foo.php? [L]
The RewriteCond statement only allows requests that have something in their query string, to be processed by the RewriteRule, or else we'd end up in that hellish place, dread to all mod_rewriters.. the endless loop. RewriteCond is often used like this; as a safety-net.
 

cooler access denied

In part one I demonstrated a drop-dead simple mechanism for denying access to particular files and folders. The trouble with this is the way our user gets a 403 "Access Denied" error, which is a bit like having a door slammed in your face. Fortunately, mod_rewrite comes to the rescue again and enables us to do less painful things. One method I often employ is to redirect the user to the parent folder..

they go "huh?.. ahhh!"
# send them up!
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^(.*)$ ../ [NC]

It works great, though it can be a wee bit tricky with the URLs, and you may prefer to use a harder location, which avoids potential issues in indexed directories, where folks can get in a loop..

they go damn! Oh!
# send them exactly there!
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^(.*)$ /comms/hardware/router/ [NC]

Sometimes you'll only want to deny access to most of the files in the directory, but allow access to maybe one or two files, or file types, easy..
deny with style!
# users can load only "special.zip", and the css and js files.
Options +FollowSymlinks
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !^(.+)\.css$
RewriteCond %{REQUEST_FILENAME} !^(.+)\.js$
RewriteCond %{REQUEST_FILENAME} !special.zip$
RewriteRule ^(.+)$ /chat/ [NC]

Here we take the whole thing a stage further. Users can access .css (stylesheet) and javascript files without problem, and also the file called "special.zip", but requests for any other filetypes are immediately redirected back up to the main "/chat/" directory. You can add as many types as you need. You could also bundle the filetypes into one line using | (or) syntax, though individual lines are perhaps clearer.

Here's what's currently cooking inside my /inc/ directory..

all-in-one control..
RewriteEngine on
Options +FollowSymlinks
# allow access with no restrictions to local machine at 192.168.1.3
RewriteCond %{REMOTE_ADDR} !192.168.1.3
# allow access to all .css and .js in sub-directories..
RewriteCond %{REQUEST_URI} !\.css$
RewriteCond %{REQUEST_URI} !\.js$
# allow access to the files inside img/, but not a directory listing..
RewriteCond %{REQUEST_URI} !img/(.*)\.
# allow access to these particular files...
RewriteCond %{REQUEST_URI} !comments.php$
RewriteCond %{REQUEST_URI} !corzmail.php$
RewriteCond %{REQUEST_URI} !digitrack.php$
RewriteCond %{REQUEST_URI} !gd-verify.php$
RewriteCond %{REQUEST_URI} !post-dumper.php$
RewriteCond %{REQUEST_URI} !print.php$
RewriteCond %{REQUEST_URI} !source-dump.php$
RewriteCond %{REQUEST_URI} !textview.php$
RewriteRule ^(.*)$ / [R,NC,L]
 

prevent hot-linking

Believe it or not, there are some webmasters who, rather than coming up with their own content will steal yours. Really! Even worse, they won't even bother to copy to their own server to serve it up, they'll just link to your content!  no, it's true, in fact, it used to be incredibly common. These days most people like to prevent this sort of thing, and .htaccess is one of the best ways to do it.

This is one of those directives where the mileage variables are at their limits, but something like this works fine for me..

how DARE they!
Options +FollowSymlinks
# no hot-linking
RewriteEngine On
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://(www\.)?corz\.org/ [NC]
RewriteRule .*\.(gif|jpg|png)$

You may see the last line broken into two, but it's all one line (all the directives on this page are). Let's have a wee look at what it does..

We begin by enabling the rewrite engine, as always.

The first RewriteCond line allows direct requests (not from other pages - an "empty referrer") to pass unmolested. The next line means; if the browser did send a referrer header, and the word "corz.org" is not in the domain part of it, then DO rewrite this request.

The all-important final RewriteRule line instructs mod_rewrite to rewrite all matched requests (anything without "corz.org" in its referrer) asking for gifs, jpegs, or pngs, to an alternative image. Mine says "no hotlinking!" You can see it in action here. There are loads of ways you can write this rule. google for "hot-link protection" and get a whole heap. Simple is best. You could send a wee message instead, or direct them to some evil script, or something. These days, mine is a simple corz.org logo, which I  think is rather clever.
 

lose the "www"

I'm often asked how I prevent the "www" part showing up at my site, so I guess I should add something about that. Briefly, if someone types http://www.corz.org/ into their browser (or uses the www part for any link at corz.org) it is redirected to the plain, rather neat, http://corz.org/ version. This is very  simple to achieve, like this..

beware the regular expression:
Options +FollowSymlinks
RewriteEngine on
RewriteCond %{http_host} ^www\.corz\.org [NC]
RewriteRule ^(.*)$ http://corz.org/$1 [R=301,NC]

You don't need to be a genius to see what's going on here. There are other ways you could write this rule, but again, simple is best. Like most of the examples here, the above is pasted directly from my own main .htaccess file, so you can be sure it works perfectly. In fact, I recently updated it so that I could share rules between my dev mirror and live site without any .htaccess editing..

here's what I'm currently using:
Options +FollowSymlinks
RewriteEngine on
RewriteCond %{HTTP_HOST} ^www\.(.*) [NC]
RewriteRule ^(.*)$ http://%1/$1 [R=301,NC,L]
 

multiple domains in one root

If you are in the unfortunate position of having your sites living on a host that doesn't support multiple domains, you may be forced to roll your own with .htaccess and mod_rewrite. So long as your physical directory structure is well thought-out, this is fairly simple to achieve.

For example, let's say we have two domains, pointing at a single hosted root; domain-one.com and domain-two.com. In our web server root, we simply create a folder for each domain, perhaps one/, and two/ then in our main (root) .htaccess, rewrite all incoming requests, like this..

All requests NOT already rewritten into these folders, transparently rewrite..
#two domains served from one root..
RewriteCond %{HTTP_HOST} domain-one.com
RewriteCond %{REQUEST_URI} !^/one
RewriteRule ^(.*)$ one/$1 [L]

RewriteCond %{HTTP_HOST} domain-two.com
RewriteCond %{REQUEST_URI} !^two
RewriteRule ^(.*)$ two/$1 [L]

All requests for the host domain-one.com are rewritten (not R=redirected) to the one/ directory, so long as they haven't already been rewritten there (the second RewriteCond). Same story for domain-two.com. Note the inconsistency in the RewriteCond statement; !^/dir-name and !^dir-name should both work fine.

Also note, with such a simple domain & folder naming scheme, you could easily merge these two rule sets together. This would be unlikely in the real world though, which is why I left them separate; but still, worth noting.

Other general settings and php directives can also go in this root .htaccess file, though if you have any further rewrite you'd like to perform; short URL's, htm to php conversion and what-not; it's probably easier and clearer to do those inside the sub-directory's .htaccess files.
 

automatic translation

If you don't read English, or some of your guests don't, here's a neat way to have the wonderful Google translator provide automatic on-the-fly translation for your site's pages. Something like this..

they simply add their country code to the end of the link, or you  do..
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^(.*)-fr$ http://www.google.com/translate_c?hl=fr&sl=en&u=http://corz.org/$1 [R,NC]
RewriteRule ^(.*)-de$ http://www.google.com/translate_c?hl=de&sl=en&u=http://corz.org/$1 [R,NC]
RewriteRule ^(.*)-es$ http://www.google.com/translate_c?hl=es&sl=en&u=http://corz.org/$1 [R,NC]
RewriteRule ^(.*)-it$ http://www.google.com/translate_c?hl=it&sl=en&u=http://corz.org/$1 [R,NC]
RewriteRule ^(.*)-pt$ http://www.google.com/translate_c?hl=pt&sl=en&u=http://corz.org/$1 [R,NC]

You can create your menu with its flags or whatever you like, and add the country code to end of the links.. <a href="page.html-fr" id="... Want to see this page in French?

Although it is very handy, and I've been using it here for a couple of years here at the org, for my international blog readers, all two of them, heh. Almost no one knows about it, mainly because I don't have any links . One day I'll probably do a wee toolbar with flags and what-not. Perhaps not. Trouble is, the Google translator stops translating after a certain amount of characters (which seems to be increasing, good), though these same rules could easily be applied to other translators, and if you find a good one, one that will translate a really huge  document on-the-fly, do let me know!

If you wanted to be really clever, you could even perform some some kind of IP block check and present the correct version automatically, but that is outside the scope of this document. note: this may be undesirable for pages where technical commands are given (like this page) because the commands will also be translated. "RewriteEngine dessus" will almost certainly get you a 500 error page!

Another thing you might like to try; rather than individual country flags; fr, de, etc., use the "u" flag, for "Universal". In theory, Google will check the client's location, and automatically translate to that language. One line in your .htaccess would cover all languages, and automatically cover new ones as Google adds them.

While I'm here, slightly related; if you are non-english speaking, note, you can do a similar thing browser-side, create a "bookmarklet" (a regular bookmark, except that it "does something"), using this code for the location..
the same sort of thing, except browser-side..
javascript:void(location.href='http://translate.google.com/translate?u='+location.href)

 

httpd.conf

Remember, if you put these rules in the main server conf file (usually httpd.conf) rather than an .htaccess file, you'll need to use ^/... ... instead of ^... ... at the beginning of the RewriteRule line, in other words, add a slash.
 

inheritance..

If you are creating rules in sub-folders of your site, you need to read this.

You'll remember how rules in top folders apply to all the folders inside those folders too. we call this "inheritance". normally this just works. but if you start creating other rules inside subfolders you will, in effect, obliterate the rules already applying to that folder due to inheritance, or "decendancy", if you prefer. not all the rules, just the ones applying to that subfolder. a wee demonstration..

Let's say I have a rule in my main /.htaccess which redirected requests for files ending .htm to their .php equivalent, just like the example at the top of this very page. now, if for any reason I need to add some rewrite rules to my /osx/.htaccess file, the .htm >> .php redirection will no longer work for the /osx/ subfolder, I'll need to reinsert it, but with a crucial difference..

this works fine, site-wide, in my main .htaccess file
# main (top-level) .htaccess file..
# requests to file.htm goto file.php
Options +FollowSymlinks
RewriteEngine on
RewriteRule ^(.*)\.htm$ http://corz.org/$1.php [R=301,NC]

Here's my updated /osx/.htaccess file, with the .htm >> .php redirection rule reinserted..

but I'll need to reinsert the rules for it to work in this sub-folder
# /osx/.htaccess file..
Options +FollowSymlinks
RewriteEngine on
RewriteRule some rule that I need here
RewriteRule some other rule I need here
RewriteRule ^(.*)\.htm$ http://corz.org/osx/$1.php [R=301,NC]

Spot the difference in the subfolder rule, highlighted in red. you must add the current path to the new rule. now it works again, and all the osx/ subfolders will be covered by the new rule. if you remember this, you can go replicating rewrite rules all over the place.

If it's possible to put your entire site's rewrite rules into the main .htaccess file, and it probably is; do that, instead, like this..

it's a good idea to put all your rules in your main .htaccess file..
# root /.htaccess file..
Options +FollowSymlinks
RewriteEngine on
# .htm >> .php is now be covered by our main rule, there's no need to repeat it.
# But if we do need some /osx/-specific rule, we can do something like this..
RewriteRule ^osx/(.*)\.foo$ /osx/$1.bar [R=301,NC]

Note, no full URL (with domain) in the second example. Don't let this throw you; with or without is functionally identical, on most servers. Essentially, try it without the full URL first, and if that doesn't work, sigh, and add it - maybe on your next host!

The latter, simpler form is preferable, if only for its tremendous portability it offers - my live site, and my development mirror share the exact same .htaccess files - a highly desirable thing.

By the way, it perhaps doesn't go without saying that if you want to disable rewriting inside a particular subfolder, where it is enabled further up the tree, simply do:

handy for avatar folders, to allow hot-linking, etc..
RewriteEngine off
 

conclusion

In short, mod_rewrite allows you to send browsers from anywhere to anywhere. You can create rules based not simply on the requested URL, but also on such things as IP address, browser agent (send old browsers to different pages, for instance), and even the time of day; the possibilities are practically limitless.

The ins-and outs of mod_rewrite syntax are topic for a much longer document than this, and if you fancy experimenting with more advanced rewriting rules, I urge you to check out the apache documentation.

If you have apache installed on your system, there will likely be a copy of the apache manual, right here, and the excellent mod_rewriting guide, lives right here. do check out the URL Rewriting Engine notes for the juicy syntax bits. That's where I got the cute quote for the top of the page, too.
 
;o)
(or
 
 

troubleshooting tips..

rewrite logging..

When things aren't working, you may want to enable rewrite logging. I'll assume you are testing these mod_rewrite directives on your development mirror, or similar setup, and can access the main httpd.conf file. If not, why not?  Testing mod_rewrite rules on your live domain isn't exactly ideal, is it? Anyway, put this somewhere at the foot of your http.conf..

Expect large log files..
#
# ONLY FOR TESTING REWRITE RULES!!!!!
#
RewriteLog "/tmp/rewrite.log"
#RewriteLogLevel 9
RewriteLogLevel 5

Set the file location and logging level to suit your own requirements. If your rule is causing your Apache to loop, load the page, immediately hit your browser's "STOP" button, and then restart Apache. All within a couple of seconds. Your rewrite log will be full of all your diagnostic information, and your server will carry on as before.

Setting a value of 1 gets you almost no information, setting the log level to 9 gets you GIGABYTES! So you must remember to comment out these rules and restart Apache when you are finished because, not only will rewrite logging create space-eating files, it will seriously impact your web server's performance.

RewriteLogLevel 5  is very useful, I find.

Fatal Redirection

If you start messing around with 301 redirects [R=301], aka. "Permanently Redirected", and your rule isn't working, you could give yourself some serious headaches..

Once the browser has been redirected permanently  to the wrong address, if you then go on to alter the wonky rule, your browser will still  be redirected to the old address (because it's a browser thing), and you may even go on to fix, and then break  the rule all over again without ever knowing it. Changes to 301 redirects can take a long time to show up in your browser.

Solution: restart your browser, or use a different one.

Better Solution: Use [R] instead of [R=301] while you are testing . When you are 100% certain the rule does exactly as it's expected to, then  switch it to [R=301] for your live site.
 

debug-report.php
A php script to make your mod_rewrite life easier!

When things aren't working as you would expect, you probably won't have to enable rewrite logging to get the information you need. What's usually required is no more than a quick readout of all the current variables, $_GET array, and so on; so you can see exactly what happened to the request.

For another purpose, I long ago created debug.php, and later, finding all this information useful in chasing down wonky rewrites, created a "report" version, which rather than output to a file, spits the information straight back into your browser, as well as $_POST, $_SESSION, and $_SERVER arrays, special variables, like __FILE__, and much more.

Usage is simple; you make it your target page, so in a rule like this..

RewriteRule ^(.*)\.html$ /catch-all.php?var=$1

You would have a copy of debug-report.php temporarily renamed to catch-all.php in the root of your server, and type http://testdomain.org/foobar.html into your address bar and, with yer mojo working, debug-report.php leaps into your browser with a shit-load of exactly the sort of information you need to figure out all this stuff. When I'm messing with mod_rewrite, debug-report.php saves me time, a lot. Also, it's free..

 
 
 

Before you ask a question..

Firstly, read this at least once in your life. I insist!

NOTE: THIS IS NOT A COMMUNITY. And I am not your free tech dude. Sure, folk sometimes drop back in, but realistically, the chances of someone else coming along and answering your tech question are about as close to zero as it gets; almost no one sticks around but me, the guy who wrote all that text (above).

If you can't be bothered to read the article, I can't be bothered responding. Capiche? I do read all comments, though, and answer questions about the article. I'm also keen to discuss anything you think I've missed, or interesting related concepts in general.

If you are still sure that you want to post your own, personal, tech question, then please ensure that you first, either..

a) Have read the article (above) and have tried "everything" yourself; in which case; post the exact code that isn't working (preferably inside [pre][/pre] tags), or else..

b) Pay me. The PayPal button is at the top right of the page.

Other posts will be ignored and/or deleted.

cbparser powered comments..

previous comments (thirty three pages)   show all comments

Torbjørn Torsvik - 20.10.08 2:26 pm

Hi. Is it possible to make a htaccessfile check for certain SESSIONS?

HTTP is a "stateless" protocol, a.k.a. "sessionless"; there is no such thing as an http session. If you are referring to sessions created by some server-side language (e.g. php), then you need to use that language to check for them.

Note: You can check for cookies with .htaccess. If you want to know more about that; drop a comment on the other page - this article is about mod_rewrite. ;o)



D. Rich - 22.10.08 3:56 am

I used the information you provided to solve my Joomla subdirectory problem.

I added a link back to this page. Great work & Thanks!


Jesse - 23.10.08 10:49 pm

Hi I'm trying to do a 'controlled' redirect..I've been searching everywhere for some answers I'm wondering if you might have an opinion.

I have (many) old links that are being displayed like they were before I implemented mod_rewrite.
I'd like for the user to be able to still click those links, and end up at the exact same place but see the rewritten url in the address bar...

I have:
RewriteRule songs/(.*)-(.*)\.html songs.php?page=$2&song=$1


ok, so:
http://localhost/songs/abc-22.html ends up at http://localhost/songs.php?page=22&song=abc

however I have thousands of links still showing songs.php?page=22&song=abc ...

I've tried many things, the best I can describe my guess for the solution is:
RewriteCond %{QUERY_STRING} . 
RewriteRule ^songs.php?song=(.*)-(.*)$ /songs/$1-$2\.html [R]

This bulletin looks like it's been recently used and answered by you so I'm leaving my question..
Thanks in advance,
Jesse


cor - 24.10.08 1:54 pm

This is a very good question.

Firstly, I'm surprised you got your initial rewrite to work, having used "songs" as your virtual "directory", rewriting to an actual script called "songs.php". Many people attempting to replicate this would be left scratching their head, wondering why it didn't work.

I have to assume you either realized that Apache's content negotiation would mess it all up, and disabled Multiviews..

Options -MultiViews

.. or else you got lucky, and it was already disabled. Either way, it's a gotcha I had to mention, in case someone else reads your post and tries something similar.

So, you have your new flat links, and want to rewrite these, as well as existing dynamic links, so the the user sees only the new flat links in their address bar, while every request is rewritten to dynamic links in the background, regardless of its original form. I like your goal, which on the surface seems "elegant in its simplicity", as villains often say; but in practice, is thorny.

Personally, I would run sed over the entire site, and physically switch out all the old dynamic links for flat links, be done with it. However, I'll assume that's not possible or feasible, and continue with a purely .htaccess approach..

In your experimentation, you've likely discovered that getting both parts to work together is tricky; each individual rewrite works fine on its own, but together, put the browser into an infinite loop.

You probably also discovered that "L" flags (which instruct Apache to stop processing rules at that point), are not enough to prevent reprocessing on their own because in the per-directory scope (.htaccess, as opposed to httpd.conf), a redirect will re-inject the request at the server level, causing processing to begin again from the first RewriteRule; and there's that loop again. There is a solution.

The first part; catching the flat links, and transparently rewriting them to dynamic links; is simple enough..

RewriteRule songs/(.+)-(.+)\.html songs.php?page=$2&song=$1 [NC,L]

The thorns appear when you try to catch those pesky dynamic links on your old pages, rewrite them visibly into flat links in the browser's address bar, and then have them rewritten transparently back to dynamic links with the first rule (above). To accomplish this, we'll need to employ two "tricks". Here's some code..

RewriteCond %{THE_REQUEST} page= [NC]
RewriteCond %{QUERY_STRING} page=(.+)&song=(.+) [NC]
RewriteRule ^songs\.php /songs/%2-%1.html? [NC,L,R]

The first trick is the use of %{THE_REQUEST} in a RewriteCond, which matches only the original request (in its entirety), i.e. the actual link that was clicked, or typed into the user's browser. This prevents Apache applying the rules to requests that have already been rewritten. In this example, the page=, ensures that only requests with a query string containing that variable are affected. song= would work just as well.

The second trick is the use of the "?" at the end of the target (.html?), which essentially strips off the query string, again, preventing infinite reprocessing.

There are other ways to achieve a similar effect, but that code or something very like it will do the trick.

Have fun!

;o)
(or

references:
In fact, the second [L] flag is redundant in this example, but I added it because it's generally a good, efficient practice.



aconana - 26.10.08 8:41 pm

Many thanks for this extended enlightenment on good htaccess usage! I hope you can tolerate another three questions - a typo (or not?!?), a basic misunderstanding, and something in between.

•First code snippet (after the 6th paragraph) is the second line missing the end-of-string delimiter, i.e. should it be
RewriteRule ^(.*)\.htm$ $1.php

instead of
RewriteRule ^(.*)\.htm $1.php

That would be "not". Anchors are completely optional. It should, in fact, read.. RewriteRule (.*)\.htm $1.php, because it would better suit the poem. ;o)

•When does / doesn't (.*) pick up the query string? For example, in the "shortening URLs" section, the sample URL appears to give
$1 = "?file=my.zip"

but the "QSA Overkill!" sample appears to give only
$1 = "foobar.zip"

(i.e. excluding the ?foo=bar stuff). Does the [QSA] flag have anything to do with it?

(.*) greedily catches everything in its path. In the first exmaple it catches everything after "grab", and in the second, everything after "grab/". The [QSA] flag is what tags the original variables; "level=5" and "foo=bar"; back on to the target URL. ;o)

•Stripping a query string from a URL (in the "Just a demo!" code snippet) - why is even the question mark ? necessary?

The "?" is the only thing which IS necessary. As mentioned, this is what strips the URL of its query string. Technically, it creates a URL with a single empty query variable, which is automatically stripped off when the URL is re-injected. ;o)

Thanks for any further patience you have with this nit-picking!

No problem! ;o)


Jesse - 27.10.08 5:36 pm

Thanks so much for your interesting response. It's enlightening to say the least. mod_rewrite is a tough module to learn, there's so much deep stuff going on.. It moreless becomes a matter of learning the internals of apache. You're right about just editing all of the old stuff into the new links. The links are actually in a database I believe, I'm a freelancer so it's not my site.
After I thought about it for a while, it became obvious that mod_rewrite is mostly made to make 'fake' stuff rather than work with 'real' stuff. For example redirecting on a file that exists will never work... and that's the dead end that needs to be realized I think. This site is awesome. Thanks for your input!

While it's true that mod_rewrite is mostly used to "fake" stuff, there is nothing to stop you rewriting from a file that exists. Why you might want to do this, is another matter. mod-rewrite provides almost limitless possibilities; being processed before the browser gets the page.

As for your links; a database, that's even easier; one simple command (in phpmyadmin, for example) would change them all, something like this..

UPDATE tablename SET tablefield = replace(tablefield,"oldstring","newstring");

You could also add a "WHERE" clause, for more specificity. Have fun! ;o)



martín - 28.10.08 8:11 pm

I've changed my "oldsite.com" to a new site "newsite.com"
The oldsite was on php and the new on html.
Pages in google are listed as "www.oldsite.com/contact.php" which I would like to redirect to "www.newsite.com/kontakt.html" or www.newsite.com

installed this, but it only works if you enter the oldsite name, www.oldsite.com. not with the .php pages

DirectoryIndex index.html index.htm index.php
IndexIgnore *
RewriteEngine On
RewriteCond %°HTTP_HOST° ^www.oldsite.com$
RewriteRule ^°.*°$ http://www.newsite.com/$1 °R=301,L°
RewriteCond %°HTTP_HOST° ^oldsite.com$
RewriteRule ^°.*°$ http://www.newsite.com/$1 °R=301,L°

°=bracket

If this post is some kind of joke, worry not, I'll be deleting it soon enough. If it's not a joke, then please a) frame a question that makes sense, giving as much detail as possible, and b) read the above article (including the huge notice above these comments) first. ;o)


Paul - 29.10.08 5:06 pm

I am trying to rewrite from:

http://www.site.com/product_category.php?category_id=75a6fcc1df7dc77d1cd7ab39b7e45549

to

http://www.site.com/product_category.php?cat_id=sheet-protectors

Per your suggestion above I have stopped using mod_alias and started using mod_rewrite (because, after all, that is what this page is about). smiley for :evil:

But, it still is not quite right. Can you take a look at the commands below and help me?

RewriteCond %{HTTP_HOST} (.*)(?i)product_category\.php\?category_id=75a6fcc1df7dc77d1cd7ab39b7e45549
RewriteRule /product_category.php?cat_id=sheet-protectors 


Thanks again.


cor - 29.10.08 6:03 pm

Paul, you clearly don't understand how this works. Did you read the article at all? I mean, how on earth could the string (.*)(?i)product_category\.php\?category_id=75a6fcc1df7dc77d1cd7ab39b7e45549" match against your domain name? That's nuts! And the RewriteRule beginning with a forward slash; again, the article (above) explains why you would not do this inside an .htaccess file.

Och well, something like this will work..

RewriteCond %{QUERY_STRING} category_id=75a6fcc1df7dc77d1cd7ab39b7e45549 [NC]
RewriteRule ^product_category.php /product_category.php?cat_id=sheet-protectors [NC,R]

However, is that long category_id really necessary? If there are many such id's corresponding to many cat_id's, then fair enough; I guess you'll be writing lots of RewriteRules (in which case, add an "L" to the flags). If there is only one, then you can omit that long string from the RewriteCond, and simply check for the existence of category_id.

If there are lots of id's to map, it would be easier done in php (or similar), creating a mapping list somewhere, and rewriting all queries to the php handler.

;o)
(or


Daniel - 30.10.08 11:34 am

Hi, I wish to acheive something similar as Paul, I have a page, dealing with animals, and the get variable determins the id to sql out of the database to get all the info but I want to rewrite the url from this:

www.domain.com/species.php?id=18

to this:

www.domain.com/common-toad-bufo-bufo.html

Is it possible to query a database to get the data I want to do the rewriting or must I make a map (?) with each id corresponding to a certain string of information I would use? I like the sound of Php handler, what does this consist in?


Paul - 30.10.08 4:49 pm

Thanks for your help. Of course what you suggested works. You were only half right on your points, though: You are right that I clearly don't understand how it works. I have read the article many times over the years and have spent many hours trying to understand it. In the end I can't tell my foo bar from my egg foo young.

Addressing your code (or my implementation):
RewriteCond %{QUERY_STRING} category_id=046216723ed2bab34a3dab9fd01fdb19 [NC]
RewriteRule ^product_category.php /product_category.php?cat_id=sheet-protectors [NC,R,L]


Is this what it is saying: If the string equals category_id=046216723ed2bab34a3dab9fd01fdb19 (no matter what the case) then rewrite it so that it uses everything before product_category.php and replaces it with everything before the string plus /product_category.php?cat_id=cleer-adheer-laminating-film (no matter what the case, redirects and ends the rule)?

Also, what is the difference between mod alias and mod rewrite?

By the way, the links in your conclusion don't work for me as they just go to http://localhost/manual/misc/rewriteguide.html

Again, thanks for your help.

Paul


cor - 30.10.08 9:26 pm

No problem, Paul. Of course what I suggested works! Half right? That means I must also have been half wrong. Tell me exactly what I was wrong about, and I'll give you the dang-diddley abc of exactly how the code works.

For the difference between the two Apache modules; see here. Also check out the useful links section below the article.

By the way, I might have been tempted to dive into a full explanation right away; but I know you aren't paying attention. For example; did it not occur to you that not one but three links in an article read by thousands of people every day, might be correct; and instead, you are in error. You're skipping! The paragraph begins, "If you have apache installed on your system..". localhost is your machine! If you're not Apache'd-up, of course the links won't work.

And where did the cleer-adheer-laminating-film come from? smiley for :eek:

Daniel, what goes on in your back-end is your own business! As for rewriting, at a minimum, simply rewrite all requests to species.php, creating a variable with the custom string, and let that script do all the work. species.php then, is your "php handler"; it handles the variables.

Somewhere; in a database, or a plain text ini-type file, even inside the handler itself, the string "common-toad-bufo-bufo" is translated to the integer, "18", which I assume means something to the script; an sql table id, or whatever. At any rate, "18", and its associated data are now available for processing by your script.

How much of all this is handled by .htaccess, and how much by your php script, depends on the number of transformations (mappings) you need. One or two would be simpler in .htaccess; one ruleset per mapping; but a longer list would be better handled by your server-side code; i.e. php.

Decide what you need, and try a few things.

;o)
(or


Jesse - 31.10.08 1:37 am

Just a quick note to some people posting on here. mod_rewrite is used best in making simple links that only involve 2 or 3 variables at the most. Take for instance

www.site.com/food/fruit/banana.html

looks much better than

www.site.com/index.php?category=food&sub_category=fruit&name=banana

..ideally if everything is planned right from the beginning, then you can put all the info you would ever need to in the link without any &,=, or ?.

Thanks for the input! Also see here. ;o)

one more thing completely different but same topic is you can use php header("Location: somefile.php?stuff") to make up for anything that doesn't otherwise with mod_rewrite.. it's a dirty hack and i don't recommend it but it works..

Though DO read the manual for that. ;o)


Amin - 31.10.08 6:45 pm

If I want my url to look from this

http://www.mysite.com/index.php?t=browse_artist&letter=a

to

http://www.mysite.com/browse_artist&letter=a.php

How can I write the mod rewrite, I am new to php and linux.

Thanks

Simple create a new plain text file called .htaccess in the root of your site, and put the rules in there. ;o)


Rohan - 02.11.08 12:04 pm

If you are familiar with regular expressionssmiley for :eek:, you can master URL rewriting under 2 minutes! smiley for :D

And if you put all the worms in the world end-to-end, they would reach from here to the Moon. Oh, no, wait a minute; the one in the middle would probably wriggle and spoil it. ;o)


Paul - 07.11.08 8:31 pm

The part where you were half wrong is where you imply I did not read the article. And I did not say the links did not work, I said they did not work for me...smiley for :evil:

Thanks for the links to the difference between alias and rewrite.

Paul

Exacitly my point! If you'd read the beginning of the paragraph, you would have known that the links only work when you have Apache installed; which is something I encourage all serious webmasters to do. ;o)


Andrew - 09.11.08 5:23 pm

Hi there,

Thanks for the guide. I'm in the situation of having two domains on the same host; I've been trying to use the htaccess file as you've outlined above, but with limited success. The links are pointing to the right files/folders, but the server seems to be 301 redirecting the URLs rather than rewriting them. The new URLs appear in the browser address bar, and the server seems to be sending a 301 redirect, according to web-sniffer.net.

Anyway, if you've any ideas why my code isn't working, I'd be glad to hear them. Apologies in advance for any obvious errors.

RewriteCond %{HTTP_HOST} myfirstdomain.com 
RewriteCond %{REQUEST_URI} !^/ga 
RewriteRule ^(.*)$ ga/$1 [L]  

RewriteCond %{HTTP_HOST} myseconddomain.co.uk 
RewriteCond %{REQUEST_URI} !^sp 
RewriteRule ^(.*)$ sp/$1 [L]

Thanks!

Andrew

A slash in front of the "sp" in the second ruleset's RewriteCond would be a good idea. Aside from that, it all looks fine; I can't see anything that would force a 301 external rewrite. Feel free to email me with your actual domain name and full .htaccess file - I'm curious. ;o)


Catherine - 13.11.08 7:26 am

Fanastic - after searching high and low your page fixed my problem. I could kiss you :-)

Hey, if you're local to Aberdeen, feel free! ;o)


evipbg - 18.11.08 5:48 am

Brilliant!

Thank you, a lot.


Pratik Thakkar - 18.11.08 9:31 am

Hi,

I am facing problems with multiple .htaccess files - one in parent and one in subfolder.

My parent .htaccess file
RewriteEngine on

RewriteRule ^(images|swf|includes|admin)(.*) - [L]
RewriteRule ^((.*).html|(.*).rss|^(\d+)$|(.*)/$) /index.php [L]


Now .htaccess in the folder "/admin"
RewriteEngine on

RewriteRule ^admin/(.*) /admin/index1.php [L]


I want all pages in the directory admin and its sub-folders to go to /admin/index1.php.


But I always get an error saying "Access Forbidden!" - You don't have permission to access the requested directory. There is either no index document or the directory is read-protected.

The only php file under /admin is index1.php.

How do I acheive this? Am I doing something wrong?

Any help will be highly appreciated.

Kind Regards,
Pratik Thakkar

Try.. RewriteRule .* index1.php [L] ;o)


reub - 21.11.08 5:28 am

oh course im a bloody human!


 

leave a comment, become part of this site!


First, confirm that you are human by entering the code you see..

(if you find it difficult to read, refresh the page for a new code)


Enter the 5-digit code this text sounds like : lower-case elle, Upper-Case Ee, zeero, lower-case you, Upper-Case Eff


 
 
[site notice]

PLEASE, !