====== PHP RFC: Add persistent curl share handles ======
  * Version: 1.2
  * Date: 2024-10-09
  * Author: Eric Norris, erictnorris@gmail.com
  * Status: Accepted
  * First Published at: http://wiki.php.net/rfc/curl_share_persistence

===== Introduction =====

PHP, while generally stateless by default, occasionally provides forms of "persistence" for connections, e.g. [[https://www.php.net/manual/en/pdo.constants.php#pdo.constants.attr-persistent|PDO::ATTR_PERSISTENT]] for persistent PDO connections.

Persistence allows PHP scripts to eliminate the overhead of establishing a connection on subsequent requests, which can improve performance and reliability.

''curl'', a popular URL transfer library made available as a core extension in PHP, provides the ability to share data between curl handles via a "share" interface. The PHP extension supports this functionality in ''curl_share_init'' and related functions.

The PHP extension does not, however, support persistent curl share handles. Connections (and DNS lookups, SSL session IDs, etc.) are only shared between handles within a single SAPI request.

===== Proposal =====

This RFC proposes to enable users to create persistent curl share handles, by modifying the signature of ''curl_share_init'' to accept a persistent ID: ''curl_share_init(?array $share_options, ?string $persistent_id)''.

When called with a persistent ID, the function will first check the global memory within the SAPI worker for an existing curl share handle. If found, the function will return immediately.

If a curl share handle does not already exist, the function will construct a new one, apply the given share options, store it in global memory, and return it.

==== Safety ====

Since curl share handles are stateful, developers must consider whether a given ''CURL_LOCK_DATA_*'' constant is safe to use in a persistent context.

  * ''CURL_LOCK_DATA_CONNECT'' and ''CURL_LOCK_DATA_SSL_SESSION'' is safe to use; curl will not reuse connections between ''CurlHandle'' objects unless the connection settings (e.g. TLS client certificates) match.
  * ''CURL_LOCK_DATA_COOKIE'' is **not** safe to use when making downstream requests on behalf of users; developers must take care to ensure that authentication cookies, etc. are not shared between separate users.
  * ''CURL_LOCK_DATA_DNS'' is safe to use.
  * ''CURL_LOCK_DATA_PSL'' is safe to use.

===== Backward Incompatible Changes =====

None expected.

===== Proposed PHP Version(s) =====

Next PHP minor release.

===== RFC Impact =====

==== To SAPIs ====

SAPIs will consume more memory proportional to the number of persistent curl share handles.

==== To Existing Extensions ====

''curl_share_init'' in ''ext/curl'' will have a new signature.

==== To Opcache ====

None.

==== New Constants ====

None.

==== php.ini Defaults ====

None.

===== Future Scope =====

  * We may want to put together an RFC in the future for a new internal API for persistence.

===== Voting Choices =====

Voting started on 2024-10-24 and will end on 2024-11-08 00:00 UTC.

This vote requires a ⅔ majority:

<doodle title="Add curl_share_init(?array $share_options, ?string $persistent_id) in the next PHP minor release" auth="enorris" voteType="single" closed="true" closeon="2024-11-08T00:00:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

  * https://github.com/php/php-src/pull/15603

===== Implementation =====


===== References =====

  * https://wiki.php.net/rfc/resource_to_object_conversion
  * https://github.com/curl/curl/pull/1917 - curl pull request demonstrating their position on connection reuse with TLS settings
===== Rejected Features =====