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

PHP, while generally stateless by default, occasionally provides forms of “persistence” for connections, e.g. 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.

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.

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.

None expected.

Next PHP minor release.

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

curl_share_init in ext/curl will have a new signature.

None.

None.

None.

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

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

This vote requires a ⅔ majority:

Add curl_share_init(?array $share_options, ?string $persistent_id) in the next PHP minor release
Real name	Yes	No
alcaeus (alcaeus)
alec (alec)
as (as)
asgrim (asgrim)
ashnazg (ashnazg)
bukka (bukka)
bwoebi (bwoebi)
dasl (dasl)
derick (derick)
dharman (dharman)
enorris (enorris)
galvao (galvao)
girgias (girgias)
jimw (jimw)
keyur (keyur)
kguest (kguest)
malferov (malferov)
mbeccati (mbeccati)
mfonda (mfonda)
nicolasgrekas (nicolasgrekas)
ocramius (ocramius)
rasmus (rasmus)
theodorejb (theodorejb)
timwolla (timwolla)
Final result:	16	8
This poll has been closed.

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

• 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