feat(transport): use share handle

[Litarnus]

Adds either a regular share handle or a persistent one to our curl handle, so it can share connect, DNS and SSL between each request without having to reestablish it.

When available, it will use the persistent share handle which should improve request performance between PHP executions. It falls back to the regular share handle which can improve performance within the same PHP execution if multiple requests are performed.

[Litarnus]

The documentation doesn't mention that curl_share_init can return false, in contrast to curl_init.

[sentry]

Bug: The return values of curl_share_setopt() are not checked. If a call fails, the share handle will be misconfigured, silently disabling the intended caching feature.
_{Severity: MEDIUM}

🔍 Detailed Analysis

The try-catch block around curl_share_init() is intended to gracefully handle setup failures. However, the subsequent curl_share_setopt() calls do not throw exceptions on failure; they return false. The code does not check these return values. If any curl_share_setopt() call fails, the catch block is skipped, and $this->shareHandle remains set to a partially configured handle. This misconfigured handle will be used later, causing the intended DNS, connect, and SSL session sharing to fail silently without any error or warning. The feature will not work as expected.

💡 Suggested Fix

Check the boolean return value of each curl_share_setopt() call. If any call returns false, set $this->shareHandle to null to prevent the misconfigured handle from being used, aligning with the intended graceful degradation.

🤖 Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: src/HttpClient/HttpClient.php#L58-L64

Potential issue: The `try-catch` block around `curl_share_init()` is intended to
gracefully handle setup failures. However, the subsequent `curl_share_setopt()` calls do
not throw exceptions on failure; they return `false`. The code does not check these
return values. If any `curl_share_setopt()` call fails, the `catch` block is skipped,
and `$this->shareHandle` remains set to a partially configured handle. This
misconfigured handle will be used later, causing the intended DNS, connect, and SSL
session sharing to fail silently without any error or warning. The feature will not work
as expected.

_{Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 8543567}

[cursor]

Missing check for false return from curl_share_init

Medium Severity

When curl_share_init() returns false (possible in PHP 7.x on failure), $this->shareHandle is set to false. The check if ($this->shareHandle !== null) passes since false !== null is true, causing curl_setopt() to be called with false as the share handle. The PR discussion explicitly noted this concern ("an extra check doesn't hurt") but the check wasn't added. This could cause warnings and prevent proper fallback behavior when share handle initialization fails.

Additional Locations (1)

• src/HttpClient/HttpClient.php#L111-L114