A PHP cURL proxy needs only a handful of options, but the defaults hide useful information. Out of the box, a rejected proxy login and a blocked page can look the same from your script: an empty body and a vague error. This guide sets up the proxy properly, shows how to read what went wrong, and covers parallel requests with curl_multi and the Guzzle equivalent.
Basic PHP cURL Proxy Request
<?php
$ch = curl_init('https://api.ipify.org');
curl_setopt_array($ch, [
CURLOPT_PROXY => 'http://global.nodeproxies.xyz:8080',
CURLOPT_PROXYUSERPWD => 'USERNAME-country-us:PASSWORD',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 15,
CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
if ($body === false) {
echo 'cURL error: ' . curl_error($ch) . PHP_EOL;
} else {
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . ' ' . $body . PHP_EOL;
}
curl_close($ch);CURLOPT_PROXYUSERPWD keeps the credentials out of the URL, so you don't need to URL-encode a password containing @ or :. The output is the IP the target saw.
Telling Proxy Errors from Website Errors
For HTTPS targets, a refused CONNECT makes curl_exec return false with an error like "CONNECT tunnel failed, response 407". For HTTP targets, the proxy's status comes back as the HTTP code. Handle both:
$body = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($errno && str_contains($error, '407') || $code === 407) {
throw new RuntimeException('Proxy rejected credentials or plan inactive');
}
if ($errno && str_contains($error, '402') || $code === 402) {
throw new RuntimeException('Proxy plan is out of bandwidth');
}
if ($errno === CURLE_OPERATION_TIMEDOUT) {
// slow exit or target, safe to retry
}str_contains needs PHP 8. CURLINFO_HTTP_CONNECTCODE also returns the proxy's response code to CONNECT, which is cleaner if you only care about the tunnel. Don't retry 407 or 402; retry timeouts and 5xx. A full checklist for 407 is in how to fix proxy error 407.
SOCKS5 with Remote DNS
curl_setopt_array($ch, [
CURLOPT_PROXY => 'global.nodeproxies.xyz:1080',
CURLOPT_PROXYTYPE => CURLPROXY_SOCKS5_HOSTNAME,
CURLOPT_PROXYUSERPWD => 'USERNAME:PASSWORD',
]);Use CURLPROXY_SOCKS5_HOSTNAME rather than CURLPROXY_SOCKS5. The plain version resolves DNS on your server and sends only an IP, which leaks lookups and can produce results for the wrong region.
Sticky Sessions Across Requests
For a flow that needs one IP, like loading a page and then submitting its form, use a session in the username and keep a cookie jar:
$session = bin2hex(random_bytes(4));
$user = "USERNAME-country-us-session-{$session}-time-10:PASSWORD";
$jar = tempnam(sys_get_temp_dir(), 'ck');
foreach (['https://example.com/', 'https://example.com/page/2'] as $url) {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_PROXY => 'http://global.nodeproxies.xyz:8080',
CURLOPT_PROXYUSERPWD => $user,
CURLOPT_COOKIEJAR => $jar,
CURLOPT_COOKIEFILE => $jar,
CURLOPT_RETURNTRANSFER => true,
]);
$html = curl_exec($ch);
curl_close($ch);
}Both requests share one IP for up to 10 minutes. Remove the session part to rotate on every request.
Parallel Requests with curl_multi
$urls = ['https://api.ipify.org', 'https://api.ipify.org', 'https://api.ipify.org'];
$mh = curl_multi_init();
$handles = [];
foreach ($urls as $i => $url) {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_PROXY => 'http://global.nodeproxies.xyz:8080',
CURLOPT_PROXYUSERPWD => 'USERNAME:PASSWORD',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
curl_multi_add_handle($mh, $ch);
$handles[$i] = $ch;
}
do {
$status = curl_multi_exec($mh, $running);
if ($running) curl_multi_select($mh);
} while ($running && $status === CURLM_OK);
foreach ($handles as $ch) {
echo curl_multi_getcontent($ch) . PHP_EOL;
curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);Each handle gets its own IP. Keep batches to a sensible size, such as 10 to 20 at a time, and add delays between batches; hammering a site gets you blocked regardless of IPs. See how to avoid blocks when web scraping.
The Same Thing in Guzzle
$client = new GuzzleHttp\Client(['timeout' => 30]);
$res = $client->get('https://api.ipify.org', [
'proxy' => 'http://USERNAME:[email protected]:8080',
]);
echo $res->getBody();Guzzle uses cURL underneath, so the same rules apply. Percent-encode special characters in the password when it's in the URL.
Measuring Where the Time Goes
When requests feel slow, curl_getinfo tells you whether the delay is the proxy or the site:
$info = curl_getinfo($ch);
printf("connect %.2fs, tls %.2fs, first byte %.2fs, total %.2fs\n",
$info['connect_time'],
$info['appconnect_time'],
$info['starttransfer_time'],
$info['total_time']);A high connect_time points at the route to the proxy. A big gap between appconnect_time and starttransfer_time means the website is slow to respond, which no proxy setting will fix. Log these numbers for a few hundred requests before changing anything.
Reusing Handles and Connections
For many sequential requests, reuse one handle and only change CURLOPT_URL between calls instead of calling curl_init every time. cURL keeps the connection to the proxy open, which saves a TCP and TLS handshake per request. Be aware that a reused tunnel to the same site keeps the same exit IP even with a rotating username. If you need a fresh IP on every request, set CURLOPT_FORBID_REUSE to true; if you want the same IP on purpose, use a session id so the behaviour doesn't depend on connection reuse.
Using PHP with NodeProxies
Set CURLOPT_PROXY to http://global.nodeproxies.xyz:8080 and pass your dashboard credentials. Scraping should stay within each site's terms and robots.txt; are proxies legal covers the ground rules. Residential proxies start at $0.65/GB; see pricing for volume tiers.
FAQ
How do I set proxy authentication in PHP cURL?
Use CURLOPT_PROXYUSERPWD with 'username:password', alongside CURLOPT_PROXY for the host and port.
What's the difference between CURLPROXY_SOCKS5 and CURLPROXY_SOCKS5_HOSTNAME?
SOCKS5 resolves DNS locally; SOCKS5_HOSTNAME lets the proxy resolve it. Use the hostname version to avoid DNS leaks.
Why does curl_exec return false with a proxy?
Read curl_error. Common causes are a refused CONNECT (407 or 402), a timeout, or a wrong host or port.
