O cURL é a forma mais usada de fazer requisições HTTP em PHP — consumir uma API, enviar dados a outro servidor, baixar o conteúdo de uma URL. Diferente do file_get_contents(), ele funciona mesmo com o allow_url_fopen desligado e dá controle total sobre a requisição: método, cabeçalhos, autenticação, tempo limite. No PHP, o cURL é usado através de quatro funções principais: curl_init(), curl_setopt(), curl_exec() e curl_close().
Este guia mostra o essencial: como montar uma requisição GET e POST, enviar cabeçalhos e JSON, lidar com autenticação, tratar erros — e, no fim, como pegar um comando curl de terminal (aqueles que aparecem na documentação de APIs) e convertê-lo em código PHP.
Uma requisição GET básica com cURL no PHP tem quatro passos:
$ch = curl_init('https://api.exemplo.com/dados');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch); O CURLOPT_RETURNTRANSFER faz o curl_exec() retornar a resposta como string, em vez de imprimi-la direto. É a opção que você quase sempre vai querer.
Conteúdo
O que é o cURL no PHP
O cURL é uma biblioteca de transferência de dados que suporta HTTP, HTTPS, FTP e vários outros protocolos. No PHP, ela é exposta pela extensão php-curl, que na maioria das hospedagens já vem ativada. Com ela, o seu código pode agir como um cliente HTTP: fazer requisições a outros servidores e receber as respostas.
É a ferramenta padrão para consumir APIs, integrar serviços externos (gateways de pagamento, envio de e-mail, redes sociais), baixar arquivos remotos e testar endpoints. Toda requisição cURL em PHP segue o mesmo esqueleto de quatro funções:
| Função | O que faz |
|---|---|
curl_init() | Inicia uma sessão cURL (opcionalmente já com a URL) |
curl_setopt() | Define as opções da requisição (método, cabeçalhos, dados…) |
curl_exec() | Executa a requisição e retorna a resposta |
curl_close() | Encerra a sessão e libera os recursos |
Requisição GET
O exemplo mais simples: buscar dados de uma URL. O ponto-chave é a opção CURLOPT_RETURNTRANSFER, que faz a resposta ser retornada como string (sem ela, o cURL imprime a resposta direto na saída):
<?php
$ch = curl_init('https://api.exemplo.com/usuarios');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch);
echo $resposta;
Requisição POST
Para enviar dados (criar um registro, submeter um formulário a uma API), você ativa o modo POST com CURLOPT_POST e passa os dados em CURLOPT_POSTFIELDS:
<?php
$ch = curl_init('https://api.exemplo.com/usuarios');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'nome' => 'Maria',
'email' => 'maria@exemplo.com',
]);
$resposta = curl_exec($ch);
curl_close($ch);
Passar um array em CURLOPT_POSTFIELDS envia os dados como formulário (application/x-www-form-urlencoded ou multipart). Para enviar JSON, veja mais abaixo.
Enviar cabeçalhos (headers)
Muitas APIs exigem cabeçalhos — um token de autenticação, o tipo de conteúdo. Use CURLOPT_HTTPHEADER com um array de strings:
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer SEU_TOKEN',
'Content-Type: application/json',
]);
Enviar JSON
O caso mais comum ao consumir APIs modernas: enviar um corpo em JSON. Você codifica os dados com json_encode(), passa o resultado em CURLOPT_POSTFIELDS e declara o Content-Type:
<?php
$dados = ['nome' => 'Maria', 'plano' => 'pro'];
$ch = curl_init('https://api.exemplo.com/usuarios');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($dados));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
]);
$resposta = curl_exec($ch);
$dadosResposta = json_decode($resposta, true);
curl_close($ch);
Autenticação básica
Para APIs que usam autenticação HTTP básica (usuário e senha), use CURLOPT_USERPWD:
curl_setopt($ch, CURLOPT_USERPWD, 'usuario:senha');
Para autenticação por token (Bearer), use o cabeçalho Authorization, como mostrado na seção de headers.
Tratar erros e ver o código de resposta
Uma requisição pode falhar (servidor fora do ar, timeout, SSL) ou retornar um status de erro (404, 500). Sempre verifique os dois:
$resposta = curl_exec($ch);
if ($resposta === false) {
// Falha na conexão (timeout, DNS, SSL...)
echo 'Erro cURL: ' . curl_error($ch);
} else {
// Requisição completou; veja o status HTTP
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "Status: $codigo";
}
curl_close($ch);
O curl_error() traz a mensagem de uma falha de conexão; o curl_getinfo() com CURLINFO_HTTP_CODE traz o status HTTP da resposta (200, 404, 500…). Uma requisição pode “ter sucesso” no cURL e ainda assim devolver um 404 — por isso os dois cheques.
Ao topar com um erro de SSL, muitos tutoriais sugerem CURLOPT_SSL_VERIFYPEER = false como “solução”. Isso desliga a verificação do certificado e abre a porta para ataques de interceptação (man-in-the-middle). Não faça isso em produção. O certo é manter a verificação ligada e, se necessário, apontar um pacote de certificados válido (CA bundle) atualizado no servidor.
Como converter um comando curl (terminal) para PHP
A documentação de muitas APIs mostra exemplos como um comando curl de terminal. Traduzir para PHP é direto quando você conhece o mapa. Veja este comando:
curl -X POST https://api.exemplo.com/pedidos \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"produto":"livro","qtd":2}' Cada parte do comando tem um equivalente em PHP:
| No terminal | No PHP |
|---|---|
-X POST | CURLOPT_POST ou CURLOPT_CUSTOMREQUEST |
-H "..." | CURLOPT_HTTPHEADER (array) |
-d '...' | CURLOPT_POSTFIELDS |
-u user:pass | CURLOPT_USERPWD |
O comando acima, traduzido para PHP, fica assim:
<?php
$ch = curl_init('https://api.exemplo.com/pedidos');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"produto":"livro","qtd":2}');
$resposta = curl_exec($ch);
curl_close($ch);
O padrão é sempre o mesmo: a URL vai no curl_init(), e cada flag do terminal (-X, -H, -d, -u) vira uma opção correspondente no curl_setopt().
Perguntas frequentes
O que é o cURL no PHP?
É a forma de fazer requisições HTTP a partir do código PHP, usando a extensão php-curl. Com ele, o seu script atua como cliente HTTP: consome APIs, envia dados a outros servidores e baixa conteúdo remoto. As requisições seguem quatro funções — curl_init(), curl_setopt(), curl_exec() e curl_close().
Como fazer uma requisição GET com cURL no PHP?
Inicie a sessão com curl_init() passando a URL, defina curl_setopt($ch, CURLOPT_RETURNTRANSFER, true) para receber a resposta como string, execute com curl_exec() e feche com curl_close(). O CURLOPT_RETURNTRANSFER é essencial: sem ele, a resposta é impressa direto na saída em vez de retornada.
Como enviar dados por POST com cURL no PHP?
Ative o POST com curl_setopt($ch, CURLOPT_POST, true) e passe os dados em CURLOPT_POSTFIELDS. Para dados de formulário, use um array. Para JSON, use json_encode() nos dados e adicione o cabeçalho Content-Type: application/json com CURLOPT_HTTPHEADER.
Como ver o código de status HTTP da resposta?
Use curl_getinfo($ch, CURLINFO_HTTP_CODE) depois do curl_exec(). Ele retorna o status HTTP (200, 404, 500…). Isso é importante porque uma requisição pode completar com sucesso no cURL e mesmo assim devolver um erro como 404 — o curl_exec() retornar false indica falha de conexão, não status de erro HTTP.
Como converter um comando curl do terminal para PHP?
Mapeie cada flag para uma opção do cURL: a URL vai no curl_init(); -X vira CURLOPT_POST ou CURLOPT_CUSTOMREQUEST; -H (cabeçalhos) vira CURLOPT_HTTPHEADER como array; -d (dados) vira CURLOPT_POSTFIELDS; e -u (autenticação) vira CURLOPT_USERPWD. O padrão de tradução é sempre o mesmo.
cURL ou file_get_contents: qual usar?
O cURL é mais completo e recomendado: funciona mesmo com o allow_url_fopen desligado e dá controle sobre método, cabeçalhos, autenticação e timeout. O file_get_contents() é mais simples para uma leitura rápida de URL, mas depende do allow_url_fopen ativo e oferece pouco controle. Para consumir APIs, prefira o cURL.
A hospedagem da Homehost já vem com a extensão cURL ativada e PHP atualizado — é só subir seu código e começar a consumir APIs e integrar serviços, com suporte em português quando precisar.
Conhecer a hospedagem HomehostConclusão
O cURL no PHP se resume a um padrão de quatro funções — curl_init(), curl_setopt(), curl_exec(), curl_close() — e a diferença entre uma requisição e outra está nas opções que você define pelo curl_setopt(): CURLOPT_POST para enviar dados, CURLOPT_HTTPHEADER para cabeçalhos, CURLOPT_POSTFIELDS para o corpo. Lembre sempre do CURLOPT_RETURNTRANSFER para receber a resposta como string, verifique tanto o curl_error() quanto o status HTTP, e nunca desligue a verificação de SSL em produção. Com esse esqueleto, você consome praticamente qualquer API — e traduzir um comando curl de documentação para PHP vira questão de mapear cada flag para a sua opção.
