Using PHP cURL with a SOCKS5 Proxy to Access Tor .onion Services

By the end of this page, you will understand why .onion addresses often fail with normal PHP cURL settings, how SOCKS5 proxy resolution works, and how to configure PHP cURL so Tor resolves the hostname correctly. You will also see common mistakes, practical examples, and a small project that fetches a page through Tor safely.

A Tor hidden service uses a .onion hostname, which is not a normal public DNS name. Your operating system's DNS resolver usually cannot resolve it.

When you send a request through a SOCKS5 proxy, there are two possible ways hostname resolution can happen:

• Local resolution: your machine tries to resolve the hostname before sending the connection to the proxy
• Proxy resolution: the proxy receives the hostname and resolves it itself

For .onion addresses, proxy resolution is required. Tor understands .onion names, but your normal DNS setup does not.

That is why this matters:

• If PHP/libcurl tries to resolve example.onion locally, it fails with Couldn't resolve host name
• If Tor resolves it through SOCKS5, the request can succeed

In command-line curl, the option:

--socks5-hostname

means: use a SOCKS5 proxy and let the proxy resolve the hostname.

In PHP cURL, the matching idea is to use the proxy type that tells libcurl to pass the hostname to the SOCKS5 proxy instead of resolving it locally.

The important distinction is:

• CURLPROXY_SOCKS5 → often resolves locally first
• CURLPROXY_SOCKS5_HOSTNAME → proxy resolves the hostname

Think of a SOCKS5 proxy like a courier service.

• With local resolution, you tell the courier: "Go to the building at this exact street address." But you first need to translate the name into an address yourself.
• With proxy resolution, you tell the courier: "Take this name and figure out where it goes." The courier handles the lookup.

A .onion address is like a destination that only a special courier understands. Tor is that special courier. If you try to look it up yourself using normal DNS, you get nowhere.

So the rule is simple:

• Normal domain? local or proxy resolution may both work
• .onion domain? let Tor resolve it through the proxy

The key setting in PHP is the proxy type.

Correct syntax for Tor .onion services

<?php
$url = 'http://jhiwjjlqpyawmpjx.onion/';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_PROXY, '127.0.0.1:9050');
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5_HOSTNAME);

$output = curl_exec($ch);

if ($output === false) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    echo $output;
}

curl_close($ch);

Why this works

CURLPROXY_SOCKS5_HOSTNAME tells libcurl:

Consider this code:

<?php
$ch = curl_init('http://exampleonionaddress.onion/');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_PROXY, '127.0.0.1:9050');
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5_HOSTNAME);

$response = curl_exec($ch);

if ($response === false) {
    echo curl_error($ch);
}

curl_close($ch);

Here is what happens step by step:

1. curl_init() creates a cURL handle for the .onion URL.
2. CURLOPT_RETURNTRANSFER tells cURL to return the response as a string instead of printing it directly.
3. CURLOPT_PROXY sets Tor's local SOCKS proxy, usually 127.0.0.1:9050.
4. CURLOPT_PROXYTYPE is set to .

This pattern appears in real software whenever an application must send traffic through Tor or another SOCKS5 proxy.

Common use cases

• Privacy-focused scripts that fetch data without direct outbound connections
• Monitoring hidden services to verify uptime or page availability
• Security research tools that access .onion resources in controlled environments
• Backend services that must route selected requests through Tor
• Scrapers or crawlers designed to work with SOCKS5-based hostname resolution

Example scenarios

• A PHP script checks whether an internal .onion service is online every 5 minutes
• A web tool downloads content from a hidden service for later analysis
• A command-line PHP script sends requests through Tor to avoid exposing the server's direct IP

The underlying idea is always the same: if the target hostname is only meaningful to the proxy, the proxy must resolve it.

In real projects, developers usually wrap proxy-aware cURL setup in a helper function so they do not repeat the same options everywhere.

Common patterns

Guard clauses

Fail early if the cURL extension is missing or Tor is not available.

<?php
if (!function_exists('curl_init')) {
    throw new RuntimeException('cURL extension is not enabled.');
}

Centralized configuration

Keep proxy settings in one place:

<?php
$torProxy = '127.0.0.1:9050';
$proxyType = CURLPROXY_SOCKS5_HOSTNAME;

This makes it easier to change environments later.

Timeouts and error handling

Developers rarely call curl_exec() without checking errors.

<?php
$result = curl_exec($ch);
if ($result === false) {
    $error = curl_error();
    
}

1. Using CURLPROXY_SOCKS5 instead of CURLPROXY_SOCKS5_HOSTNAME

This is the main problem in the original question.

Broken

curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5);

Correct

curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5_HOSTNAME);

CURLPROXY_SOCKS5 can lead to local DNS resolution. .onion names need proxy-side resolution.

2. Including the proxy as a full URL when only host and port are needed

Some developers write:

curl_setopt($ch, CURLOPT_PROXY, 'http://127.0.0.1:9050/');

This may work in some cases, but the clearer and more typical form is:

curl_setopt($ch, CURLOPT_PROXY, '127.0.0.1:9050');

3. Not checking whether curl_exec() returned

curl_setopt($ch, CURLOPT_PROXY, '127.0.0.1:9050');
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5_HOSTNAME);

Quick rules

• Use CURLPROXY_SOCKS5_HOSTNAME for .onion addresses
• Do not rely on local DNS for .onion
• Tor usually listens on 127.0.0.1:9050
• Check curl_exec() for false
• Use curl_error() for debugging
• Add timeouts for reliability

Minimal working example

<?php
$ch = curl_init('http://exampleonionaddress.onion/');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROXY => '127.0.0.1:9050',
    CURLOPT_PROXYTYPE => CURLPROXY_SOCKS5_HOSTNAME,
]);

$response = curl_exec($ch);

if ( === ) {
     ();
}

();

Why does PHP cURL say Couldn't resolve host name for a .onion URL?

Because local DNS does not understand .onion addresses. You must let the SOCKS5 proxy resolve the hostname.

What is the PHP equivalent of curl --socks5-hostname?

Use:

curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5_HOSTNAME);

What is the difference between CURLPROXY_SOCKS5 and CURLPROXY_SOCKS5_HOSTNAME?

CURLPROXY_SOCKS5 may resolve the hostname locally. CURLPROXY_SOCKS5_HOSTNAME sends the hostname to the proxy for resolution.

Do I need Tor installed and running locally?

Yes, if you are connecting through 127.0.0.1:9050, Tor must be running and listening on that port.

Can I use http://127.0.0.1:9050/ as the proxy value?

It is better to use 127.0.0.1:9050. It is simpler and avoids confusion.

Does this only matter for .onion domains?

• cURL in PHP — the core library used to make HTTP requests from PHP
• SOCKS5 proxy — the proxy protocol used by Tor for routing connections
• DNS resolution — explains why .onion names fail with local hostname lookup
• Tor hidden services — the type of service addressed by .onion hostnames
• Proxy configuration — useful for understanding host, port, and proxy type settings
• Error handling in PHP — important for checking curl_exec() results and debugging failures
• HTTP requests — broader concept behind fetching remote resources
• Timeouts in network programming — helps make proxy-based requests more reliable