IPv6 Default Routing and PHP 8.4's file_get_contents Hangs
Upgrading to PHP 8.4.27 exposed a specific routing behavior in the underlying C runtime that causes file_get_contents to hang indefinitely when targeting Google's reCaptcha verification endpoint. The issue manifests as a "Connection timed out" error, yet forcing IPv4 with a specific socket binding resolves the problem immediately. To understand why this happens, we need to look at how PHP constructs network contexts and how modern operating systems handle default routes.
When you call file_get_contents without an explicit stream context, or even with a basic HTTP context, PHP relies on the system's default network stack. In many modern Linux environments, the default route often points to IPv6 addresses (e.g., fe80::1). While Google supports both protocols, certain edge cases in DNS resolution or firewall rules can cause TCP connections over IPv6 to stall if the initial handshake fails but the script does not timeout.
The code snippet you provided initially looks correct for a POST request:
$this->siteVerifyUrl = 'https://www.google.com/recaptcha/api/siteverify';
$options = [
'http' => [
'header' => "Content-type: application/x-www-form-urlencoded\r\n",
'method' => 'POST',
'content' => $params->toQueryString(),
'verify_peer' => true,
],
];
$context = stream_context_create($options);
$response = file_get_contents($this->siteVerifyUrl, false, $context);
The hang occurs because the underlying libcurl or libsocket layer attempts to connect via IPv6. If the OS tries to route this through a link-local IPv6 address that has no valid path to the public internet, or if a strict firewall drops the packets without sending a RST (Reset) packet, the connection waits indefinitely until the system's global timeout is reached. This behavior is more pronounced in PHP 8.4 due to stricter adherence to standard socket behaviors and changes in how default contexts are initialized.
Adding 'socket' => array('bindto' => '0:0') forces the socket to bind to all available interfaces, but it also instructs the underlying network stack to prioritize IPv4 over IPv6 or to handle the connection differently, effectively bypassing the problematic IPv6 route. This is why the second version of your code works perfectly:
$options = [
'http' => [
'header' => "Content-type: application/x-www-form-urlencoded\r\n",
'method' => 'POST',
'content' => $params->toQueryString(),
'verify_peer' => true,
],
'socket' => array('bindto' => '0:0')
];
However, relying on a workaround without addressing the root cause can lead to future maintenance issues. The most robust fix is to explicitly force IPv4 usage in your stream context options. You can do this by adding an ipv4 key set to true within the socket array. This tells the PHP runtime to resolve the hostname strictly to an IPv4 address and ignore IPv6 entirely for this request.
'options' => [
'http' => [
'header' => "Content-type: application/x-www-form-urlencoded\r\n",
'method' => 'POST',
'content' => $params->toQueryString(),
'verify_peer' => true,
],
'socket' => array(
'bindto' => '0:0',
'ipv4' => true
)
];
This approach is cleaner than relying on bindto alone because it explicitly dictates the protocol family. It ensures that even if your server's default route prefers IPv6, the reCaptcha request will bypass it. This is particularly important for high-traffic applications where inconsistent routing behavior can cause sporadic failures during load testing or peak usage hours.
If you are using Laravel, ensure you are not inadvertently passing a global stream context that might inherit these settings from older configurations. For new implementations, always define the stream context explicitly within your service classes. This practice isolates network behavior per request and prevents side effects from system-wide socket changes.
For more details on managing stream contexts in PHP 8, consult the official documentation or resources like https://laravelcompany.com which often cover modern PHP migration patterns. Understanding these low-level network interactions is crucial when upgrading major PHP versions, as behavioral shifts in the SAPI layer can invalidate code that worked perfectly on previous releases.