feature #47595 [HttpFoundation] Extract request matchers for better reusability (fabpot)

This PR was merged into the 6.2 branch.

Discussion
----------

[HttpFoundation] Extract request matchers for better reusability

| Q             | A
| ------------- | ---
| Branch?       | 6.2
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | n/a <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT
| Doc PR        |

The `RequestMatcher` class hardcodes its matchers. This PR extracts those into their own classes so that we can compose a `RequestMatcher` and allow better reusability.

Commits
-------

6cfd3b707a [HttpFoundation] Extract request matchers for better reusability

Author: fabpot

CHANGELOG.md

@@ -6,6 +6,9 @@ CHANGELOG
 
  * The HTTP cache store uses the `xxh128` algorithm
  * Deprecate calling `JsonResponse::setCallback()`, `Response::setExpires/setLastModified/setEtag()`, `MockArraySessionStorage/NativeSessionStorage::setMetadataBag()`, `NativeSessionStorage::setSaveHandler()` without arguments
+ * Add request matchers under the `Symfony\Component\HttpFoundation\RequestMatcher` namespace
+ * Deprecate `RequestMatcher` in favor of `ChainRequestMatcher`
+ * Deprecate `Symfony\Component\HttpFoundation\ExpressionRequestMatcher` in favor of `Symfony\Component\HttpFoundation\RequestMatcher\ExpressionRequestMatcher`
 
 6.1
 ---

ChainRequestMatcher.php

@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation;
+
+/**
+ * ChainRequestMatcher verifies that all checks match against a Request instance.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class ChainRequestMatcher implements RequestMatcherInterface
+{
+    /**
+     * @param iterable<RequestMatcherInterface> $matchers
+     */
+    public function __construct(private iterable $matchers)
+    {
+    }
+
+    public function matches(Request $request): bool
+    {
+        foreach ($this->matchers as $matcher) {
+            if (!$matcher->matches($request)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

ExpressionRequestMatcher.php

@@ -13,11 +13,16 @@
 
 use Symfony\Component\ExpressionLanguage\Expression;
 use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
+use Symfony\Component\HttpFoundation\RequestMatcher\ExpressionRequestMatcher as NewExpressionRequestMatcher;
+
+trigger_deprecation('symfony/http-foundation', '6.2', 'The "%s" class is deprecated, use "%s" instead.', ExpressionRequestMatcher::class, NewExpressionRequestMatcher::class);
 
 /**
  * ExpressionRequestMatcher uses an expression to match a Request.
  *
  * @author Fabien Potencier <[email protected]>
+ *
+ * @deprecated since Symfony 6.2, use "Symfony\Component\HttpFoundation\RequestMatcher\ExpressionRequestMatcher" instead
  */
 class ExpressionRequestMatcher extends RequestMatcher
 {

RequestMatcher.php

@@ -11,10 +11,14 @@
 
 namespace Symfony\Component\HttpFoundation;
 
+trigger_deprecation('symfony/http-foundation', '6.2', 'The "%s" class is deprecated, use "%s" instead.', RequestMatcher::class, ChainRequestMatcher::class);
+
 /**
  * RequestMatcher compares a pre-defined set of checks against a Request instance.
  *
  * @author Fabien Potencier <[email protected]>
+ *
+ * @deprecated since Symfony 6.2, use ChainRequestMatcher instead
  */
 class RequestMatcher implements RequestMatcherInterface
 {

RequestMatcher/AttributesRequestMatcher.php

@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * Checks the Request attributes matches all regular expressions.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class AttributesRequestMatcher implements RequestMatcherInterface
+{
+    /**
+     * @param array<string, string> $regexps
+     */
+    public function __construct(private array $regexps)
+    {
+    }
+
+    public function matches(Request $request): bool
+    {
+        foreach ($this->regexps as $key => $regexp) {
+            $attribute = $request->attributes->get($key);
+            if (!\is_string($attribute)) {
+                return false;
+            }
+            if (!preg_match('{'.$regexp.'}', $attribute)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

RequestMatcher/ExpressionRequestMatcher.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\ExpressionLanguage\Expression;
+use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * ExpressionRequestMatcher uses an expression to match a Request.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class ExpressionRequestMatcher implements RequestMatcherInterface
+{
+    public function __construct(
+        private ExpressionLanguage $language,
+        private Expression|string $expression,
+    ) {
+    }
+
+    public function matches(Request $request): bool
+    {
+        return $this->language->evaluate($this->expression, [
+            'request' => $request,
+            'method' => $request->getMethod(),
+            'path' => rawurldecode($request->getPathInfo()),
+            'host' => $request->getHost(),
+            'ip' => $request->getClientIp(),
+            'attributes' => $request->attributes->all(),
+        ]);
+    }
+}

RequestMatcher/HostRequestMatcher.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * Checks the Request URL host name matches a regular expression.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class HostRequestMatcher implements RequestMatcherInterface
+{
+    public function __construct(private string $regexp)
+    {
+    }
+
+    public function matches(Request $request): bool
+    {
+        return preg_match('{'.$this->regexp.'}i', $request->getHost());
+    }
+}

RequestMatcher/IpsRequestMatcher.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\HttpFoundation\IpUtils;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * Checks the client IP of a Request.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class IpsRequestMatcher implements RequestMatcherInterface
+{
+    private array $ips;
+
+    /**
+     * @param string[]|string $ips A specific IP address or a range specified using IP/netmask like 192.168.1.0/24
+     *                             Strings can contain a comma-delimited list of IPs/ranges
+     */
+    public function __construct(array|string $ips)
+    {
+        $this->ips = array_reduce((array) $ips, static function (array $ips, string $ip) {
+            return array_merge($ips, preg_split('/\s*,\s*/', $ip));
+        }, []);
+    }
+
+    public function matches(Request $request): bool
+    {
+        if (!$this->ips) {
+            return true;
+        }
+
+        return IpUtils::checkIp($request->getClientIp() ?? '', $this->ips);
+    }
+}

RequestMatcher/IsJsonRequestMatcher.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * Checks the Request content is valid JSON.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class IsJsonRequestMatcher implements RequestMatcherInterface
+{
+    public function matches(Request $request): bool
+    {
+        try {
+            json_decode($request->getContent(), true, 512, \JSON_BIGINT_AS_STRING | \JSON_THROW_ON_ERROR);
+        } catch (\JsonException) {
+            return false;
+        }
+
+        return true;
+    }
+}

RequestMatcher/MethodRequestMatcher.php

@@ -0,0 +1,48 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * Checks the HTTP method of a Request.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class MethodRequestMatcher implements RequestMatcherInterface
+{
+    /**
+     * @var string[]
+     */
+    private array $methods = [];
+
+    /**
+     * @param string[]|string $methods An HTTP method or an array of HTTP methods
+     *                                 Strings can contain a comma-delimited list of methods
+     */
+    public function __construct(array|string $methods)
+    {
+        $this->methods = array_reduce(array_map('strtoupper', (array) $methods), static function (array $methods, string $method) {
+            return array_merge($methods, preg_split('/\s*,\s*/', $method));
+        }, []);
+    }
+
+    public function matches(Request $request): bool
+    {
+        if (!$this->methods) {
+            return true;
+        }
+
+        return \in_array($request->getMethod(), $this->methods, true);
+    }
+}

RequestMatcher/PathRequestMatcher.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\RequestMatcher;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcherInterface;
+
+/**
+ * Checks the Request URL path info matches a regular expression.
+ *
+ * @author Fabien Potencier <[email protected]>
+ */
+class PathRequestMatcher implements RequestMatcherInterface
+{
+    public function __construct(private string $regexp)
+    {
+    }
+
+    public function matches(Request $request): bool
+    {
+        return preg_match('{'.$this->regexp.'}', rawurldecode($request->getPathInfo()));
+    }
+}