ESSENTIALS - This page contains information that you can use as you introduce yourself to a topic.

Note: In some circumstances, you will see in other documents that you can modify the behavior of a request in your settings.php file. This article focuses only on .htaccess.

Introduction¶

The .htaccess file controls a number of ways that a website can be accessed, blocked, and redirected. It does this using a series of one or more rewrite rules. These rewrites are made possible by Apache's mod_rewrite module.

mod_rewrite provides a way to modify incoming URL requests, dynamically, based on regular expression rules. This allows you to map arbitrary URLs onto your internal URL structure in any way you like.

Basic Format¶

The basic formulation of any .htaccess rewrite rule includes setting a combination of rewrite condition (RewriteCond) tests along with a corresponding rule (RewriteRule) if the prior conditions pass. In most cases, these rules should be placed at any point after the `RewriteEngine ON` line in the .htaccessfile located in the website's docroot.

Creating a useable rule generally breaks down into three steps:

1. Determining where the tests go
2. Building the Conditions
3. Executing the Rule

You may also find the following items handy:

• Common variables
• Common flags
• Tools

Determining where the tests go¶

As noted previously, rewrite rules execute after the `RewriteEngine ON` line in the .htaccess file. We often see customers place rewrite rules after Drupal's core rewrite rules (which route the request to be handled by Drupal). These rules will typically not be evaluated, because Drupal's default request handler rules will take precedence. If you are adding rewrite rules to Drupal, they should typically be:

• Within the ... block
• After the `RewriteEngine ON`  line
• Before Drupal's request handler rule

  Note: As Drupal versions change, these line numbers may also change. Double-check the code to ensure that your placement is correct.

  • Drupal 8 - http://cgit.drupalcode.org/drupal/tree/.htaccess?h=8.0.x#n134
  • Drupal 7 - http://cgit.drupalcode.org/drupal/tree/.htaccess?h=7.x#n112
  • Drupal 6 - http://cgit.drupalcode.org/drupal/tree/.htaccess?h=6.x#n109

Building the Conditions¶

The first step to rewriting a path is to create a condition which will either pass or fail. This condition will then cause the rule to process, or not. Regular expressions power each condition, and are based on a group of common variables.

In some cases where simple path redirection is required, you can skip setting a RewriteCond and a RewriteRule can be passed with a simple condition. Any other conditions, including conditions based on the HTTP_HOST, must be done through a RewriteCond line.

Syntax¶

RewriteRule¶

RewriteRule Pattern Substitution [flags]

• pattern - regex, matched against URL-path
• substitution - string that replaces the matched URL-path
• flags - optional, special actions (L, R)
• If a rule is triggered, you typically want to handle the request and stop evaluating any other rules ([L] flag)

RewriteRule Example¶

RewriteRule contest http://example.com/node/123 [L,R]

• Request to http://example.com/contest will redirect to http://example.com/node/123
• Response code 302 (default R=302)
• Stop evaluating rules [L]; Redirect [R]

RewriteCond¶

RewriteCond TestString CondPattern [flags]

• TestString - server/env variables, HTTP_HOST, REQUEST_URI, etc.
• CondPattern - condition, usually a regex; can use a file attribute test
• flags - optional, special actions (NC, OR)

A RewriteCond checks the value of variables, in order. The default behavior is EQUAL TO. You can change this by using an exclamation point, like the following which will be evaluated as "X-Forwarded-Proto is NOT https":

RewriteCond %{HTTP:X-Forwarded-Proto} !https

Adding regex to the condition makes it very powerful. For example, the following line looks for domains that do not start with www:

RewriteCond %{HTTP_HOST} !^www\. [NC]

RewriteCond rules are parsed from top to bottom. This allows multiple conditions to be placed back to back which will evaluate by default with AND before the RewriteRule is either executed or skipped. The following rule is executed as "If the request is not over HTTPS AND the host matches example.com" If both conditions pass, the following RewriteRule is executed, if one but not the other pass this rule is skipped:

RewriteCond %{HTTPS} off 
RewriteCond %{HTTP:X-Forwarded-Proto} !https 
RewriteCond %{HTTP_HOST} ^example\.com$ [NC]
RewriteRule ^ https://www.%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Executing the Rule¶

A RewriteRule will be executed after each preceding condition or group of conditions has passed. If there are no conditions set prior to the RewriteRulethe rule will automatically execute.

Note: If you place a RewriteRule in a block of existing conditions it will be assumed that these conditions are required for the rule to execute.

Rewrite rules also include the ability to use regex matching on the URI before it is executed. In this case, a RewriteCond is not necessary and the condition can be rolled directly into the rule.

RewriteRule takes two parameters.

• A condition based on the request URI on which to execute the Rule.
• If this passes, the second parameter is the rule to execute.

Variables such as %{HTTP_HOST} and %{REQUEST_URI} can be passed to the second parameter as well as matching results from the regex pattern in the condition by using $1, $2, and so on.

In the following example, this is used to redirect all requests from one directory on a site to another directory. In this instance, only URI matching is necessary, no prior RewriteCond is required. Also, the regex pattern results are used to redirect any path requested relative to the directory to the same URL in the new directory:

RewriteRule ^oldfolder(.*)$ newfolder/$1 [L,R=301]

Variables and flags¶

Variables and flags perform similar, but not quite the same functions for rules and conditions. Variables generally are near the beginning of the rule, and refer to where the parts of the incoming request. Flags are generally at the end of a rule, and indicate a response to a request.

Common variables¶

These are some of the variables that can be used when constructing a RewriteCond and a RewriteRule:

The following variables are specific to Acquia Cloud customers:

Common Flags¶

Flags are set between brackets at the end of a RewriteCond or RewriteRule. Multiple flags may be separated by commas. A full list of flags is available at RewriteRule Flags .

Most of the flags specifically apply to RewriteRule. Only the [NC] and [OR] flags are most commonly used with RewriteCond.

Tools¶

Acquia recommends testing your rules in a non-production environment. There are some tools available to help you with pre-testing:

• Testing your htaccess rules: http://htaccess.madewithlove.be/
• Building and testing your regex matching: http://regexpal.com/
• Learning Regular Expressions

Drupal modules¶

In cases where .htaccess file level redirects are more heavy-duty than necessary, or you don't have or don't want to give server-level access, there are some Drupal modules you can use to do redirects:

• Redirect
• Global Redirect

Either of these may be a simpler or more efficient solution to a redirect problem, especially in cases where bootstrapping Drupal is not an issue.