Managing URL Transitions with Apache mod_rewrite

The Problem: Brittle URLs and SEO Decay

When a website evolves, its URL structure often changes. Moving from a directory-based structure (/products/category/item) to a flat structure (/item) or changing file extensions (.php to no extension) usually results in broken links and a loss of search engine rankings. The challenge is mapping these legacy paths to new locations without forcing the user to manually update their bookmarks or causing a 404 error.

The solution is mod_rewrite, an Apache module that uses regular expressions to map an incoming request URL to a different destination. By distinguishing between external redirects (telling the browser to go elsewhere) and internal rewrites (changing the path behind the scenes), you can maintain a clean public API for your URLs while keeping your server's file structure organized.

Internal Rewrites vs. External Redirects

Understanding the difference between these two operations is the most critical part of configuring mod_rewrite. If you use the wrong one, you either confuse the user or fail to tell search engines that a page has moved.

External Redirects (The [R] Flag)

An external redirect sends an HTTP response code (like 301 for permanent or 302 for temporary) back to the client. The browser's address bar updates to the new URL. This is essential for SEO when a page has permanently moved, as it transfers the "link juice" to the new destination.

Internal Rewrites (The Default)

An internal rewrite happens entirely on the server. The server sees a request for /profile/username, but internally fetches the content from /user_profile.php?id=username. The user still sees /profile/username in their browser. This creates "pretty URLs" that are easier for humans to read and share.

Implementing a Clean URL Structure

To use these features, mod_rewrite must be enabled. On Debian-based systems, run the following as root or via sudo:

a2enmod rewrite
systemctl restart apache2

Once enabled, you can define rules in your main server configuration or a .htaccess file. Below is a practical example of converting a legacy query-string URL into a clean, SEO-friendly path.

Example: Mapping Product IDs to Slugs

Assume you have a legacy system that uses /product.php?id=123, but you want the public URL to be /product/123.

# Enable the rewrite engine
RewriteEngine On

# 1. External Redirect: Force old .php links to the new clean path
# This prevents duplicate content issues in search engines
RewriteCond %{THE_REQUEST} /product\.php\?id=([0-9]+)
RewriteRule ^product\.php$ /product/%1 [R=301,L]

# 2. Internal Rewrite: Map the clean path back to the actual file
# The server handles this internally; the user sees /product/123
RewriteRule ^product/([0-9]+)$ product.php?id=$1 [L]

Breakdown of the logic:

• RewriteCond %{THE_REQUEST}: Checks the raw HTTP request line to avoid infinite loops when the internal rewrite happens.
• ([0-9]+): A regular expression capturing group that matches one or more digits.
• %1 and $1: These reference the captured digits from the condition and the rule, respectively.
• [L]: The "Last" flag, telling Apache to stop processing further rules if this one matches.

Verification and Risks

The most common failure in mod_rewrite is the infinite rewrite loop, which triggers a 500 Internal Server Error. This happens when a rule rewrites a URL to a path that then matches the same rule again, repeating indefinitely.

To verify your rules without risking a production crash, use curl to check the HTTP headers. Run this from your terminal:

curl -I http://yourdomain.com/product.php?id=123

Expected Result: You should see HTTP/1.1 301 Moved Permanently and a Location: /product/123 header. If you request /product/123, you should see HTTP/1.1 200 OK.

Performance Trade-offs

While powerful, mod_rewrite is more computationally expensive than simple Alias or Redirect directives because it must evaluate regular expressions for every incoming request. For simple one-to-one path changes, use Redirect 301 /old /new. Reserve mod_rewrite for complex patterns or internal mapping.

Rollback Procedure

If a change causes a 500 error or unexpected redirects, the fastest way to recover is to comment out the RewriteEngine On line or rename the .htaccess file to .htaccess.bak. This immediately disables all rewrite logic and restores the server to its default routing behavior.