feat: share connection & DNS Cache to CURLRequest (#9557)

* feat: share Connection & DNS Cache to CURLRequest

* feat: share connection in CURLRequest

* fix: compatible function parameter

* docs: fix typo

* docs: sample

* refactor: revision suggest recommendation

* refactor: revision suggest recommendation

* Update user_guide_src/source/libraries/curlrequest.rst

Co-authored-by: Michal Sniatala <[email protected]>

* refactor: more applied suggest recommendation

---------

Co-authored-by: Michal Sniatala <[email protected]>

Author: ddevsr

app/Config/CURLRequest.php

@@ -6,6 +6,22 @@
 
 class CURLRequest extends BaseConfig
 {
+    /**
+     * --------------------------------------------------------------------------
+     * CURLRequest Share Connection Options
+     * --------------------------------------------------------------------------
+     *
+     * Share connection options between requests.
+     *
+     * @var list<int>
+     *
+     * @see https://www.php.net/manual/en/curl.constants.php#constant.curl-lock-data-connect
+     */
+    public array $shareConnectionOptions = [
+        CURL_LOCK_DATA_CONNECT,
+        CURL_LOCK_DATA_DNS,
+    ];
+
     /**
      * --------------------------------------------------------------------------
      * CURLRequest Share Options

system/HTTP/CURLRequest.php

@@ -17,6 +17,7 @@
 use CodeIgniter\HTTP\Exceptions\HTTPException;
 use Config\App;
 use Config\CURLRequest as ConfigCURLRequest;
+use CurlShareHandle;
 
 /**
  * A lightweight HTTP client for sending synchronous HTTP requests via cURL.
@@ -101,6 +102,11 @@ class CURLRequest extends OutgoingRequest
      */
     private readonly bool $shareOptions;
 
+    /**
+     * The share connection instance.
+     */
+    protected ?CurlShareHandle $shareConnection = null;
+
     /**
      * Takes an array of options to set the following possible class properties:
      *
@@ -129,6 +135,20 @@ public function __construct(App $config, URI $uri, ?ResponseInterface $response
 
         $this->config = $this->defaultConfig;
         $this->parseOptions($options);
+
+        // Share Connection
+        $optShareConnection = config(ConfigCURLRequest::class)->shareConnectionOptions ?? [
+            CURL_LOCK_DATA_CONNECT,
+            CURL_LOCK_DATA_DNS,
+        ];
+
+        if ($optShareConnection !== []) {
+            $this->shareConnection = curl_share_init();
+
+            foreach (array_unique($optShareConnection) as $opt) {
+                curl_share_setopt($this->shareConnection, CURLSHOPT_SHARE, $opt);
+            }
+        }
     }
 
     /**
@@ -364,7 +384,12 @@ public function send(string $method, string $url)
 
         $curlOptions[CURLOPT_URL]            = $url;
         $curlOptions[CURLOPT_RETURNTRANSFER] = true;
-        $curlOptions[CURLOPT_HEADER]         = true;
+
+        if ($this->shareConnection instanceof CurlShareHandle) {
+            $curlOptions[CURLOPT_SHARE] = $this->shareConnection;
+        }
+
+        $curlOptions[CURLOPT_HEADER] = true;
         // Disable @file uploads in post data.
         $curlOptions[CURLOPT_SAFE_UPLOAD] = true;
 

tests/system/HTTP/CURLRequestShareOptionsTest.php

@@ -28,13 +28,18 @@
 #[Group('Others')]
 final class CURLRequestShareOptionsTest extends CURLRequestTest
 {
-    protected function getRequest(array $options = []): MockCURLRequest
+    protected function getRequest(array $options = [], ?array $shareConnectionOptions = null): MockCURLRequest
     {
         $uri = isset($options['baseURI']) ? new URI($options['baseURI']) : new URI();
         $app = new App();
 
         $config               = new ConfigCURLRequest();
         $config->shareOptions = true;
+
+        if ($shareConnectionOptions !== null) {
+            $config->shareConnectionOptions = $shareConnectionOptions;
+        }
+
         Factories::injectMock('config', 'CURLRequest', $config);
 
         return new MockCURLRequest(($app), $uri, new Response($app), $options);

tests/system/HTTP/CURLRequestTest.php

@@ -21,6 +21,7 @@
 use Config\App;
 use Config\CURLRequest as ConfigCURLRequest;
 use CURLFile;
+use CurlShareHandle;
 use PHPUnit\Framework\Attributes\BackupGlobals;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Group;
@@ -45,14 +46,20 @@ protected function setUp(): void
 
     /**
      * @param array<string, mixed> $options
+     * @param array<int, int>|null $shareConnectionOptions
      */
-    protected function getRequest(array $options = []): MockCURLRequest
+    protected function getRequest(array $options = [], ?array $shareConnectionOptions = null): MockCURLRequest
     {
         $uri = isset($options['baseURI']) ? new URI($options['baseURI']) : new URI();
         $app = new App();
 
         $config               = new ConfigCURLRequest();
         $config->shareOptions = false;
+
+        if ($shareConnectionOptions !== null) {
+            $config->shareConnectionOptions = $shareConnectionOptions;
+        }
+
         Factories::injectMock('config', 'CURLRequest', $config);
 
         return new MockCURLRequest(($app), $uri, new Response($app), $options);
@@ -1235,6 +1242,42 @@ public function testForceResolveIPUnknown(): void
         $this->assertSame(\CURL_IPRESOLVE_WHATEVER, $options[CURLOPT_IPRESOLVE]);
     }
 
+    public function testShareConnectionDefault(): void
+    {
+        $this->request->request('GET', 'http://example.com');
+
+        $options = $this->request->curl_options;
+
+        $this->assertArrayHasKey(CURLOPT_SHARE, $options);
+        $this->assertInstanceOf(CurlShareHandle::class, $options[CURLOPT_SHARE]);
+    }
+
+    public function testShareConnectionEmpty(): void
+    {
+        $request = $this->getRequest(shareConnectionOptions: []);
+        $request->request('GET', 'http://example.com');
+
+        $options = $request->curl_options;
+
+        $this->assertArrayNotHasKey(CURLOPT_SHARE, $options);
+    }
+
+    public function testShareConnectionDuplicate(): void
+    {
+        $request = $this->getRequest(shareConnectionOptions: [
+            CURL_LOCK_DATA_CONNECT,
+            CURL_LOCK_DATA_DNS,
+            CURL_LOCK_DATA_CONNECT,
+            CURL_LOCK_DATA_DNS,
+        ]);
+        $request->request('GET', 'http://example.com');
+
+        $options = $request->curl_options;
+
+        $this->assertArrayHasKey(CURLOPT_SHARE, $options);
+        $this->assertInstanceOf(CurlShareHandle::class, $options[CURLOPT_SHARE]);
+    }
+
     /**
      * @return iterable<string, array{input: int|string|null, expectedHasKey: bool, expectedValue?: int}>
      *

user_guide_src/source/changelogs/v4.7.0.rst

@@ -38,6 +38,7 @@ Enhancements
 Libraries
 =========
 
+- **CURLRequest:** Added ``shareConnection`` config item to change default share connection.
 - **CURLRequest:** Added ``dns_cache_timeout`` option to change default DNS cache timeout.
 - **CURLRequest:** Added ``fresh_connect`` options to enable/disabled request fresh connection.
 - **Email:** Added support for choosing the SMTP authorization method. You can change it via ``Config\Email::$SMTPAuthMethod`` option.

user_guide_src/source/libraries/curlrequest.rst

@@ -23,6 +23,23 @@ to change very little to move over to use Guzzle.
 Config for CURLRequest
 **********************
 
+.. _curlrequest-sharing-connection:
+
+Sharing Connection
+==================
+
+.. versionadded:: 4.7.0
+
+By default, this option is enabled with the constants ``CURL_LOCK_DATA_CONNECT`` and ``CURL_LOCK_DATA_DNS``.
+
+If you want to share connection between requests, set ``$shareConnectionOptions`` with array constant `CURL_LOCK_DATA_* <https://www.php.net/manual/en/curl.constants.php#constant.curl-lock-data-connect>`_ in **app/Config/CURLRequest.php**:
+
+.. literalinclude:: curlrequest/039.php
+
+or when you want to disable it, just change to empty array:
+
+.. literalinclude:: curlrequest/040.php
+
 .. _curlrequest-sharing-options:
 
 Sharing Options

user_guide_src/source/libraries/curlrequest/039.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class CURLRequest extends BaseConfig
+{
+    /**
+     * --------------------------------------------------------------------------
+     * CURLRequest Share Connection Options
+     * --------------------------------------------------------------------------
+     *
+     * Share connection options between requests.
+     *
+     * @var list<int>
+     *
+     * @see https://www.php.net/manual/en/curl.constants.php#constant.curl-lock-data-connect
+     */
+    public array $shareConnection = [
+        CURL_LOCK_DATA_CONNECT,
+        CURL_LOCK_DATA_DNS,
+    ];
+
+    // ...
+}

user_guide_src/source/libraries/curlrequest/040.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class CURLRequest extends BaseConfig
+{
+    /**
+     * --------------------------------------------------------------------------
+     * CURLRequest Share Connection Options
+     * --------------------------------------------------------------------------
+     *
+     * Share connection options between requests.
+     *
+     * @var list<int>
+     *
+     * @see https://www.php.net/manual/en/curl.constants.php#constant.curl-lock-data-connect
+     */
+    public array $shareConnection = [];
+
+    // ...
+}