feature #61979 [HttpFoundation] Add Request::set/getAllowedHttpMethodOverride() to list which HTTP methods can be overridden (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[HttpFoundation] Add `Request::set/getAllowedHttpMethodOverride()` to list which HTTP methods can be overridden

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

This feature addresses https://github.com/symfony/symfony/pull/61949/files#r2402280654 and hardens HttpFoundation by giving control over which HTTP methods can be overridden:

```php
Request::setAllowedHttpMethodOverride(['PUT', 'PATCH', 'DELETE']);
```

Providing no method disables verb tunneling altogether:
```php
Request::setAllowedHttpMethodOverride([]);
```

This setting can be set using standard Symfony configuration:
```yaml
framework:
    allowed_http_method_override: ['PUT', 'DELETE', 'PATCH']
```

2 implementations note:
- This doesn't update the XSD file on purpose: that format is deprecated and handling it would mean adding more complexity that nobody will benefit from in practice.
- This isn't compatible with defining the list of allowed methods using env vars. This could be added later if one has a use case for that. Until it happens, I prefer keeping the code simpler.

Commits
-------

a4f51c9548c [HttpFoundation] Add `Request::$allowedHttpMethodOverride` to list which HTTP methods can be overridden

Author: fabpot

CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
  * Add `#[WithHttpStatus]` to define status codes: 404 for `SignedUriException` and 403 for `ExpiredSignedUriException`
  * Add support for the `QUERY` HTTP method
  * Add support for structured MIME suffix
+ * Add `Request::set/getAllowedHttpMethodOverride()` to list which HTTP methods can be overridden
  * Deprecate using `Request::sendHeaders()` after headers have already been sent; use a `StreamedResponse` instead
  * Deprecate method `Request::get()`, use properties `->attributes`, `query` or `request` directly instead
  * Make `Request::createFromGlobals()` parse the body of PUT, DELETE, PATCH and QUERY requests

Request.php

@@ -81,6 +81,13 @@ class Request
 
     protected static bool $httpMethodParameterOverride = false;
 
+    /**
+     * The HTTP methods that can be overridden.
+     *
+     * @var uppercase-string[]|null
+     */
+    protected static ?array $allowedHttpMethodOverride = null;
+
     /**
      * Custom parameters.
      */
@@ -680,6 +687,30 @@ public static function getHttpMethodParameterOverride(): bool
         return self::$httpMethodParameterOverride;
     }
 
+    /**
+     * Sets the list of HTTP methods that can be overridden.
+     *
+     * Set to null to allow all methods to be overridden (default). Set to an
+     * empty array to disallow overrides entirely. Otherwise, provide the list
+     * of uppercased method names that are allowed.
+     *
+     * @param uppercase-string[]|null $methods
+     */
+    public static function setAllowedHttpMethodOverride(?array $methods): void
+    {
+        self::$allowedHttpMethodOverride = $methods;
+    }
+
+    /**
+     * Gets the list of HTTP methods that can be overridden.
+     *
+     * @return uppercase-string[]|null
+     */
+    public static function getAllowedHttpMethodOverride(): ?array
+    {
+        return self::$allowedHttpMethodOverride;
+    }
+
     /**
      * Gets a "parameter" value from any bag.
      *
@@ -1197,7 +1228,7 @@ public function getMethod(): string
 
         $this->method = strtoupper($this->server->get('REQUEST_METHOD', 'GET'));
 
-        if ('POST' !== $this->method) {
+        if ('POST' !== $this->method || !(self::$allowedHttpMethodOverride ?? true)) {
             return $this->method;
         }
 
@@ -1213,11 +1244,11 @@ public function getMethod(): string
 
         $method = strtoupper($method);
 
-        if (\in_array($method, ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'PATCH', 'PURGE', 'TRACE', 'QUERY'], true)) {
-            return $this->method = $method;
+        if (self::$allowedHttpMethodOverride && !\in_array($method, self::$allowedHttpMethodOverride, true)) {
+            return $this->method;
         }
 
-        if (!preg_match('/^[A-Z]++$/D', $method)) {
+        if (\strlen($method) !== strspn($method, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')) {
             throw new SuspiciousOperationException('Invalid HTTP method override.');
         }
 

Tests/RequestTest.php

@@ -33,6 +33,7 @@ protected function tearDown(): void
     {
         Request::setTrustedProxies([], -1);
         Request::setTrustedHosts([]);
+        Request::setAllowedHttpMethodOverride(null);
     }
 
     public function testInitialize()
@@ -255,6 +256,50 @@ public function testCreate()
         $this->assertEquals('http://test.com/foo', $request->getUri());
     }
 
+    public function testHttpMethodOverrideRespectsAllowedListWithHeader()
+    {
+        $request = Request::create('http://example.com/', 'POST');
+        $request->headers->set('X-HTTP-METHOD-OVERRIDE', 'PATCH');
+
+        Request::setAllowedHttpMethodOverride(['PUT', 'PATCH']);
+
+        $this->assertSame('PATCH', $request->getMethod());
+    }
+
+    public function testHttpMethodOverrideDisallowedSkipsOverrideWithHeader()
+    {
+        $request = Request::create('http://example.com/', 'POST');
+        $request->headers->set('X-HTTP-METHOD-OVERRIDE', 'DELETE');
+
+        Request::setAllowedHttpMethodOverride(['PUT', 'PATCH']);
+
+        $this->assertSame('POST', $request->getMethod());
+    }
+
+    public function testHttpMethodOverrideDisabledWithEmptyAllowedList()
+    {
+        $request = Request::create('http://example.com/', 'POST');
+        $request->headers->set('X-HTTP-METHOD-OVERRIDE', 'PUT');
+
+        Request::setAllowedHttpMethodOverride([]);
+
+        $this->assertSame('POST', $request->getMethod());
+    }
+
+    public function testHttpMethodOverrideRespectsAllowedListWithParameter()
+    {
+        Request::enableHttpMethodParameterOverride();
+        Request::setAllowedHttpMethodOverride(['PUT']);
+
+        try {
+            $request = Request::create('http://example.com/', 'POST', ['_method' => 'PUT']);
+
+            $this->assertSame('PUT', $request->getMethod());
+        } finally {
+            (new \ReflectionProperty(Request::class, 'httpMethodParameterOverride'))->setValue(null, false);
+        }
+    }
+
     public function testCreateWithRequestUri()
     {
         $request = Request::create('http://test.com:80/foo');