Rewrite Rules

Rewrite Rules allow you to transform incoming URLs before any other processing happens. They work like nginx rewrite rules, enabling URL normalization, legacy URL support, and clean URL structures.

What are Rewrite Rules?

Rewrite Rules modify the request URL based on pattern matching. They're evaluated early in the request flow, right after Access Rules and before Page Rules, ensuring that URL transformations happen before configuration rules evaluate the URL.

Key characteristics:

• Execute second in the rule sequence (after Access Rules, before Page and Conditional Rules)

• Transform URLs before cache lookup

• nginx-style URL rewriting

• Evaluated in position order (1, 2, 3...)

• Stop after first match - once a rule matches, no further Rewrite Rules are evaluated

How Rewrite Rules Work

Rewrite Rules are evaluated in ascending position order (1 → 2 → 3...) for every incoming request. When a rule's URL pattern matches, the URL is rewritten to the target path and evaluation stops.

Position-Based Evaluation

Request: /old-path
    ↓
Rewrite Rule (Position 1) → Match /old-path? → Rewrite to /new-path → STOP
    ↓ (no match)
Rewrite Rule (Position 2) → Match? → Rewrite → STOP
    ↓ (no match)
Continue to Page Rules with original or rewritten URL...

Important: Once a Rewrite Rule matches, no further Rewrite Rules are evaluated. The rewritten URL is then used by all subsequent rules (Page Rules, Conditional Rules).

URL Matching

Rewrite Rules use the same URL matching system as Page Rules. You can match URLs using three different matchers:

Matchers

Equals (=): Exact match

Matcher: Equals
URL: /old-page
Target: /new-page

Matches: /old-page
Doesn't match: /old-page/, /old-page?query=1, /old-page-extra

Matches Regex (~): Case-sensitive regex

Matcher: Matches Regex
URL: ^/blog/(\d+)
Target: /articles/$1

Matches: /blog/123 → /articles/123
Doesn't match: /BLOG/123 (case-sensitive)

Matches Regex Case-Insensitive (~*): Case-insensitive regex

Matcher: Matches Regex Case-Insensitive
URL: ^/products/(.*)
Target: /shop/$1

Matches: /products/item → /shop/item
Also matches: /PRODUCTS/item → /shop/item

URL vs URI

• URL: The complete web address including protocol and domain

  • Example: https://www.example.com/category/data.html

• URI: Just the path without domain or protocol

  • Example: /category/data.html

Rewrite Rules work with URIs (the path only).

When to Use Rewrite Rules

Use Rewrite Rules When:

• ✅ You need to support legacy URLs while restructuring your site

• ✅ You want clean, SEO-friendly URLs (e.g., /product/123 instead of /product.php?id=123)

• ✅ You're migrating from another platform and need to maintain old URL structures

• ✅ You need URL normalization (e.g., remove trailing slashes, lowercase URLs)

• ✅ URL transformations should happen before other rules evaluate

Use Cases & Examples

Example 1: Legacy URL Support

Scenario: You've restructured your site from /old-section/page.html to /new-section/page, but need to support old links.

Position: 1
Matcher: Matches Regex
URL: ^/old-section/(.*)\.html$
Target: /new-section/$1

Result:
/old-section/about.html → /new-section/about
/old-section/contact.html → /new-section/contact

Why rewrite instead of redirect? Rewrites are transparent - the user doesn't see the URL change, and you maintain the original request context. Page Rules can then apply configurations based on the new URL.

Example 2: Clean URL Structure

Scenario: Your application uses query parameters, but you want clean URLs for SEO.

Position: 1
Matcher: Matches Regex
URL: ^/product/([0-9]+)$
Target: /product.php?id=$1

Result:
/product/12345 → /product.php?id=12345
(Clean URL is rewritten to actual backend URL)

Why this works: Users and search engines see clean URLs (/product/12345), but your backend receives the query parameter format it expects.

Example 3: Platform Migration

Scenario: Migrating from WordPress to a new platform and need to support old post URLs.

Position: 1
Matcher: Matches Regex
URL: ^/([0-9]{4})/([0-9]{2})/(.*)$
Target: /posts/$1-$2-$3

Result:
/2024/03/my-blog-post → /posts/2024-03-my-blog-post
/2023/12/another-post → /posts/2023-12-another-post

Combined with Page Rules: After the rewrite, a Page Rule matching /posts/* can apply specific caching or optimization settings.

Target Path

The Target Path is where the URL gets rewritten to. It can be:

• Static path: /new-location

• With capture groups: /section/$1 (uses regex capture groups from the URL pattern)

• Multiple captures: /category/$1/item/$2

Important: The target path is the actual backend path your application will receive. Make sure it's a valid path your application can handle.

Rule Order Best Practices

Since Rewrite Rules stop on first match, order them carefully:

1. Most Specific First

Position 1: /exact/specific/path → /target1
Position 2: /specific/* → /target2
Position 3: /* → /target3

2. Exact Matches Before Patterns

Position 1: = /special-page → /new-special
Position 2: ~ ^/special → /regular-special

3. Consider Downstream Rules

Remember that Page Rules and Conditional Rules will evaluate against the rewritten URL, not the original:

Rewrite Rule: /old/* → /new/*
Page Rule: Match /new/* (not /old/*)

4. Consolidate Similar Patterns

Use regex to handle multiple cases efficiently:

❌ Less efficient (multiple rules):
/old-about → /about
/old-contact → /contact
/old-help → /help

✅ More efficient (single rule):
^/old-(.*)$ → /$1

Use regex for flexibility:

❌ Multiple specific rules:
/product-1 → /item/1
/product-2 → /item/2
...

✅ Single flexible rule:
^/product-([0-9]+)$ → /item/$1

Uniqueness

Each site must have unique:

• Rule names - each rule must have a unique name

• URL patterns - you cannot have duplicate URL patterns

If you try to create a duplicate, you'll see: "Name already exists" or "Same matcher exists."

Common Mistakes

❌ Catch-all rewrite at position 1

Position 1: ~ ^/(.*)$ → /new/$1
→ Rewrites EVERYTHING, other rules never match

✅ Specific patterns first

Position 1: = /special → /new-special
Position 2: ~ ^/blog/(.*)$ → /articles/$1
Position 3: ~ ^/old-(.*)$ → /$1

---

❌ Forgetting about Page Rules

Rewrite Rule: /old-admin → /admin
Page Rule: Match /old-admin/* → NEVER MATCHES
Should match: /admin/*

✅ Page Rules match rewritten URLs

Rewrite Rule: /old-admin → /admin
Page Rule: Match /admin/* → Matches after rewrite

---

❌ Invalid target path

URL: ^/product/(.*)$
Target: /invalid/$2 (capture group $2 doesn't exist)
→ Broken rewrite

✅ Valid capture groups

URL: ^/product/(.*)$
Target: /item/$1 (uses capture group $1)

Testing Rewrite Rules

1. Enable Debug Headers in your site configuration

2. Make test requests with the original URLs

3. Check response headers to see which rules were applied and what the URL became

4. Verify Page Rules are matching the rewritten URL, not the original