Request handler patch.

Changelog excerpt:
- The request handler can now handle custom methods.

Changelog.txt

@@ -21,6 +21,8 @@ found at:
   keys is defined. Accordingly, that's been done, and a new method added for
   that purpose (CIDRAM/CIDRAM#547).
 
+- [2023.12.24; Maikuolan]: The request handler can now handle custom methods.
+
 === Version/Release 1.10.0 ===
 MINOR RELEASE.
 

_docs/Request.md

@@ -121,7 +121,7 @@ public $MostRecentStatusCode = 0;
 The main request method (this is what you'll want to use to actually perform a request).
 
 ```PHP
-public function request(string $URI, $Params = [], int $Timeout = -1, array $Headers = [], int $Depth = 0): string;
+public function request(string $URI, $Params = [], int $Timeout = -1, array $Headers = [], int $Depth = 0, string $Method = ''): string;
 ```
 
 The first parameter (`$URI`) is the URL, URI, resource, etc that you want to request.
@@ -132,14 +132,16 @@ The third parameter (`$Timeout`) is an optional timeout limit for the request. W
 
 The fourth parameter (`$Headers`) is an optional array of headers to send with the request.
 
-The fifth parameter (`$Depth`) represents the recursion depth of the current request instance, is populated automatically by `request`, and shouldn't ever be populated manually by the implementation.
+The fifth parameter (`$Depth`) represents the recursion depth of the current request instance, is populated automatically by `request`, and shouldn't be populated manually by the implementation (other than when needing access to the sixth parameter).
+
+The sixth parameter (`$Method`) can be used to specify the intended request method in the event that the method intended isn't GET or POST. When the intended request method is GET or POST, it shouldn't be populated manually by the implementation (the method will determine automatically whether GET or POST is needed, based on factors like request parameters). This can be useful when methods such as CONNECT or DELETE are needed.
 
 The method returns a string (either the returned resource, or an empty string on failure).
 
 The class also implements the magic method `__invoke`, as a way to alias back to `request` when the instance is utilised as a callable or function.
 
 ```PHP
-public function __invoke($URI, $Params = [], $Timeout = -1, array $Headers = [], $Depth = 0);
+public function __invoke(...$Params): string;
 ```
 
 #### inCsv method.
@@ -161,4 +163,4 @@ public function sendMessage(string $Message): void;
 ---
 
 
-Last Updated: 24 March 2023 (2023.03.24).
+Last Updated: 24 December 2023 (2023.12.24).

src/Request.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Request handler (last modified: 2023.11.22).
+ * Request handler (last modified: 2023.12.24).
  *
  * This file is a part of the "common classes package", utilised by a number of
  * packages and projects, including CIDRAM and phpMussel.
@@ -71,7 +71,7 @@ class Request
      *
      * @return string
      */
-    public function __invoke($URI, $Params = [], $Timeout = -1, array $Headers = [], $Depth = 0)
+    public function __invoke($URI, $Params = [], $Timeout = -1, array $Headers = [], $Depth = 0, $Method = '')
     {
         return $this->request($URI, $Params, $Timeout, $Headers, $Depth);
     }
@@ -108,9 +108,10 @@ public function __destruct()
      * @param int $Timeout An optional timeout limit.
      * @param array $Headers An optional array of headers to send with the request.
      * @param int $Depth Recursion depth of the current closure instance.
+     * @param string $Method The request method to use (if not GET or POST).
      * @return string The results of the request, or an empty string upon failure.
      */
-    public function request($URI, $Params = [], $Timeout = -1, array $Headers = [], $Depth = 0)
+    public function request($URI, $Params = [], $Timeout = -1, array $Headers = [], $Depth = 0, $Method = '')
     {
         /** Test channel triggers. */
         foreach ($this->Channels['Triggers'] as $TriggerName => $TriggerURI) {
@@ -138,7 +139,7 @@ public function request($URI, $Params = [], $Timeout = -1, array $Headers = [],
             }
             if ($this->inCsv($TriggerName, $this->Disabled)) {
                 if (isset($AlternateURI)) {
-                    return $this($AlternateURI, $Params, $Timeout, $Headers, $Depth);
+                    return $this($AlternateURI, $Params, $Timeout, $Headers, $Depth, $Method);
                 }
                 return '';
             }
@@ -173,6 +174,9 @@ public function request($URI, $Params = [], $Timeout = -1, array $Headers = [],
                 isset($Overrides['CURLOPT_SSL_VERIFYPEER']) ? !empty($Overrides['CURLOPT_SSL_VERIFYPEER']) : false
             ));
         }
+        if ($Method !== '') {
+            curl_setopt($Request, CURLOPT_CUSTOMREQUEST, $Method);
+        }
         curl_setopt($Request, CURLOPT_FOLLOWLOCATION, true);
         curl_setopt($Request, CURLOPT_MAXREDIRS, 1);
         curl_setopt($Request, CURLOPT_RETURNTRANSFER, true);
@@ -196,7 +200,7 @@ public function request($URI, $Params = [], $Timeout = -1, array $Headers = [],
             /** Request failed. Try again using an alternative address. */
             if ($Info['http_code'] >= 400 && isset($AlternateURI) && $Depth < 3) {
                 curl_close($Request);
-                return $this($AlternateURI, $Params, $Timeout, $Headers, $Depth + 1);
+                return $this($AlternateURI, $Params, $Timeout, $Headers, $Depth + 1, $Method);
             }
         } else {
             $this->sendMessage(sprintf('%s - %s - %s - %s', $Post ? 'POST' : 'GET', $URI, 200, (floor($Time * 100) / 100) . 's'));