Configuração de proxy em PHP

A configuração de proxy em PHP para cURL, Guzzle e file_get_contents consiste em ajustar as opções do cliente HTTP ou os contextos de stream para rotear as requisições de saída através de um proxy definido, normalmente informando host, porta e credenciais de autenticação do proxy.

Usar um proxy com PHP permite que a aplicação mascare o IP de origem, contorne restrições geográficas, acesse recursos de redes internas ou controle a taxa de requisições em web scraping e integrações com API. A escolha do método depende do controle necessário, da complexidade das requisições e das necessidades de tratamento de erros.

Usando cURL

cURL é uma biblioteca robusta para fazer requisições HTTP, com controle amplo sobre os parâmetros de conexão, inclusive as configurações de proxy. É a escolha comum para interações web complexas e normalmente está disponível como extensão do PHP (php-curl).

Configuração básica de proxy

Para rotear uma requisição por um proxy HTTP ou HTTPS, use CURLOPT_PROXY e CURLOPT_PROXYPORT.

<?php
$ch = curl_init();

// URL de destino
curl_setopt($ch, CURLOPT_URL, 'http://example.com/api/data');

// Configurações do proxy
curl_setopt($ch, CURLOPT_PROXY, 'proxy.example.com');
curl_setopt($ch, CURLOPT_PROXYPORT, 8080);

// Retorna a transferência como string em vez de exibi-la diretamente
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>

Proxy SOCKS

O cURL suporta proxies SOCKS (SOCKS4, SOCKS4a, SOCKS5, SOCKS5h). Defina o tipo de proxy com CURLOPT_PROXYTYPE.

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://example.com/api/data');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Configurações do proxy SOCKS5
curl_setopt($ch, CURLOPT_PROXY, 'socks5.example.com');
curl_setopt($ch, CURLOPT_PROXYPORT, 1080);
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5); // Ou CURLPROXY_SOCKS4, CURLPROXY_SOCKS4A, CURLPROXY_SOCKS5_HOSTNAME

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>

Proxy com autenticação

Para proxies que exigem autenticação, use CURLOPT_PROXYUSERPWD com uma string username:password.

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://example.com/api/data');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Configurações do proxy com autenticação
curl_setopt($ch, CURLOPT_PROXY, 'authproxy.example.com');
curl_setopt($ch, CURLOPT_PROXYPORT, 8080);
curl_setopt($ch, CURLOPT_PROXYUSERPWD, 'proxyuser:proxypassword');

// Opcional: definir o método de autenticação do proxy (ex.: CURLAUTH_BASIC, CURLAUTH_DIGEST)
// curl_setopt($ch, CURLOPT_PROXYAUTH, CURLAUTH_BASIC);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>

Proxy HTTPS (túnel CONNECT)

Ao conectar a um destino HTTPS através de um proxy HTTP, o cURL usa o método HTTP CONNECT para abrir um túnel. CURLOPT_HTTPPROXYTUNNEL habilita isso explicitamente, embora normalmente seja tratado de forma automática.

<?php
$ch = curl_init();

// URL HTTPS de destino
curl_setopt($ch, CURLOPT_URL, 'https://secure.example.com/data');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Configurações do proxy
curl_setopt($ch, CURLOPT_PROXY, 'proxy.example.com');
curl_setopt($ch, CURLOPT_PROXYPORT, 8080);

// Habilita o túnel para HTTPS através de proxy HTTP (muitas vezes implícito)
curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, true);

// Tratamento da verificação de certificado SSL (desative para testes, ative em produção)
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); 
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>

Opções comuns do cURL para proxies

• CURLOPT_TIMEOUT: tempo máximo, em segundos, para a operação do cURL.
• CURLOPT_CONNECTTIMEOUT: tempo máximo, em segundos, para estabelecer a conexão.
• CURLOPT_FOLLOWLOCATION: segue os cabeçalhos HTTP Location:.
• CURLOPT_MAXREDIRS: número máximo de redirecionamentos a seguir.
• CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST: controlam a verificação do certificado SSL. Defina como true em produção.
• CURLOPT_HEADER: inclui o cabeçalho na saída.

Usando Guzzle

Guzzle é um cliente HTTP popular em PHP que oferece uma abstração de mais alto nível sobre o cURL, simplificando tarefas HTTP comuns. Requer instalação via Composer.

Configuração básica de proxy

Clientes e requisições do Guzzle aceitam a opção proxy. Ela pode ser definida globalmente para o cliente ou por requisição.

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    // URI base para todas as requisições feitas com este cliente
    'base_uri' => 'http://example.com/',
    // Configuração global de proxy para o cliente
    'proxy' => 'http://proxy.example.com:8080',
]);

try {
    $response = $client->request('GET', 'api/data');
    echo $response->getBody();
} catch (GuzzleHttp\Exception\RequestException $e) {
    echo 'Guzzle error: ' . $e->getMessage();
}
?>

Proxy com autenticação

Inclua as credenciais de autenticação diretamente na URI do proxy para proxies HTTP/HTTPS.

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'http://example.com/',
    // Proxy com autenticação
    'proxy' => 'http://proxyuser:[email protected]:8080',
]);

try {
    $response = $client->request('GET', 'api/data');
    echo $response->getBody();
} catch (GuzzleHttp\Exception\RequestException $e) {
    echo 'Guzzle error: ' . $e->getMessage();
}
?>

Proxy SOCKS

Indique proxies SOCKS usando o esquema socks na URI do proxy.

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'http://example.com/',
    // Proxy SOCKS5
    'proxy' => 'socks5://socks5.example.com:1080',
]);

try {
    $response = $client->request('GET', 'api/data');
    echo $response->getBody();
} catch (GuzzleHttp\Exception\RequestException $e) {
    echo 'Guzzle error: ' . $e->getMessage();
}
?>

Proxies por requisição

A opção proxy pode ser sobrescrita ou definida para requisições individuais.

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(); // Sem proxy global

try {
    $response = $client->request('GET', 'http://example.com/api/data', [
        'proxy' => 'http://perrequestproxy.example.com:8080', // Proxy apenas para esta requisição
    ]);
    echo $response->getBody();
} catch (GuzzleHttp\Exception\RequestException $e) {
    echo 'Guzzle error: ' . $e->getMessage();
}
?>

Opções comuns do Guzzle para proxies

• proxy: a string da URI do proxy (http://, https://, socks4://, socks5://).
• verify: controla a verificação do certificado SSL (true, false ou caminho para o bundle de CA).
• timeout: tempo limite total da requisição, em segundos.
• connect_timeout: tempo limite para conectar ao servidor, em segundos.
• allow_redirects: controla o tratamento de redirecionamentos (true, false ou array de opções).

Usando file_get_contents

file_get_contents é uma função simples para ler o conteúdo de arquivos, incluindo URLs. Ela pode usar contextos de stream para configurar o proxy, mas oferece menos controle e tratamento de erros que cURL ou Guzzle. É adequada para requisições HTTP/HTTPS básicas com requisitos simples de proxy.

Configuração básica de proxy

Use stream_context_create para definir as configurações de proxy dentro das opções http.

<?php
$proxy = 'tcp://proxy.example.com:8080';
$url = 'http://example.com/api/data';

$context = stream_context_create([
    'http' => [
        'proxy' => $proxy,
        'request_fulluri' => true, // Essencial para proxies HTTP
    ],
]);

$response = @file_get_contents($url, false, $context);

if ($response === false) {
    echo 'Failed to retrieve content via proxy.';
} else {
    echo $response;
}
?>

request_fulluri precisa ser true ao usar um proxy HTTP, pois instrui o cliente a enviar a URI completa na linha de requisição (ex.: GET http://example.com/path HTTP/1.0).

Proxy HTTPS

Para destinos HTTPS, o wrapper de stream https trata a configuração de proxy de forma semelhante ao http.

<?php
$proxy = 'tcp://proxy.example.com:8080';
$url = 'https://secure.example.com/data';

$context = stream_context_create([
    'http' => [ // Observação: a configuração do proxy continua sob 'http' para o túnel CONNECT
        'proxy' => $proxy,
        'request_fulluri' => true,
    ],
    'ssl' => [ // Opções de verificação SSL/TLS
        'verify_peer' => false, // Desative para testes, ative em produção
        'verify_peer_name' => false,
    ],
]);

$response = @file_get_contents($url, false, $context);

if ($response === false) {
    echo 'Failed to retrieve content via proxy.';
} else {
    echo $response;
}
?>

Proxy com autenticação

A autenticação de proxy no file_get_contents normalmente é feita definindo manualmente o cabeçalho Proxy-Authorization nas opções do contexto http.

<?php
$proxy = 'tcp://proxy.example.com:8080';
$url = 'http://example.com/api/data';
$proxyUser = 'proxyuser';
$proxyPass = 'proxypassword';

// Codifica em Base64 o username:password para autenticação Basic
$authHeader = 'Proxy-Authorization: Basic ' . base64_encode("$proxyUser:$proxyPass");

$context = stream_context_create([
    'http' => [
        'proxy' => $proxy,
        'request_fulluri' => true,
        'header' => $authHeader,
    ],
]);

$response = @file_get_contents($url, false, $context);

if ($response === false) {
    echo 'Failed to retrieve content via proxy.';
} else {
    echo $response;
}
?>

Limitações do file_get_contents com proxies

• Sem suporte a proxy SOCKS: os stream wrappers do PHP não suportam SOCKS nativamente.
• Tratamento de erros limitado: as informações de erro são mínimas, restritas a warnings ou ao retorno false.
• Menos controle: o controle granular sobre cabeçalhos, timeouts e redirecionamentos é menos flexível.
• Desempenho: pode ser menos performático em requisições concorrentes ou numerosas em comparação ao cURL.

Comparação dos métodos de proxy em PHP