feat: add dns_cache_timeout for option CURLRequest

system/HTTP/CURLRequest.php

@@ -616,6 +616,11 @@ protected function setCURLOptions(array $curlOptions = [], array $config = [])
             }
         }
 
+        // DNS Cache Timeout
+        if (isset($config['dns_cache_timeout']) && is_numeric($config['dns_cache_timeout']) && $config['dns_cache_timeout'] >= -1) {
+            $curlOptions[CURLOPT_DNS_CACHE_TIMEOUT] = (int) $config['dns_cache_timeout'];
+        }
+
         // Timeout
         $curlOptions[CURLOPT_TIMEOUT_MS] = (float) $config['timeout'] * 1000;
 

tests/system/HTTP/CURLRequestTest.php

@@ -22,6 +22,7 @@
 use Config\CURLRequest as ConfigCURLRequest;
 use CURLFile;
 use PHPUnit\Framework\Attributes\BackupGlobals;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Group;
 
 /**
@@ -1212,6 +1213,76 @@ public function testForceResolveIPUnknown(): void
         $this->assertSame(\CURL_IPRESOLVE_WHATEVER, $options[CURLOPT_IPRESOLVE]);
     }
 
+    /**
+     * @return iterable<string, array{input: int|string|null, expectedHasKey: bool, expectedValue?: int}>
+     *
+     * @see https://curl.se/libcurl/c/CURLOPT_DNS_CACHE_TIMEOUT.html
+     */
+    public static function provideDNSCacheTimeout(): iterable
+    {
+        yield from [
+            'valid timeout (integer)' => [
+                'input'          => 160,
+                'expectedHasKey' => true,
+                'expectedValue'  => 160,
+            ],
+            'valid timeout (numeric string)' => [
+                'input'          => '180',
+                'expectedHasKey' => true,
+                'expectedValue'  => 180,
+            ],
+            'valid timeout (zero / disabled)' => [
+                'input'          => 0,
+                'expectedHasKey' => true,
+                'expectedValue'  => 0,
+            ],
+            'valid timeout (zero / disabled using string)' => [
+                'input'          => '0',
+                'expectedHasKey' => true,
+                'expectedValue'  => 0,
+            ],
+            'valid timeout (forever)' => [
+                'input'          => -1,
+                'expectedHasKey' => true,
+                'expectedValue'  => -1,
+            ],
+            'valid timeout (forever using string)' => [
+                'input'          => '-1',
+                'expectedHasKey' => true,
+                'expectedValue'  => -1,
+            ],
+            'invalid timeout (null)' => [
+                'input'          => null,
+                'expectedHasKey' => false,
+            ],
+            'invalid timeout (string)' => [
+                'input'          => 'is_wrong',
+                'expectedHasKey' => false,
+            ],
+            'invalid timeout (negative number / below -1)' => [
+                'input'          => -2,
+                'expectedHasKey' => false,
+            ],
+        ];
+    }
+
+    #[DataProvider('provideDNSCacheTimeout')]
+    public function testDNSCacheTimeoutOption(int|string|null $input, bool $expectedHasKey, ?int $expectedValue = null): void
+    {
+        $this->request->request('POST', '/post', [
+            'dns_cache_timeout' => $input,
+        ]);
+
+        $options = $this->request->curl_options;
+
+        if ($expectedHasKey) {
+            $this->assertArrayHasKey(CURLOPT_DNS_CACHE_TIMEOUT, $options);
+            $this->assertSame($expectedValue, $options[CURLOPT_DNS_CACHE_TIMEOUT]);
+        } else {
+            $this->assertArrayNotHasKey(CURLOPT_DNS_CACHE_TIMEOUT, $options);
+        }
+    }
+
     public function testCookieOption(): void
     {
         $holder = SUPPORTPATH . 'HTTP/Files/CookiesHolder.txt';

user_guide_src/source/changelogs/v4.7.0.rst

@@ -38,6 +38,10 @@ Enhancements
 Libraries
 =========
 
+- **CURLRequest:** Added ``dns_cache_timeout`` option to change default DNS cache timeout.
+- **Email:** Added support for choosing the SMTP authorization method. You can change it via ``Config\Email::$SMTPAuthMethod`` option.
+- **Image:** The ``ImageMagickHandler`` has been rewritten to rely solely on the PHP ``imagick`` extension.
+- **Image:** Added ``ImageMagickHandler::clearMetadata()`` method to remove image metadata for privacy protection.
 - **Time:** added methods ``Time::addCalendarMonths()`` and ``Time::subCalendarMonths()``
 
 Commands
@@ -61,13 +65,6 @@ Others
 Model
 =====
 
-Libraries
-=========
-
-**Email:** Added support for choosing the SMTP authorization method. You can change it via ``Config\Email::$SMTPAuthMethod`` option.
-**Image:** The ``ImageMagickHandler`` has been rewritten to rely solely on the PHP ``imagick`` extension.
-**Image:** Added ``ImageMagickHandler::clearMetadata()`` method to remove image metadata for privacy protection.
-
 Helpers and Functions
 =====================
 

user_guide_src/source/libraries/curlrequest.rst

@@ -251,6 +251,18 @@ Allows you to pause a number of milliseconds before sending the request:
 
 .. literalinclude:: curlrequest/023.php
 
+dns_cache_timeout
+=================
+
+.. versionadded:: 4.7.0
+
+By default, CodeIgniter does not change the DNS Cache Timeout value (``120`` seconds). If you need to
+modify this value, you can do so by passing an amount of time in seconds with the ``dns_cache_timeout`` option.
+
+.. literalinclude:: curlrequest/037.php
+
+.. note:: Based on the `libcurl <https://curl.se/libcurl/c/CURLOPT_DNS_CACHE_TIMEOUT.html>`__ documentation, you can set to zero (``0``) to completely disable caching, or set to ``-1`` to make the cached entries remain forever.
+
 form_params
 ===========
 

user_guide_src/source/libraries/curlrequest/037.php

@@ -0,0 +1,4 @@
+<?php
+
+// Modify default DNS Cache Timeout
+$client->request('GET', '/', ['dns_cache_timeout' => 360]); // seconds