An earlier RFC added persistent curl share handles. A share handle lets several curl requests share data like open connections, and "persistent" means the handle survives after the PHP request ends, so later requests can reuse it. That RFC passed, but people raised problems after the vote. This RFC from Eric Norris fixes them with a new design.

What was wrong with the first design

The first version added two parameters to curl_share_init(), including a $persistent_id string. Three issues came up:

  • Cookies could leak. With CURL_LOCK_DATA_COOKIE, a badly chosen ID could share one cookie jar across unrelated requests, which could mix up cookies between users.
  • You had to pick the IDs. Poorly chosen IDs could pile up many handles, with nothing to clean them up.
  • Handles could change. Calling curl_share_setopt() on a persistent handle would change it for every later request.

The new design

Instead of new parameters on curl_share_init(), there's a new function:

curl_share_init_persistent(array $share_options): CurlSharePersistentHandle

You pass it CURL_LOCK_DATA_* constants, then attach the handle to a request with curl_setopt() and the CURLOPT_SHARE option. The design fixes each problem:

  • CURL_LOCK_DATA_COOKIE isn't allowed, and passing it throws a RuntimeException.
  • There's no ID to choose, because PHP reuses one handle for each unique set of options.
  • CurlSharePersistentHandle is its own type that the other curl_share_* functions don't accept, so once it's created, it can't change.

You also can't pass the new handle to curl_share_close().

What it means for existing code

Nothing breaks, since the first design never shipped in a PHP release.

The vote

There were two votes, and both passed 9 to 0. Both closed on January 2, 2025.

  • Use the new function instead of the old signature. This needed a two-thirds majority.
  • Block CURL_LOCK_DATA_COOKIE. This needed a simple majority.

The change was then merged into php-src.