Module Structure

Rewrite Configuration Guide

URL rewriting is a common function of HTTP servers. However, the rules and configuration differ widely between them. Below are some common approaches across a variety of popular web servers available at the time of writing.

Apache HTTP Server

All examples that follow use mod_rewrite, an official module that comes bundled with Apache. To use it, mod_rewrite must either be included at compile time or enabled as a Dynamic Shared Object (DSO). Please consult the » Apache documentation for your version for more information.

Rewriting inside a VirtualHost

Here is a very basic virtual host definition. These rules direct all requests to index.php, except when a matching file is found under the document_root.

  1. <VirtualHost my.domain.com:80>
  2.     ServerName   my.domain.com
  3.     DocumentRoot /path/to/server/root/my.domain.com/public
  4.  
  5.     RewriteEngine off
  6.  
  7.     <Location />
  8.         RewriteEngine On
  9.         RewriteCond %{REQUEST_FILENAME} -s [OR]
  10.         RewriteCond %{REQUEST_FILENAME} -l [OR]
  11.         RewriteCond %{REQUEST_FILENAME} -d
  12.         RewriteRule ^.*$ - [NC,L]
  13.         RewriteRule ^.*$ /index.php [NC,L]
  14.     </Location>
  15. </VirtualHost>

Note the slash ("/") prefixing index.php; the rules for .htaccess differ in this regard.

Rewriting within a .htaccess file

Below is a sample .htaccess file that utilizes mod_rewrite. It is similar to the virtual host configuration, except that it specifies only the rewrite rules, and the leading slash is omitted from index.php.

  1. RewriteEngine On
  2. RewriteCond %{REQUEST_FILENAME} -s [OR]
  3. RewriteCond %{REQUEST_FILENAME} -l [OR]
  4. RewriteCond %{REQUEST_FILENAME} -d
  5. RewriteRule ^.*$ - [NC,L]
  6. RewriteRule ^.*$ index.php [NC,L]

There are many ways to configure mod_rewrite; if you would like more information, see Jayson Minard's » Blueprint for PHP Applications: Bootstrapping.

Microsoft Internet Information Server

As of version 7.0, IIS now ships with a standard rewrite engine. You may use the following configuration to create the appropriate rewrite rules.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <configuration>
  3.     <system.webServer>
  4.         <rewrite>
  5.             <rules>
  6.                 <rule name="Imported Rule 1" stopProcessing="true">
  7.                     <match url="^.*$" />
  8.                     <conditions logicalGrouping="MatchAny">
  9.                         <add input="{REQUEST_FILENAME}"
  10.                              matchType="IsFile" pattern=""
  11.                              ignoreCase="false" />
  12.                         <add input="{REQUEST_FILENAME}"
  13.                              matchType="IsDirectory"
  14.                              pattern=""
  15.                              ignoreCase="false" />
  16.                     </conditions>
  17.                     <action type="None" />
  18.                 </rule>
  19.                 <rule name="Imported Rule 2" stopProcessing="true">
  20.                     <match url="^.*$" />
  21.                     <action type="Rewrite" url="index.php" />
  22.                 </rule>
  23.             </rules>
  24.         </rewrite>
  25.     </system.webServer>
  26. </configuration>

Module Structure