Page Rules (Deprecated)

⚠️ Deprecation Notice

Page Rules are deprecated and will be removed in a future version. Please use Conditional Rules for all new rules.

Why switch?

  • No performance difference: Conditional Rules are just as fast as Page Rules

  • Better overview: All setting changes in one place instead of spread across two pages

  • Easier debugging: Page Rules used nginx-style location logic where only the "best" match won – this made it difficult to understand which rule was actually applied. Conditional Rules are evaluated transparently in position order, so you always know exactly what happened.

  • More flexibility: Conditional Rules additionally offer rich conditions (IP, country, headers, etc.)

Migration: To migrate a Page Rule, create a Conditional Rule with a URI condition. See the migration guide below.

What are Page Rules?

Page Rules allow you to override any smoxy configuration setting based on URL patterns. They're perfect for applying different caching strategies, image optimization levels, load balancing, or any other setting to specific sections of your site.

Key characteristics:

  • Execute third in the rule sequence (after Access Rules and Rewrite Rules)

  • URL-based matching only - simple and focused

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

  • First match wins, then stops - once a rule matches, no further Page Rules are evaluated

  • Can override any smoxy setting from your site configuration

Migration to Conditional Rules

Migrating from Page Rules to Conditional Rules is straightforward. Use the URI condition in Conditional Rules to achieve the same behavior.

Migration Example

Before (Page Rule):

Matcher: Matches Regex
URI: ^/admin
Settings:
- HTML Cache: Disabled

After (Conditional Rule):

Condition: URI matches "^/admin"
Settings:
- HTML Cache: Disabled

Important Differences to Note

Aspect
Page Rules
Conditional Rules

Execution

First match wins, stops

All matching rules apply

Stop behavior

Always (automatic)

Optional (stop=true)

Tip: If you want to preserve the "first match wins" behavior of Page Rules, add stop=true to your Conditional Rule.

Migration Checklist

  1. ✅ Create a new Conditional Rule with URI condition

  2. ✅ Copy over the same settings

  3. ✅ Add stop=true if you want to preserve Page Rule behavior

  4. ✅ Test the new rule with debug headers

  5. ✅ Delete the old Page Rule

Legacy Documentation

The following documentation is provided for existing Page Rules. For new rules, please use Conditional Rules.

How Page Rules Work

Page Rules are evaluated in ascending position order (1 → 2 → 3...) for every incoming request. When a rule's URL pattern matches, its settings are applied and evaluation stops.

Position-Based Evaluation

Request: /admin/dashboard
    ↓
Page Rule (Position 1) → Match /admin/*? → Apply Settings → STOP
    ↓ (no match)
Page Rule (Position 2) → Match /api/*? → NOT EVALUATED
    ↓ (no match)
Page Rule (Position 3) → Match /*? → NOT EVALUATED

Important: Once a Page Rule matches, no further Page Rules are evaluated. This is why order matters - more specific patterns should come before general ones.

URL Matching

Page Rules match based on URL patterns using three different matchers:

Matchers

Equals (=): Exact match

Matcher: Equals
URI: /myresource/data.php

Matches: /myresource/data.php
Doesn't match: /myresource/data.php/, /myresource/data.php?query=1

Matches Regex (~): Case-sensitive regex

Matcher: Matches Regex
URI: ^/exports

Matches: /exports, /exports/data, /exports/2024/file.csv
Doesn't match: /Exports (case-sensitive)

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

Matcher: Matches Regex Case-Insensitive
URI: ^/exports

Matches: /exports, /Exports, /EXPORTS, /ExPoRtS

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

Page Rules work with URIs (the path only).

Common Regex Patterns

^/admin          Starts with /admin
^/blog/          Exact path /blog/ or /blog/anything
\.php$           Ends with .php
\.(jpg|png|gif)$ Ends with .jpg, .png, or .gif
^/api/v[0-9]+    Matches /api/v1, /api/v2, etc.

Tip: Test your regex patterns using tools like regexr.com before applying them.

When to Use Page Rules

Use Page Rules When:

  • ✅ You need different settings for different URLs

  • ✅ Your logic is simple (just URL-based matching)

  • ✅ You want only one rule to apply (first match wins)

  • ✅ You're working with URL patterns that can be expressed with regex

Use Conditional Rules Instead When:

  • ❌ You need to match based on IPs, countries, headers, cookies, etc.

  • ❌ You want multiple rules to apply to the same request

  • ❌ You need complex AND/OR logic with multiple conditions

Settings: Override Any Configuration

Page Rules can override any setting from your site's configuration. This includes:

  • Routing: Choose different origins or load balancers

  • Caching: Control cache TTL, cache keys, cache tags, bypass cache

  • Image Optimization: AVIF, WebP, JPEG, PNG quality levels

  • Security: Enable/disable WAF, basic auth, custom error pages

  • Headers: Add, modify, or remove request/response headers

  • Optimization: HTML/JS/CSS minification

  • Advanced: Maintenance mode, debug headers, proxy timeouts

Simply select the settings you want to override when creating or editing a Page Rule. The available settings are grouped by category in the smoxy dashboard.

Use Cases & Examples

Example 1: Disable Caching for Admin Area

Scenario: Your admin panel should never be cached to ensure editors always see fresh content.

Position: 1
Matcher: Matches Regex
URI: ^/admin

Settings:
- HTML Cache: Disabled
- Image Cache: Disabled

Result: All URLs starting with /admin bypass caching

Why position 1? If you have a catch-all rule at position 1 (like /*), it would match first and your admin rule would never apply.

Example 2: High-Quality Images for Product Pages

Scenario: Product images need higher quality than the rest of your site.

Position: 2
Matcher: Matches Regex
URI: ^/products/

Settings:
- JPEG Quality: 90
- PNG Quality: 95
- WebP Quality: 90

Result: Product page images are served at higher quality

Example 3: Route API Traffic to Different Backend

Scenario: Your API endpoints should be served by a different server or load balancer group.

Position: 1
Matcher: Matches Regex
URI: ^/api/

Settings:
- Load Balancer: api-loadbalancer-group

Result: All API traffic is routed to your API servers

Combined with Conditional Rules: You could add a Conditional Rule to further customize API behavior based on authentication headers or client IPs.

Rule Order Best Practices

Since Page Rules stop on first match, order is critical:

1. Most Specific Before General

❌ Bad order:
Position 1: /* → Generic settings
Position 2: /admin/* → NEVER MATCHES

✅ Good order:
Position 1: /admin/super-secret → Most specific
Position 2: /admin/* → More specific  
Position 3: /* → Catch-all

2. Exact Matches Before Patterns

Position 1: = /special-page → Exact match
Position 2: ~ ^/special → Pattern match
Position 3: ~ ^/ → Broad pattern

3. Consider Rewrite Rules

Remember that Page Rules evaluate after Rewrite Rules. Match against the rewritten URL, not the original:

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

Uniqueness

Each site can only have one Page Rule per unique URL pattern. If you try to create a duplicate, you'll see: "The rule for this URI already exists."

This prevents conflicting rules and ensures predictable behavior.

Common Mistakes

❌ Catch-all rule at position 1

Position 1: /* → Catches everything
Position 2: /admin/* → Never evaluated

✅ Specific before general

Position 1: /admin/* → Specific rule
Position 2: /* → Catch-all

❌ Wrong matcher type

Matcher: Equals
URI: /blog/
→ Only matches /blog/, not /blog/post-1

✅ Use regex for patterns

Matcher: Matches Regex
URI: ^/blog/
→ Matches /blog/, /blog/post-1, /blog/category/tech

❌ Forgetting about rewrites

Rewrite Rule: /products/* → /shop/*
Page Rule: /products/* → Never matches

✅ Match rewritten URL

Rewrite Rule: /products/* → /shop/*
Page Rule: /shop/* → Matches after rewrite

❌ Case sensitivity issues

Matcher: Matches Regex (case-sensitive)
URI: ^/admin
→ Doesn't match /Admin or /ADMIN

✅ Use case-insensitive when needed

Matcher: Matches Regex Case-Insensitive
URI: ^/admin
→ Matches /admin, /Admin, /ADMIN

Page Rules vs Conditional Rules

When to choose Page Rules:

  • Simple URL-based logic

  • First match behavior is desired

  • You only need one rule to apply

When to choose Conditional Rules:

  • Need to match on IPs, headers, cookies, countries

  • Want multiple rules to stack/combine

  • Need AND/OR logic with multiple conditions

Can you use both? Yes! Page Rules execute first (position 3), then Conditional Rules (position 4). You can combine them:

Page Rule: /api/* → Set API load balancer
Conditional Rule: User-Agent = "mobile" → Enable mobile optimizations
→ Both can apply to /api/users from mobile device

Testing Page Rules

  1. Enable Debug Headers in your site configuration

  2. Make test requests to different URLs

  3. Check response headers to see which Page Rule matched

  4. Verify settings are being applied correctly

  5. Adjust positions if rules aren't matching as expected

Last updated

Was this helpful?