Merge pull request #6995 from kenjis/feat-request-is

feat: add IncomingRequest::is() method

Author: kenjis

system/HTTP/CLIRequest.php

@@ -304,4 +304,15 @@ public function getLocale(): string
     {
         return Locale::getDefault();
     }
+
+    /**
+     * Checks this request type.
+     *
+     * @param string $type HTTP verb or 'json' or 'ajax'
+     * @phpstan-param string|'get'|'post'|'put'|'delete'|'head'|'patch'|'options'|'json'|'ajax' $type
+     */
+    public function is(string $type): bool
+    {
+        return false;
+    }
 }

system/HTTP/IncomingRequest.php

@@ -375,6 +375,33 @@ public function negotiate(string $type, array $supported, bool $strictMatch = fa
         throw HTTPException::forInvalidNegotiationType($type);
     }
 
+    /**
+     * Checks this request type.
+     *
+     * @param string $type HTTP verb or 'json' or 'ajax'
+     * @phpstan-param string|'get'|'post'|'put'|'delete'|'head'|'patch'|'options'|'json'|'ajax' $type
+     */
+    public function is(string $type): bool
+    {
+        $valueUpper = strtoupper($type);
+
+        $httpMethods = ['GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'PATCH', 'OPTIONS'];
+
+        if (in_array($valueUpper, $httpMethods, true)) {
+            return strtoupper($this->getMethod()) === $valueUpper;
+        }
+
+        if ($valueUpper === 'JSON') {
+            return strpos($this->getHeaderLine('Content-Type'), 'application/json') !== false;
+        }
+
+        if ($valueUpper === 'AJAX') {
+            return $this->isAJAX();
+        }
+
+        throw new InvalidArgumentException('Unknown type: ' . $type);
+    }
+
     /**
      * Determines if this request was made from the command line (CLI).
      */

tests/system/HTTP/CLIRequestTest.php

@@ -625,4 +625,9 @@ public function testGetCookie()
 
         $this->assertSame($this->request->getCookie(), []);
     }
+
+    public function testIs()
+    {
+        $this->assertFalse($this->request->is('get'));
+    }
 }

tests/system/HTTP/IncomingRequestTest.php

@@ -16,6 +16,8 @@
 use CodeIgniter\HTTP\Files\UploadedFile;
 use CodeIgniter\Test\CIUnitTestCase;
 use Config\App;
+use Generator;
+use InvalidArgumentException;
 use TypeError;
 
 /**
@@ -615,6 +617,63 @@ public function testCanGrabGetRawInputVar($rawstring, $var, $expected, $filter,
         $this->assertSame($expected, $request->getRawInputVar($var, $filter, $flag));
     }
 
+    /**
+     * @dataProvider provideIsHTTPMethods
+     */
+    public function testIsHTTPMethodLowerCase(string $value)
+    {
+        $request = $this->request->withMethod($value);
+
+        $this->assertTrue($request->is(strtolower($value)));
+    }
+
+    public function provideIsHTTPMethods(): Generator
+    {
+        yield from [
+            ['GET'],
+            ['POST'],
+            ['PUT'],
+            ['DELETE'],
+            ['HEAD'],
+            ['PATCH'],
+            ['OPTIONS'],
+        ];
+    }
+
+    /**
+     * @dataProvider provideIsHTTPMethods
+     */
+    public function testIsHTTPMethodUpperCase(string $value)
+    {
+        $request = $this->request->withMethod($value);
+
+        $this->assertTrue($request->is($value));
+    }
+
+    public function testIsInvalidValue()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown type: invalid');
+
+        $request = $this->request->withMethod('GET');
+
+        $request->is('invalid');
+    }
+
+    public function testIsJson()
+    {
+        $request = $this->request->setHeader('Content-Type', 'application/json');
+
+        $this->assertTrue($request->is('json'));
+    }
+
+    public function testIsWithAjax()
+    {
+        $request = $this->request->setHeader('X-Requested-With', 'XMLHttpRequest');
+
+        $this->assertTrue($request->is('ajax'));
+    }
+
     public function testIsCLI()
     {
         $this->assertFalse($this->request->isCLI());

user_guide_src/source/changelogs/v4.3.0.rst

@@ -323,6 +323,8 @@ Others
 - **Config:** Added ``Config\Session`` class to handle session configuration.
 - **Debug:** Kint has been updated to 5.0.1.
 - **Request:** Added new ``$request->getRawInputVar()`` method to return a specified variable from raw stream. See :ref:`Retrieving Raw data <incomingrequest-retrieving-raw-data>`.
+- **Request:** Added new ``$request->is()`` method to query the request type.
+  See :ref:`Determining Request Type <incomingrequest-is>`.
 
 Message Changes
 ***************

user_guide_src/source/incoming/incomingrequest.rst

@@ -40,6 +40,20 @@ be checked with the ``isAJAX()`` and ``isCLI()`` methods:
     which in some cases is not sent by default in XHR requests via JavaScript (i.e., fetch).
     See the :doc:`AJAX Requests </general/ajax>` section on how to avoid this problem.
 
+.. _incomingrequest-is:
+
+is()
+====
+
+    .. versionadded:: 4.3.0
+
+Since v4.3.0, you can use the ``is()`` method. It returns boolean.
+
+.. literalinclude:: incomingrequest/040.php
+
+getMethod()
+===========
+
 You can check the HTTP method that this request represents with the ``getMethod()`` method:
 
 .. literalinclude:: incomingrequest/005.php

user_guide_src/source/incoming/incomingrequest/040.php

@@ -0,0 +1,16 @@
+<?php
+
+// Checks HTTP methods. Returns boolean.
+$request->is('get');
+$request->is('post');
+$request->is('put');
+$request->is('delete');
+$request->is('head');
+$request->is('patch');
+$request->is('options');
+
+// Checks if it is an AJAX request. The same as `$request->isAJAX()`.
+$request->is('ajax');
+
+// Checks if it is a JSON request.
+$request->is('json');