From 4660584114725dc9065410ed9d4d8dd54268193c Mon Sep 17 00:00:00 2001
From: Peter Amiri <peter@alurium.com>
Date: Fri, 9 Oct 2026 07:14:53 -0700
Subject: [PATCH] docs(router): note that constraint regexes use single
 backslashes in CFML
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A route `constraints` value is a plain CFML string that the router drops
into the route regex verbatim (`$patternToRegex` wraps each in a group).
CFML strings have no backslash escapes, so a digit class is written
`"\d{4}"`, not `"\\d{4}"` — a doubled backslash reaches the regex as a
literal backslash and the pattern never matches, so the route silently
falls through. Add a short caution to the "Constrain pattern
placeholders" section (the example there already uses the correct form).

Verified against the router source and the framework's own passing
route specs, which declare `constraints = {year = "\d{4}", ...}` and
compile to a `\d{4}` route regex that matches a numeric path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
---
 web/sites/guides/src/content/docs/v4-2-0/basics/routing.mdx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/web/sites/guides/src/content/docs/v4-2-0/basics/routing.mdx b/web/sites/guides/src/content/docs/v4-2-0/basics/routing.mdx
index 6ac720127d..bed010871f 100644
--- a/web/sites/guides/src/content/docs/v4-2-0/basics/routing.mdx
+++ b/web/sites/guides/src/content/docs/v4-2-0/basics/routing.mdx
@@ -145,6 +145,10 @@ mapper()
 
 With the constraint, `/posts/2026/04` matches and fills `params.year="2026"`, `params.month="04"`. `/posts/foo/bar` does not match — the router moves on to the next route. Without the constraint, `/posts/foo/bar` would match and `params.year="foo"`.
 
+<Aside type="caution" title="Write the pattern with a single backslash">
+A constraint value is a plain CFML string, and the router drops it into the route's regex verbatim. CFML strings have **no backslash escapes**, so a backslash in a constraint reaches the regex as-is: write a digit class as `"\d{4}"`, not `"\\d{4}"`. A doubled backslash is a *literal* backslash to the regex engine (`\\d` means "a backslash, then `d`"), so `"\\d{4}"` never matches a year and the route silently falls through. The same holds for `\w`, `\s`, `\.` and any other escape.
+</Aside>
+
 ## Route helpers
 
 Every route with a `name` is reachable by name from anywhere in your app. The helpers take the name, resolve it to a URL, and fill in placeholders from named arguments.