When not to use mod_rewrite (original) (raw)

Available Languages: en | fr

This document supplements the [mod_rewrite](../mod/mod%5Frewrite.html) reference documentation. It describes perhaps one of the most important concepts about [mod_rewrite](../mod/mod%5Frewrite.html) - namely, when to avoid using it.

[mod_rewrite](../mod/mod%5Frewrite.html) should be considered a last resort, when other alternatives are found wanting. Using it when there are simpler alternatives leads to configurations which are confusing, fragile, and hard to maintain. Understanding what other alternatives are available is a very important step towards [mod_rewrite](../mod/mod%5Frewrite.html) mastery.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

The most common situation in which [mod_rewrite](../mod/mod%5Frewrite.html) is the right tool is when the very best solution requires access to the server configuration files, and you don't have that access. Some configuration directives are only available in the server configuration file. So if you are in a hosting situation where you only have .htaccess files to work with, you may need to resort to[mod_rewrite](../mod/mod%5Frewrite.html).

Simple Redirection

[mod_alias](../mod/mod%5Falias.html) provides the [Redirect](../mod/mod%5Falias.html#redirect) and [RedirectMatch](../mod/mod%5Falias.html#redirectmatch) directives, which provide a means to redirect one URL to another. This kind of simple redirection of one URL, or a class of URLs, to somewhere else, should be accomplished using these directives rather than [RewriteRule](../mod/mod%5Frewrite.html#rewriterule). RedirectMatchallows you to include a regular expression in your redirection criteria, providing many of the benefits of using RewriteRule.

A common use for RewriteRule is to redirect an entire class of URLs. For example, all URLs in the /one directory must be redirected to http://one.example.com/, or perhaps all http requests must be redirected tohttps.

These situations are better handled by the Redirectdirective. Remember that Redirect preserves path information. That is to say, a redirect for a URL /one will also redirect all URLs under that, such as /one/two.htmland /one/three/four.html.

To redirect URLs under /one tohttp://one.example.com, do the following:

Redirect "/one/" "http://one.example.com/"

To redirect one hostname to another, for exampleexample.com to www.example.com, see theCanonical Hostnamesrecipe.

To redirect http URLs to https, do the following:

<VirtualHost *:80> ServerName www.example.com Redirect "/" "https://www.example.com/"

<VirtualHost *:443> ServerName www.example.com # ... SSL configuration goes here

The use of RewriteRule to perform this task may be appropriate if there are other RewriteRule directives in the same scope. This is because, when there are Redirectand RewriteRule directives in the same scope, theRewriteRule directives will run first, regardless of the order of appearance in the configuration file.

In the case of the http-to-https redirection, the use ofRewriteRule would be appropriate if you don't have access to the main server configuration file, and are obliged to perform this task in a .htaccess file instead.

URL Aliasing

The [Alias](../mod/mod%5Falias.html#alias) directive provides mapping from a URI to a directory - usually a directory outside of your [DocumentRoot](../mod/core.html#documentroot). Although it is possible to perform this mapping with [mod_rewrite](../mod/mod%5Frewrite.html),[Alias](../mod/mod%5Falias.html#alias) is the preferred method, for reasons of simplicity and performance.

Using Alias

Alias "/cats" "/var/www/virtualhosts/felines/htdocs"

The use of [mod_rewrite](../mod/mod%5Frewrite.html) to perform this mapping may be appropriate when you do not have access to the server configuration files. Alias may only be used in server or virtualhost context, and not in a .htaccess file.

Symbolic links would be another way to accomplish the same thing, if you have Options FollowSymLinks enabled on your server.

Virtual Hosting

Although it is possible to handle virtual hosts with mod_rewrite, it is seldom the right way. Creating individual[<VirtualHost>](../mod/core.html#virtualhost) blocks is almost always the right way to go. In the event that you have an enormous number of virtual hosts, consider using[mod_vhost_alias](../mod/mod%5Fvhost%5Falias.html) to create these hosts automatically.

Modules such as [mod_macro](../mod/mod%5Fmacro.html) are also useful for creating a large number of virtual hosts dynamically.

Using [mod_rewrite](../mod/mod%5Frewrite.html) for vitualhost creation may be appropriate if you are using a hosting service that does not provide you access to the server configuration files, and you are therefore restricted to configuration using .htaccess files.

See the virtual hosts with mod_rewritedocument for more details on how you might accomplish this if it still seems like the right approach.

Simple Proxying

[RewriteRule](../mod/mod%5Frewrite.html#rewriterule) provides the [P] flag to pass rewritten URIs through[mod_proxy](../mod/mod%5Fproxy.html).

RewriteRule "^/?images(.*)" "http://imageserver.local/images$1" [P]

However, in many cases, when there is no actual pattern matching needed, as in the example shown above, the [ProxyPass](../mod/mod%5Fproxy.html#proxypass) directive is a better choice. The example here could be rendered as:

ProxyPass "/images/" "http://imageserver.local/images/"

Note that whether you use [RewriteRule](../mod/mod%5Frewrite.html#rewriterule) or [ProxyPass](../mod/mod%5Fproxy.html#proxypass), you'll still need to use the[ProxyPassReverse](../mod/mod%5Fproxy.html#proxypassreverse) directive to catch redirects issued from the back-end server:

ProxyPassReverse "/images/" "http://imageserver.local/images/"

You may need to use RewriteRule instead when there are other RewriteRules in effect in the same scope, as aRewriteRule will usually take effect before aProxyPass, and so may preempt what you're trying to accomplish.

Environment Variable Testing

[mod_rewrite](../mod/mod%5Frewrite.html) is frequently used to take a particular action based on the presence or absence of a particular environment variable or request header. This can be done more efficiently using the[<If>](../mod/core.html#if) directive.

Consider, for example, the common scenario whereRewriteRule is used to enforce a canonical hostname, such as www.example.com instead ofexample.com. This can be done using the [<If>](../mod/core.html#if) directive, as shown here:

<If "req('Host') != '" title="undefined" rel="noopener noreferrer">www.example.com'"> Redirect "/" "http://www.example.com/"

This technique can be used to take actions based on any request header, response header, or environment variable, replacing[mod_rewrite](../mod/mod%5Frewrite.html) in many common scenarios.

See especially the expression evaluation documentation for a overview of what types of expressions you can use in [<If>](../mod/core.html#if) sections, and in certain other directives.