How can I connect to a Tor hidden service using cURL in PHP?

How can I connect to a Tor hidden service using cURL in PHP?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The DNS Resolution Trap in PHP cURL Tor Connections

Connecting to a Tor hidden service from command-line tools often feels straightforward, but replicating that behavior in PHP can hit an immediate wall. You might find yourself staring at a Couldn't resolve host name error when running standard cURL code, even though the exact same command works perfectly fine from your terminal. This discrepancy isn't a bug in your proxy configuration; it is a fundamental misunderstanding of where DNS resolution occurs in the request lifecycle.

The core issue lies in the order of operations between the client (PHP) and the proxy (Tor). When you execute curl -v --socks5-hostname localhost:9050 http://jhiwjjlqpyawmpjx.onion from a shell, you are effectively telling cURL to hand off the hostname resolution to the SOCKS proxy. Tor reads the .onion address and resolves it internally before forwarding the connection. However, PHP's default behavior with CURLOPT_PROXYTYPE set to CURLPROXY_SOCKS5 does not automatically disable local DNS resolution for the target URL.

By default, PHP's cURL extension attempts to resolve the hostname provided in $url against your system's DNS resolver (usually /etc/resolv.conf) before it ever touches the proxy. Since .onion addresses are not part of the public Internet DNS system, this lookup fails immediately, resulting in the error you observed. The fix requires explicitly instructing cURL to skip local resolution and pass the raw hostname string to the proxy.

You can achieve this by setting CURLOPT_PROXYHOSTRESOLVE to true. This option tells cURL to rely entirely on the proxy server for name resolution rather than querying your local DNS. Here is how you modify the PHP code:

$url = 'http://jhiwjjlqpyawmpjx.onion/';
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Configure the SOCKS5 proxy
curl_setopt($ch, CURLOPT_PROXY, '127.0.0.1:9050');
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5);

// CRITICAL FIX: Enable proxy-side name resolution
curl_setopt($ch, CURLOPT_PROXYHOSTRESOLVE, true); 

$output = curl_exec($ch);
$curl_error = curl_error($ch);
curl_close($ch);

if ($curl_error) {
    die("cURL Error: " . $curl_error);
}

print_r($output);

If you are running PHP 7.2 or earlier, this specific option might not be available in your cURL build, as CURLOPT_PROXYHOSTRESOLVE was added in later versions of the library to address exactly this use case. In those older environments, you may need to check if your system's hosts file or local DNS settings are interfering, though typically upgrading the cURL extension is the cleanest path forward.

Another potential pitfall involves how PHP handles SSL verification when dealing with hidden services. Tor nodes often present certificates that do not match the standard public CA roots because they self-sign or use specific trust anchors. While this article focuses on the DNS resolution error, it is worth noting that if you encounter certificate errors after fixing the hostname issue, you may need to adjust CURLOPT_SSL_VERIFYPEER and ensure your cURL instance includes the appropriate root certificates, such as those used by the Tor network.

For developers building applications on top of Laravel, this logic remains consistent regardless of the framework. The underlying cURL library handles the networking, so the fix applies universally. If you are using a package manager like Composer to install cURL extensions, ensure you are installing a version that supports the CURLOPT_PROXYHOSTRESOLVE flag if you are targeting PHP 7.2+.

Always verify that your Tor service is actually listening on the port specified in $ch. The command-line success suggests your Tor instance is running correctly, so the isolation here is purely within the PHP runtime environment. By explicitly delegating DNS resolution to the proxy, you bridge the gap between local network expectations and the anonymity network's internal addressing scheme.

Our network