From aa8b9117f54ef643fbfdf33d25c0a6b951a2c145 Mon Sep 17 00:00:00 2001
From: Jasper Smet <josbeir@gmail.com>
Date: Sat, 24 Oct 2026 14:01:48 +0200
Subject: [PATCH] Document SQL expression string restrictions

Refs cakephp/cakephp#19726, cakephp/cakephp#19735.
---
 docs/en/orm/query-builder.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/en/orm/query-builder.md b/docs/en/orm/query-builder.md
index bfefcb020d..cd10388350 100644
--- a/docs/en/orm/query-builder.md
+++ b/docs/en/orm/query-builder.md
@@ -1536,6 +1536,10 @@ $query = $cities->find()
 # WHERE name COLLATE LIKE Latin1_general_CI_AI "%São José%"
 ```
 
+Collation names must be simple ASCII names; whitespace and hyphens are
+rejected with `InvalidArgumentException`. Choose collations from a fixed list
+in application code instead of accepting arbitrary user input.
+
 ### Automatically Creating IN Clauses
 
 When building queries using the ORM, you will generally not have to indicate the
@@ -2381,6 +2385,26 @@ by `AggregateExpresion`, but make sure you follow your database documentation on
   the current row that should be included in the aggregate function. This
   evaluates values based on the `orderBy()` field.
 
+String arguments for window partitioning, ordering and frame boundaries must
+be simple names or values. SQL fragments containing spaces or operators are
+rejected with `InvalidArgumentException`. Use an expression object for a
+trusted SQL fragment, for example an interval boundary:
+
+```php
+use Cake\Database\Expression\QueryExpression;
+use Cake\Database\Expression\WindowExpression;
+
+$window = (new WindowExpression())->range(
+    new QueryExpression("'1 day'"),
+    new QueryExpression("'10 days'"),
+);
+```
+
+Expression objects contain raw SQL. Construct these fragments from trusted
+application code, never directly from request data. The same restriction on
+simple names applies to function names passed to `FunctionExpression` and
+`AggregateExpression`.
+
 If you need to re-use the same window expression multiple times you can create
 named windows using the `window()` method: