A diretiva RewriteRule é o verdadeiro cavalo de força da reescrita de URL. A ordem que essas diretivas aparecem em seu arquivo de configuração importa. Em tempo de execução a regra de reescrita que for aplicada primeiro modifica a URL a partir deste ponto adiante. Uma típica URL-FULL possui o seguinte formato:

http://server:port/path/program?query_string

Suas partes são:

• http ou https representam o protocolo chamado de esquema (scheme);
• server é o nome da máquina servidora, também chamado de hostname;
• port é a porta TCP padrão, que pode ser omitida na URL se for 80;
• /path/program é o caminho web até um recurso chamado de URL-PATH;
• ?query_string é uma consulta de dados ou passagem de parâmetros.

A sintaxe de RewriteRule consiste de três argumentos separados por espaços.

1. A regex (Pattern) define quais URL's são afetadas pela regra;

2. Substituição (Substitution) - A porção que irá substituir outra, dentro da URL, quando a URL original combinar com a regex (Pattern);

3. Sinalizadores (Flags) - São opcionais e afetam a requisição reescrita.

A diretiva RewriteRule funciona em todos os contextos (server config, virtual host, directory, .htaccess) e permite sobrescrita no grupo FileInfo.

O valor para Pattern é uma regex que inicialmente é comparada contra uma URL-PATH contida na requisição de entrada ou ainda sobre a saída da primeira regra RewriteRule, onde a substituição ocorrer. URL-PATH é a porção da URL após o esquema (http://) e do hostname, mas anterior ao inicio de uma consulta (?query_string). Um ponto de interrogação marca o início do campo consulta.

Num contexto de diretório, uma URL-PATH é equivalente ao caminho relativo do diretório no sistema de arquivos para o qual uma regra é definida. Uma vez que a substituição ocorreu, as regras seguintes são aplicadas sobre a URL modificada pela diretiva RewriteRule anterior, permitindo uma cascata de modificações posteriores. Isso pode ficar confuso em algum momento!

Observe que se você deseja combinar contra a porção do hostname, da porta TCP ou porções da consulta (?query_string), então a diretiva RewriteCond deve ser utilizada com %{HTTP_HOST}, %{SERVER_PORT} e %{QUERY_STRING}, respectivamente.

Observe o modelo de funcionamento da diretiva RewriteRule: Pattern - É a expressão regular (regex) que você deseja checar contra uma URL enviada em uma requisição HTTP. Em uma URI, tudo que vier após o esquema e do nome do host (http://hostname) é comparado contra Pattern, exceto o conteúdo de query_string.

Substitution - O valor contido aqui pode assumir quatro funções diferentes:

1. Um novo valor para Pattern;
2. Um caminho absoluto para um arquivo no filesystem;
3. Uma URL completa redirecionando a requisição para outro lugar;
4. Um traço (dash) que indica para não fazer NADA!

[Flags] - Sinalizadores especiais que podem assumir DIVERSOS valores e que realizam ações como, por exemplo, definir variáveis, cabeçalhos de controle, redirecionar ou negar acesso. São vários sinalizadores e alguns deles podem ser combinados entre si.

Exemplos de RewriteRule

Um caminho absoluto para um recurso no sistema de arquivos como:


Isso mapeia uma solicitação para um local arbitrário em seu sistema de arquivos, como faz a diretiva Alias.

Um caminho Web para um recurso como:


Se a diretiva DocumentRoot é configurada para /usr/local/apache2/htdocs, então essa regra faria o mapeamento da requisição http://exemplo.com/foo para o caminho /usr/local/apache2/htdocs/bar.

Uma URL absoluta:


Essa regra diz ao cliente (navegador) para refazer a requisição para um outro endereço (redirecionamento). O sinalizador [R] significa redirecionamento com código de erro HTTP igual a 302. Outros códigos HTTP podem ser especificados explicitamente como [R=301] ou [R=304].