A Unix-domain socket is a transport path to a local service, not a proxy address. Set CURLOPT_UNIX_SOCKET_PATH for the socket and keep an ordinary HTTP URL so cURL can build the request and Host header.
Last updated: October 13, 2026.
<?php
declare(strict_types=1);
$curl = curl_init('http://localhost/v1/health');
curl_setopt_array($curl, [
CURLOPT_UNIX_SOCKET_PATH => '/run/example-api.sock',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 2,
CURLOPT_TIMEOUT => 10,
]);
$body = curl_exec($curl);
if ($body === false) {
throw new RuntimeException(curl_error($curl), curl_errno($curl));
}
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);The socket file must exist and the PHP worker account needs permission to connect to it. The URL host is still used at the HTTP layer even though no TCP connection is opened.
Do not put a socket path in CURLOPT_PROXY
The PHP curl_setopt() reference lists the cURL options exposed by the extension. CURLOPT_PROXY expects a proxy hostname or URL. Passing /run/example-api.sock there can make libcurl parse the path as a malformed proxy target.
The libcurl documentation for CURLOPT_UNIX_SOCKET_PATH specifies that the socket replaces the normal network connection while the URL continues to describe the HTTP request. Use CURLOPT_PROXY only when traffic should pass through an HTTP or SOCKS proxy.
Diagnose connection failures safely
Check the socket with ls -l and confirm which service user owns it. If PHP-FPM runs as another account, fix the service group or socket mode rather than making the socket world-writable. A missing socket usually means the upstream service is stopped or configured to listen elsewhere.
Always set bounded connect and request timeouts, inspect curl_errno(), and treat a successful transport separately from an HTTP error status. Continue with handling cURL option failures, detecting PHP socket timeouts, and calling an HTTP API from PHP.
