Introdução ao cURL: Como fazer requisições HTTP em PHP

É comum em aplicações WEB ter a necessidade de se comunicar com outras aplicações, seja por APIs, protocolo FTP ou até mesmo, enviar dados via POST. Independente do protocolo e do verbo utilizado, ter uma boa ferramenta é fundamental neste processo.

Podemos fazer requisições get utilizando a função file_get_contents do PHP, porém ela é extremamente limitada e não é recomendada para requisições fora do servidor, devido a falta de parâmetros necessários, como cabeçalhos e definição de protocolo.

O PHP como uma poderosa linguagem faz uso da biblioteca cURL (Client URL), com ela a gente pode fazer requisições passando credenciais de segurança, como Bearer, cabeçalhos, definir o tipo de protocolo como GET ou POST, por exemplo, enviar dados para a aplicação, dentre muitas outras possibilidades.

Não é o assunto do artigo, mas também podemos utilizar uma biblioteca chamada Guzzle que torna o processo mais simplificado. O Guzzle é uma biblioteca de cliente HTTP em PHP que aproveita o cURL como um dos seus adaptadores de transporte padrão para realizar requisições HTTP.

O que é o cURL?

O cURL é uma biblioteca e uma ferramenta de linha de comando usada para transferir dados com URLs, sendo amplamente utilizada no desenvolvimento web, muito popular no PHP. Ele foi desenvolvido originalmente por Daniel Stenberg e teve seu início no final da década de 1990, hoje é mantido pela comunidade Open Source. Originalmente, Stenberg criou o cURL como um projeto pessoal para preencher uma necessidade que ele encontrou ao tentar fazer transferências de arquivos pela web. Com o tempo, o cURL ganhou popularidade e foi adotado por uma ampla comunidade de desenvolvedores devido à sua flexibilidade e suporte a uma variedade de protocolos de transferência, incluindo HTTP, FTP, SCP e dentre outros. O cURL é amplamente utilizado em aplicações de automação, integração de APIs, transferência de arquivos e é uma ferramenta essencial para desenvolvedores que precisam interagir com recursos online de forma eficiente, segura e confiável.

A evolução do cURL ao longo dos anos resultou em uma ferramenta poderosa e de código aberto, que continua a ser mantida e aprimorada pela comunidade de desenvolvedores. Sua natureza versátil e a capacidade de ser facilmente integrada em diversas linguagens de programação, incluindo o PHP, fizeram do cURL uma escolha fundamental para projetos de desenvolvimento web que envolvem comunicação com servidores e serviços remotos.

Instalando o cURL

Por padrão o cURL já vem instalado quando utilizamos o PHP, porém pode acontecer dele não estar presente em sistemas Linux ou Windows.

Habilitando o cURL no PHP usando o Windows

Tudo o que você precisa fazer é adicionar a linha abaixo no seu arquivo php.ini, que é um arquivo de configurações do PHP. Certifique-se de que a linha não esteja apenas comentada com // (barras), caso esteja, basta removê-los. O caminho do arquivo php.ini pode variar de sistema para sistema, mas normalmente fica na pasta do PHP em php/7.x/cli/php.ini, no XAMPP ele deve ficar em C:\xampp\php\php.ini.

extension=curl

Ainda é possível que o cURL esteja ausente no sistema, para isso faça o download da DLL do cURL e instale no seu sistema.

Habilitando o cURL no PHP usando o Linux

Primeiramente certifique-se de que o cURL não esteja instalado, para isso rode o comando abaixo.

php -m | grep curl

Caso não retorne nada, então você pode refazer o passo que explicamos no Windows utilizando seu editor favorito e descomentar a linha do cURL.

Após realizar este processo reinicie seu PC por garantia. Caso o cURL ainda não esteja presente, então faça a instalação através do comando abaixo.

apt-get install curl

Requisição GET com cURL

Vamos começar o nosso primeiro exemplo realizando uma simples requisição do tipo get. GET é um verbo utilizado para consumir informações, então tudo o que precisamos é de uma URL.

Veja o nosso exemplo abaixo que consome uma API do Github, retornando todos os nossos repositórios existentes.

<?php

// URL que vamos consumir a API
$url = 'https://api.github.com/users/satellasoft';

// Inicializa a sessão cURL
$cURL = curl_init();

// Configura as opções da requisição GET

// Define a URL de destino
curl_setopt($cURL, CURLOPT_URL, $url);
// Habilita a captura da resposta, ou seja, o resultado que queremos
curl_setopt($cURL, CURLOPT_RETURNTRANSFER, true);

// Cabeçalho obrigatório para consumir a API do Github (https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#user-agent-required)
curl_setopt($cURL, CURLOPT_USERAGENT, 'cURL test');

// Executa a requisição e armazena a resposta na variável $response
$response = curl_exec($cURL);

// Verifica se ocorreu algum erro
if (curl_errno($cURL)) {
    echo sprintf('Erro na execução do cURL %s', curl_error($cURL));
} else {
    // Exibe a resposta
    echo $response;
}

// Finaliza a sessão cURL e libera o uso da biblioteca
curl_close($cURL);

Embora toda a explicação esteja nos comentários, vamos entender o passo a passo:

Definimos a URL que desejamos consultar;
Iniciamos uma sessão, ou seja, iniciamos uma instância da biblioteca;
Utilizando a função curl_setopt e com o parâmetro CURLOPT_URL definimos a nossa URL;
Utilizando a função curl_setopt e com o parâmetro CURLOPT_RETURNTRANSFER definimos que queremos obter a resposta da requisição, ou seja, o conteúdo da URL;
Utilizando a função curl_setopt e com o parâmetro CURLOPT_USERAGENT informamos qual seria o nosso “navegador”, aqui informamos o nome da nossa aplicação;
Utilizando a função curl_exec executamos a nossa biblioteca, levando em consideração todos os parâmetros especificados;
Em seguida tratamos os erros e exibimos a resposta;
Por fim, utilizando a função curl_close encerramos o uso da biblioteca.

Requisições POST com cURL

Agora vamos ver como fazer uma requisição utilizando o verbo POST, ou seja, vamos enviar dados para a nossa aplicação.

Primeiramente vamos utilizar o código abaixo como exemplo, ele vai ser a página que irá receber a nossa requisição. Chamamos esse arquivo de proc_post.php.

<?php
// Verifica se a requisição é do tipo POST
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    // Recebe os dados do corpo da requisição
    $postData = file_get_contents("php://input");

    // Converte os dados em um array associativo
    parse_str($postData, $data);

    // Verifica se a conversão foi bem-sucedida
    if ($data !== null) {
        // Exibe os dados recebidos
        echo "Dados recebidos com sucesso:";
        echo "<pre>";
        print_r($data);
        echo "</pre>";
    } else {
        echo "Erro ao processar os dados JSON. <br>";
    }
} else {
    echo "Esta página só aceita requisições POST.";
}

Note que utilizamos a função file_get_contents() com o parâmetro php://input, ele obtém os dados brutos de uma página, ou seja, podemos obter um JSON, string ou qualquer outro tipo de informação. Normalmente estamos acostumados a receber dados utilizando os arrays globais como $_POST ou $_GET, por exemplo, mas aqui eles não serão utilizados.

Vamos fazer uma análise deste código.

O código verifica se a requisição é do tipo POST usando if ($_SERVER['REQUEST_METHOD'] === 'POST');
Se for uma requisição POST, ele lê os dados brutos do corpo da requisição usando file_get_contents("php://input") e armazena-os na variável $postData;
Em seguida, ele tenta converter esses dados brutos em um array associativo usando a função parse_str($postData, $data);
Se a conversão for bem-sucedida (ou seja, se os dados brutos poderem ser interpretados como uma query string válida), ele exibe os dados recebidos em formato de array usando print_r;
Se ocorrer algum erro na conversão, ele exibirá uma mensagem de erro;
Se a requisição não for do tipo POST, ele exibirá uma mensagem informando que a página só aceita requisições POST.

Agora vamos ao nosso exemplo em cURL, veja o código completamente comentado abaixo.

<?php
//URL do endpoint de destino onde você deseja enviar os dados
$url = 'http://localhost:8000/proc_post.php';

//Os dados que você deseja enviar no corpo da requisição POST (em formato de array)
$postData = [
    'site' => 'SatellaSoft',
    'url' => 'https://satellasoft.com',
    //...
];

//Inicializa a sessão cURL
$ch = curl_init();

//Configura as opções da requisição POST

//Define a URL
curl_setopt($ch, CURLOPT_URL, $url);

//Queremos obter a resposta
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

//Define que é uma requisição do tipo POST
curl_setopt($ch, CURLOPT_POST, true);

//Enviamos os dados do nosso array no formato de query string
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));

//Executa a requisição e armazena a resposta em $response
$response = curl_exec($ch);

//Verifica se ocorreu algum erro
if (curl_errno($ch)) {
    echo 'Erro cURL: ' . curl_error($ch);
} else {
    //Processa a resposta (no exemplo, apenas exibimos a resposta)
    echo $response;
}

//Fecha a sessão cURL
curl_close($ch);

Aqui nós temos boa parte do código utilizado na requisição GET, com a adição dos parâmetros de configuração abaixo:

CURLOPT_POST - Define que é uma requisição do tipo POST;
CURLOPT_POSTFIELDS - Enviamos os dados para a nossa página, perceba que estamos convertendo nosso array em query string, ou seja, uma string especial.

No servidor obtemos a string a partir da função file_get_contents e convertemos em array associativo com o uso da função parse_str.

Adicionando Cabeçalhos Personalizados e Autenticação Bearer em Requisições cURL

Nem só de POST e GET basta, dependendo da aplicação é necessário informar cabeçalhos HTTP para diferentes funcionalidades, como, por exemplo, realizar a autenticação na aplicação.

Para este exemplo vamos utilizar um cabeçalho de autenticação do tipo Bearer, para isso declaramos um array e informamos a chave, por fim, definimos a configuração CURLOPT_HTTPHEADER com o array que criamos anteriormente. Veja o código de exemplo abaixo.

<?php
// URL da API que requer autenticação via Bearer Token
$apiUrl = 'https://exemplo.com/';

// Token de autenticação Bearer
$token = 'SeuBearerTokenAqui';

// Inicializa a sessão cURL
$cURL = curl_init($apiUrl);

// Define o cabeçalho de autenticação Bearer
$headers = [
    'Authorization: Bearer ' . $token,
];

// Configura as opções da requisição cURL
curl_setopt($cURL, CURLOPT_HTTPHEADER, $headers);
curl_setopt($cURL, CURLOPT_RETURNTRANSFER, true);

// Executa a requisição
$response = curl_exec($cURL);

// Verifica se ocorreu algum erro
if (curl_errno($cURL)) {
    echo 'Erro cURL: ' . curl_error($cURL);
} else {
    // Processa a resposta da API
    echo 'Resposta da API:';
    echo '<pre>';
    print_r(json_decode($response, true));
    echo '</pre>';
}

// Fecha a sessão cURL
curl_close($cURL);

Veja uma explicação detalhada:

O código define a URL da API que requer autenticação via Bearer Token e o token Bearer;
Uma sessão cURL é iniciada com curl_init(), usando o URL da API;
É criado um cabeçalho de autenticação Bearer no formato 'Authorization: Bearer ' . $token e armazenado no array $headers;
As opções da requisição cURL são configuradas: os cabeçalhos personalizados são definidos com CURLOPT_HTTPHEADER e a opção CURLOPT_RETURNTRANSFER é definida como true, o que significa que a resposta será armazenada em $response;
A requisição é executada com curl_exec($cURL);
É verificado se ocorreu algum erro durante a requisição. Se houver um erro, ele exibe uma mensagem de erro com a descrição do erro;
Se não houver erro, a resposta da API é processada: a resposta JSON é decodificada em um array associativo com json_decode e exibida;
A sessão cURL é encerrada com curl_close($cURL) para liberar recursos.