URL rewriting

URL rewriting is useful when your application expects “pretty URLs” that map to a single entry script (common in PHP CMS/framework stacks). It is also useful when you need to preserve old URL structures after migrations.

Ferron applies rewrites in the request pipeline, before proxying or static file serving, so later stages use the rewritten URL. Rewrites do not trigger a new round of location matching. Ferron selects the location block once, on the original URL. The client sees no redirect, meaning the rewrite is transparent.

For many applications behind reverse proxy, rewriting is not required. Those apps usually handle routing themselves, and Ferron only forwards requests with proxy (often using location blocks).

Single-page application fallback⁠#

A common pattern is rewriting unknown routes to / so client-side routing works:

example.com {
    root /var/www/html
    rewrite "^/.*" "/" {
        last
        directory false
        file false
    }
}

This preserves real files (for example /assets/app.js) while routing non-file paths (for example /dashboard/settings) to your SPA entry point.

PHP front-controller pattern⁠#

Many PHP applications route requests through index.php:

example.com {
    root /var/www/app/public
    rewrite "^/(.*)" "/index.php/$1" {
        file false
        directory false
        last
    }
}

CMS/framework setups commonly use this pattern where the app resolves routes internally.

Legacy URL migration⁠#

To keep old URLs working after restructuring paths:

example.com {
    root /var/www/html
    rewrite "^/old-path/(.*)" "/new-path/$1" {
        last
    }
    rewrite "^/blog/([^/]+)/?(?:$|[?#])" "/blog.php?slug=$1" {
        last
    }
}

Clean URLs without .html for static files⁠#

To serve clean URLs (without .html) for static files, you can use a regex pattern that matches any path except those ending with .html:

example.com {
    root /var/www/html

    # Rewrite /test?a=b&c=d -> /test.html?a=b&c=d
    rewrite "^/([^?#]*[^?#/])($|[?#].*)" "/$1.html$2" {
        file false
    }

    # Redirect /test/?a=b&c=d -> /test?a=b&c=d
    status 301 {
        regex "^/([^?#]*[^?#/])/($|[?#].*)"
        location /$1$2
    }
}

This is useful when serving websites generated with a static site generator (SSG) such as Jekyll, Hugo, or Astro.

Chained rules without last⁠#

Without last true, multiple rewrite rules can chain together:

example.com {
    rewrite "^/legacy/(.*)" "/modern/$1"
    rewrite "^/modern/(.*)" "/current/$1"
}

The first rule rewrites a request to /legacy/foo to /modern/foo. Then the second rule rewrites it to /current/foo.