Complete Guide to Mod Rewrite Rules & Diretives

Hellow and Hi  


This time I took a bit of a change from the usual subjects i write, not a big change though. The reason for writting this set of articles (More to come and there's another beginners one as well) is because i felt that there isnt a proper or complete guide written for the pure beginners to start with mod rewite. I myself had great trouble in understanding + searching through forums to be understood certain fcts. Anyhow i hope many other would be saved of countless search entries by this article 

TWO things before proceeding :


[1] If you are a real begginer and have no idea about mod rewrite and got this page after some Google search, then i recommend to read the first article of the set to get a better understanding of all related stuff.


http://manzzup.blogspot.com/2011/09/intr...e-mod.html


[2] Noone can master writting rules, it is all about expressions and what you get is what you get through experience. So this article is not n00b->pr0 conversion article but something full for you to get started with. I have referred to various forum, countless articles and blogs before to get the understanding about the subject [that was when i was on the blog moB project]. And i want to make this a COMPLETE ALL IN ONE GUIDE

LEts go coding -->

RewriteRule
First we need to know what actually you get in a .htaccess file
example file is like belows

http://myoldsite.com/.htaccess (you cant access it like this though)

Code:

RewriteEngine On
RewriteRule ^(.*) http://mysite.com/$1

Thats what will likely be there inside, but of curse it doesnt mean anything to you ATM
but it WILL [soon ]


1 -> The first line is pretty self explanatory, it turns on the RewriteEngine, it is needed to turn on the runtime engine.


2 -> The second line is what you call the HERO of the story, the command lie here.
It defines rules for the behaviour of the engine (ex: this line would redirect every browser going to myoldsite.com to mysite)
The structure of a rule is:

Code:

RewriteRule Pattern Substitution [OptionalFlags]

Now we'll split it up and analyse part-by-part


Portion 1 : RewriteRule
That is mandatory for defining a rule, basically it should be there for evey rule [pretty stupid even to explain it ]


Portion 2 : Pattern
Pattern is a Regular Expression that defines which kind of URL should be processed by the engine. I other term, all URLs send to the server having the defined Pattern would be rewritten/procced or changed.
Writting the Pattern is a bit trick, so lets get to that part seperately.


Portion 3 : Substitution
Plainly this tells what to be placed instead of the requested String. Or this is the replacement for any found match as defined above.


Portion medium : Optional Flags
As the name says they are optional but it is good to know them. These put at the end of each Rule (within sqaure brackert [] ) would affect the way script works with each Rule. The most common cases are as follows:


[F] - Forbiddened. Retricting user access so that the users will get an "Error medium0medium".
[L] - Last Rule. If this rules matches, non other would be processed down the list.
[R] - Visible Redirection. User sees the change of the url, well this is not much preffered
--[R=301 or 302] can be used
[G] - Force to go medium01
[N] - Next round. Rerun the rules again from the start
[C] - Chains a rewrite rule together with the next rule.
[T] - use T=MIME-type to force the file to be a mime type
[NS] - Use if no sub request is requested
[NC] - Makes the rule case INsensitive
[QSA] - Query String Append use to add to an existing query string
[NE] - Turns of normal escapes that are default in the rewriterule
[PT] - Pass through to the handler (together with mod alias)
[S] - Skip the next rule S=3 skips the next 3 rules
[E] - E=var sets an enviromental variable that can be called by other rules


Remeber that you can 2 or more together in one condition by separating them via ' , '
ex: [L,R]


So, now you know about the strcuture, lets write the "Hellow mod rewrite" first so that we can move further through examples [or you would sure to k!ll me for keep you waiting ]


Writting a .htaccess file


1. First we need a case to write a htaccess file, make two html files
come-here.html : add any content you like
now-here.html : add something like "Hellow mod rewrite? "


2. Now put them in the root of your server [I am assuming that you have the required knowledge with servers and stuff]


3. Open up your FAVORITE text editor and shoot this up. [case sensitive]

Code:

RewriteEngine On
RewriteRule ^come-here.html$ now-here.html

medium. save it as .htaccess [if your editor donot allow you to save without a file name, put a file name and manally remove it]


large. Add this with the other two files the root/home directory.And navigate to the come-here.html
ex: http://mysite.com/come-here.html


YEAH you will see the contents of the "now-here.html" file, but the URL is the same. VIOLA!@!? not yet 
now you ask me, WTF does this code means, hell i was trying to tell you when you wanted to code first.  so lets learn the patterns.


Writting mod rewrite Patterns


Explaining common pattern characters


\ - Escape character. Like in real world programming languages, this escapes the functionality of normal regular epxression characters like $ ^

Code:

\$ means the character $
          \^ means the character ^

^ - Starts with. This defines how to the expression starts

Code:

^man : EVERYTHING starting with word "man", so that a URLs like
           [url]http://mysite.com/man[/url]   [url]http://mysite.com/maned.html[/url] would qualify

$ - End with. This defines the ending of the expression

Code:

^man$ : ONLY the EXACT match of "man" would qualify
             [url]http://mysite.com/man[/url] would qualify but
             [url]http://mysite.com/maned.html[/url] would NOT

. - Any character. This says "match any ONE character that is there"

Code:

^man.   : [url]http://mysite.com/assed[/url] qualifies
             [url]http://mysite.com/man[/url] DOESNOT qualifies as there should be at least one character after "man"
^man.$ : [url]http://mysite.com/mane[/url] would qualify, but assed would not as the $ is used, only ONE character can
             be there after "man"

[ ] - Starts a segment / Class. Inside a Class you can put up a wide expression.

Code:

[man]$ : Search for the exact word "man" with cases sensitivity, [url]http://mysite.com/man[/url]
  [^man]$ : Here the ^ character is behaving to give the action NOT. Means this says NOT "man" or
                 everything except man. [url]http://mysite.com/man[/url] would only returns an error
  [a-z]$  : Any word with lowercase letters
  [A-z]$ : Any word with lowercase + uppercase letters
  [A-z0-9]$ : YUP you gueesed right, Any word with lowercase + uppercase letters + numbers from 0-9

( ) - Starts a Back Reference Point. This would be needed to get the matched pattern from the engine. You can get the matched stirng by using $1 in the substitution [will be explained later]


| - match this OR that
[aa]$|[bb]$ : http://mysite.com/aa OR http://mysite.com/bb would ONLY qualify
[NOTE donot make spaces between one expression and the | ]


? - Match the expression 0 or 1 more times in a String.


^[man]?$ : http://mysite.com/man


+ - Match At Least 1 or More times


^[man]+$ : http://mysite.com/manmanman


{ } - Match to a given number of time


^[man]{0,2}$ : Match the word "man" upto 3 times (dont ask me why 3 times )


* - Match indefinite (~) times


^[man]*$ : http://mysite.com/manmanmanmanman


But in all cases any other character/word interruption would break the search !


! - Says NOT, put it infront of any expression to null it


< > = - Comparing stuff


-d - Directory


-f - File


NOw say !!VIOLA/2!! 
Why devided by 2? because therez another half and a ton waiting to be explained. However they will be there while we move onto some examples. The practical stuff.


I wont be going onto the "Writting the Rules steps again, only the Rule itself would be discussed.


Example 1:


Our previous code

Code:

RewriteRule ^come-here.html$ now-here.html

its your turn, guess it first! [obviously you arent that dumb not to understand ], in plain english it says
"redirect any URL having the the exact phrase 'come-here.html' to now-here.html". Pretty cool hah?


Example 2:


Problem : All traffic going to http://mysite.com/forums redirected as it is to http://myforum.com
Understanding the situation:
1. http://mysite.com/forum/view.php -> http://myforum.com/view.php
2. http://mysite.com/forum/show.php?1223 -> http://myforum.com/show.php?1223


Solution:
The best way is to make a directory called "forum" in mysite and put a .htaccess file in it to redirect all the traffic to the new host.
Note that you can put the .htaccess in the directory to have customized actions


Rule:

Code:

RewriteRule (.*) http://myforum.com/$1

NOTE: $1
This is the Back referencing, the paranthesis allows the engine to remember the matched String and it is used by using $1 .




There are many more real world problems, i will post the reference links at the end if you are curious about reading them.


NEXT PART :::--


Now the big star RewriteRule is introduced, here comes the sidekick RewriteCond
Plainly it is the "if" statement of mod rewrite. Lets see when we will need such a thing.


-->Back to Example 2
So all the traffic now goes to http://myforum.com/ the big admin is really happy, but only untill he found out that his [my :S] articles have some links to Smiley images linked to the forum images. This is a good break point for you to understand that mod rewrite wont be working for hotlinking, it would just get an ugly error, so now the whole thing screwed up and he needs to put up the script which says:


"redirect all traffic except the links to the 'images' directory "


and you says GOTO HELL this is not a freaking language and you are kicked out.
NO, you call up a pretty little RewriteCond


RewriteCond


Structure :

Code:

RewriteCond TestString CondPattern

TestString : A set of special Strings to check for a certain exception
CondPattern : The pattern to be searched


See this example:

Code:

RewriteCond %{REQUEST_URI} !^/images/
RewriteRule (.*) http://myforum.com/$1

Saw the addition? the new Cond will say "if not the Requested URI contains /images/ proccees with search" if it is there, do nothing.


The RewriteCond is something you would have to search for more as many have no need of it in there cases, but it is REALLY IMPORTANT TO KNOW THEM. Here's the TestString list you can use from
"Apache Official Documentation"


Http Headers


HTTP_USER_AGENT
The clients browser by the userAgent name. (MSIE/Firefox.Chrome)
HTTP_REFERER
The referng URL/URI/IRI/whatever of the refering site.
HTTP_COOKIE
Cookie
HTTP_FORWARDED
Sorry i have no idea :S
HTTP_HOST
The Host obtained from the request of the client (http://zontek.net.tc)
HTTP_PROXY_CONNECTION
The Proxy of course
HTTP_ACCEPT




Connection and Request


REMOTE_ADDR
The IP of the current viewing page (192.168.0.1)
REMOTE_HOST
Mostly the domain name
REMOTE_PORT
Port used for the connection
REMOTE_USER
User accessing
REMOTE_IDENT
REQUEST_METHOD
GET/POST other methods
SCRIPT_FILENAME
PATH_INFO
QUERY_STRING
AUTH_TYPE


Server Internals


Server information


DOCUMENT_ROOT
SERVER_ADMIN
SERVER_NAME
SERVER_ADDR
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE


System Stuff


Time/Date related stuff [According to the configuration of the server]


TIME_YEAR
TIME_MON
TIME_DAY
TIME_HOUR
TIME_MIN
TIME_SEC
TIME_WDAY
TIME


Specials


API_VERSION
THE_REQUEST
REQUEST_URI
REQUEST_FILENAME
IS_SUBREQ
HTTPS


To findout find they does, TRY THEM ON!
But as you all are lazy like laziers [err?] I would put up some examples 


Example 1 : Blocking A specific IP from accessing the site

Code:

RewriteCond %{REMOTE_ADDR} ^192.168.0.2$
RewriteRule (.*) get-the-hell-out-of-here.html

That will redirect all the traffic from 192.168.0.1 [my experimental pc ] to the mentioned html


Example 2 : Blocking Internet Explorer from access [YUP I HATE IT :|]

Code:

RewriteCond %{HTTP_USER_AGENT} MSIE
RewriteRule (.*) get-the-hell-out-of-here.html

That's engouh I guess


Now OMG it is nearly the end, and its past 10.00 PM here and i have been writting this for 2 days [well not at a stretch], but there's one little tiny part left .


Other Diretives


There are certain other but important parts (Directives) to be known, brief explanations would be given of each


RewriteBase


Set the base URL per directory. Once define, the expression would be applied to the path - the diretory name.


Structure :

Code:

RewriteBase URL-path

Example :

Code:

RewriteBase /forum
RewriteRule (.*) http://myforum.com/$1

RewriteOptions


This defines certain special options that can be used.
ex: inherit inherit will force the .htaccess to inherit properties form its parent


Structure :

Code:

RewriteOptions Options

Example:

Code:

RewriteOptions inherit

NOTE: There are few other diretives like RewriteMap, RewriteLog & RewriteLock. But these are configured by the Server config or the vitual host. So those arent of very much use [but of importance]. If you would like to know about them please refer the official docuementation


HaaH thats ~~ALL~~ 


Some Stuff to remember:


1) Rewritting takes PROCESSING power of your server, so make your ruls far simple as possible. For an example if you want to check for a large number of availabilities but only a few exception in a String, make sure you check for the NON availability of the exception so that it saves the power as well your head.


2) AGAIN all of these are CasE SENsitive


3) Practice only would bring the excellence


medium) Non other than the creator can ever know the whole thing, so dont worry about being the GURU, there's Google for that 


large) Theory without practice == NULL+VOID


6) Come to [URL="http://manzzup.blogspot.com"]my blog[/URL] from time to time to check for new updates and to give my ads some impressions so i can save a few $$ for a hard disk 


References :


1. For a complete list of common Flags
http://www.webforgers.net/mod-rewrite/mo...syntax.php
Full List here : http://httpd.apache.org/docs/1.3/mod/mod...ewriteRule


2. For the immense reference and support [The official document(s)]
http://httpd.apache.org/docs/current/mod...write.html
http://httpd.apache.org/docs/2.0/misc/rewriteguide.html
http://httpd.apache.org/docs/2.0/mod/mod...ewritecond


3. For some awesome 10+ tips to be added [MUST read]
http://www.noupe.com/php/10-mod_rewrite-...-know.html


medium. Some General Stuff
http://www.workingwith.me.uk/articles/sc...od_rewrite