feat: share Connection & DNS Cache to CURLRequest

[ddevsr]

Description
I need this for reuse connection. As soon PHP 8.5 will have new function for persistent, Benefit choosing persistent_id by PHP (read more on RFC).

php/php-src@d20880c#diff-6db2da0f77fa4c56808260fdf566a723bbb52d6159077953097d05d995335558R135-R245

https://wiki.php.net/rfc/curl_share_persistence_improvement

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[michalsn]

This is a nice improvement, but I think it would benefit from being more configurable.

How about introducing a $share array in the config with default values like connect and dns, and optionally supporting others like cookie, session, and psl? This way, we can control what gets shared based on the use case. If the array is empty, we can skip calling curl_share_init() entirely, which avoids unnecessary memory allocation.

We should also note in the user guide that the $share option makes the most sense when making requests to the same domain.

It's a bit unfortunate that we already have $shareOptions property in the config - hopefully it won't be confusing.

[ddevsr]

In new function persistent that avoid cookie, we avoid too?

[michalsn]

Do you mean curl_share_init_persistent()?
I think we should introduce a new configuration option, such as sharePersistent, which would default to false. If persistence is enabled, I’d still accept all share options - PHP will handle any invalid ones, like the cookie option, by throwing an error.

[ddevsr]

<?php

$optShareConnection = [
            CURL_LOCK_DATA_CONNECT,
            CURL_LOCK_DATA_DNS,
];
$this->shareConnection = curl_share_init();

foreach (array_unique($optShareConnection) as $opt) {
      curl_share_setopt($this->shareConnection, CURLSHOPT_SHARE, $opt);
}

same as persistent implementation in next PR (when ready):

<?php

$optShareConnection = [
            CURL_LOCK_DATA_CONNECT,
            CURL_LOCK_DATA_DNS,
];
$this->shareConnection = curl_share_init_persistent($optShareConnection);

[paulbalandan]

The sentence suggests it is boolean rather than as array. Please revise. I think this property should read as "shareConnectionOptions".

[michalsn]

It would be good to mention that these are the default values.