From 3460472feec244f4a2eb4436e2c93b6774ff384f 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 HTTP method override validation

Refs cakephp/cakephp#19669.
---
 docs/en/appendices/5-5-migration-guide.md |  7 +++++++
 docs/en/controllers/request-response.md   | 21 +++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/docs/en/appendices/5-5-migration-guide.md b/docs/en/appendices/5-5-migration-guide.md
index 067170a4d4..876001ce5c 100644
--- a/docs/en/appendices/5-5-migration-guide.md
+++ b/docs/en/appendices/5-5-migration-guide.md
@@ -33,6 +33,13 @@ bin/cake upgrade rector --rules cakephp55 <path/to/app/src>
   this method must add the optional parameter to their signature and pass it
   through when calling `parent::addDefaultTypes()`.
 
+### Http
+
+- HTTP method overrides from `_method` or `X-Http-Method-Override` are normalized
+  to uppercase. Invalid syntax and non-string values now raise
+  `BadRequestException` (HTTP 400). See
+  [HTTP Method Overrides](../controllers/request-response#http-method-overrides).
+
 ## Deprecations
 
 Coming soon
diff --git a/docs/en/controllers/request-response.md b/docs/en/controllers/request-response.md
index b0403d28a5..9435c44757 100644
--- a/docs/en/controllers/request-response.md
+++ b/docs/en/controllers/request-response.md
@@ -514,6 +514,27 @@ Returns the HTTP method the request was made with:
 echo $request->getMethod();
 ```
 
+### HTTP Method Overrides
+
+`ServerRequestFactory::fromGlobals()` supports a `_method` request-body field
+or an `X-Http-Method-Override` header to override the request method. The
+header takes precedence over the body field. `_method` is removed from the
+parsed body. Use
+`$request->getEnv('ORIGINAL_REQUEST_METHOD')` to read the original method.
+
+Override values are converted to uppercase and must contain letters A-Z,
+optionally separated by single hyphens or underscores. For example, `patch`,
+`VERSION-CONTROL` and `CUSTOM_METHOD` are accepted; digits, whitespace, repeated
+separators and array values are rejected.
+
+Invalid values throw `BadRequestException` with the message
+`Invalid HTTP method override.` and result in HTTP 400. This happens while
+building the request, before the middleware queue runs.
+
+::: info Added in version 5.5.0
+Validation and normalization of HTTP method overrides were added.
+:::
+
 ### Restricting HTTP Methods per Action
 
 `method` Cake\\Http\\ServerRequest::**allowMethod**(array|string $methods): bool