[NANOWEB DOCUMENTATION]

NANOWEB, the aEGiS PHP web server

mod_rewrite

This module tries to imitate the famous apache module. However not all features supported in the original one can be used with this version.
See bottom of this file for what it doesn't understand.

mod_rewrite is used to map requested file names to existing files by using regular expressions. For example, if your browser wants to GET say
http://www.example.com/thisfile.html
you can use the keyword "RewriteRule" to change the requested filename:

  RewriteRule  thisfile  changedfilename  
so that a file named "changedfilename.html" gets sent back to the browser.

Such keywords must be written into files named ".htaccess" in the directory the rewriting shall take place.

This mod_rewrite supports most of the regular expression syntax that you can use with apache's module: 


    .        matches any character  
    .+       matches many of any character, at a minimum of 1  
    .*       matches also zero length character string  

    [a-z]    matches one character out of specified range  
    [4x#]    matches one of the specified characters  
 
    ()       grouping (and for backreferences in replacement string)  
    (a|bc)   matches "a" or "bc"  
 
    .{2,5}   exactly specified repeat count (here: 2 to 5 of any character)

An exclamation mark ! at the beginning of a regex means that the rule matches only if the regular expression pattern itself doesn't match the filename of the requested URL.

If you used one of the special regular expression characters in a filename you just have to prepend this character with an backslash to mask it,
for example \* just matches the asterisk character and not a row of backslashes.

an example:
 
  RewriteRule  file([a-z])+[.]html  new$1.php  
would rewrite specified name "fileABC.html" to "newABC.php", where the dot occurred in square brackets to only match the dot and not _any_ character.



RewriteRule

RewriteRules may also have some flags specified (write these in brackets!, comma separated list of flags), so the complete Syntax is: 

    RewriteRule  REGEX  REPLACEMENT  [flag1,flag2,...]
[NC|nocase]
make regular-expression match case-insensitive
[R|redirect]
send an redirection header back to the browser, default HTTP errorcode will be 302 (TEMP), you can specify others by appending the code [R=301] or these special values: [R=TEMP] (default), [R=permanent], [REDIRECT=seeother]
[P|proxy]
if mod_proxy is loaded, you may do an (internal) redirect to another server for virtual inclusion of thats content; use http://example.com/... as replacement string to make this work
[F|forbidden]
sends http status code, that tells client "no permission"
[G|gone]
tells browser, that requested page no longer exists
[L|last]
stop rewriting URLs after this Rule
[N|next]
restart rewriting with first rule
[chain|C]
if this rule does not match, do not use following one (you can chain several rules together by use of this flag)
[type|T=MIME-type]
set mime of the target file
[qsappend|QSA]
if you rewrite a filename and specify ?var1=xy any previous query-string will be lost; this flags preserves former values and just appends your new ?var1=xy
[skip|S=num]
skip next "num" rules, if the current one matches
[env|E=VAR:VAL]
set environment variable to specified value (may contain backreferences to regex) if rule matches
[header|H=X-Header:Content]
sets the disired HTTP response header to given value; Note that overriding default response headers may not work in all cases.
This flag is not found in apache's mod_rewrite, so using it will make this rule a trap for the apache module.

But see also the much more complete apache documentation about RewriteRule.

RewriteCond

There exists another keyword, which just does regex matches, but no rewritings; and by failure prevents following RewriteRules from being executed: 

  RewriteCond  TESTSTRING  CONDPATTERN   [NOCASE,ORnext]  

Here the second argument is the regular expression, and NC and OR are the only allowed flags.
TESTSTRING can be constructed by using %{SERVER_VARS} or backreferences to last RewriteRule-groups $NN or RewriteCond-groups %NN. For more Information see the documentation of apache's mod_rewrite.

Available vars are for now:

CONDPATTERN may be a regular expression as seen above, or:


-d tests TESTSTRING to be an existing directory
-f tests TESTSTRING to be an existing file
-s file specified by TESTSTRING must be grater than 0 bytes

>CONDPATTERN must be lexically greater than TESTSTRING
=CONDPATTERN must be lexically equal to TESTSTRING
<CONDPATTERN must be lexically lower than TESTSTRING

ReflectRewriting directive

Syntax: ReflectRewriting = 1
Context: Server Config
Status: mod_rewrite, mod_multiviews

will reflect changes to the requested path name in server error responses, when for example the rewritten file name does not exist or has no read permissions set; otherwise the url from the request will be printed in such server messages.
Note: This config directive affects mod_multiviews as well.


differences to apache

in nanoweb the main server formerly (pre 1.8.0) used to append 'index.html' to the request_uri, when it existed in the given path, the workaround was to use following regular expression (not necessary anymore): 
  RewriteRule  ^(index.html)*$  otherpath/new-index.html   


this mod_rewrite clone does not support:

- some of that very special Rule-flags
- rewriterules in main server config (not yet)
- all the other keywords:
  RewriteEngine (not yet)
  RewriteBase (not yet)
  RewriteOptions (inheritance of rules, not yet)
  RewriteLog*, RewriteLock, RewriteMap


examples

  #-- WAP-redirect, based upon accepted file type

  RewriteCond %{HTTP_ACCEPT} (x-)*(application|text)/(x-)*(vnd[-.])*(wap[-.]|wml)+

  RewriteRule ^(index.html)*$ index.wml [L]



  #-- redirect file names to google search
  
  RewriteRule  ^(.+)$   http://www.google.de/search?q=$1  [R=seeother]

But, see also the URL rewriting guide from the apache.org team (they must know it!) ;>

NANOWEB, the aEGiS PHP web server

Index   Modules   Configuration   READMEs   FAQ   Support Forum