Consumindo APIs Externas com Guzzle em PHP na Prática Já leu

Introdução ao Guzzle: O Cliente HTTP Essencial

Guzzle é a biblioteca HTTP mais popular em PHP para consumir APIs externas. Com uma API intuitiva, suporte a requisições síncronas e assíncronas, além de gerenciamento automático de redirecionamentos e autenticação, ela se tornou padrão na comunidade PHP. Neste artigo, você aprenderá a instalação, implementação e boas práticas para trabalhar com APIs externas de forma profissional e segura.

Instalação e Configuração Básica

Instalando via Composer

O Guzzle é instalado através do Composer, gerenciador de dependências do PHP. Execute o comando abaixo no seu projeto:

composer require guzzlehttp/guzzle

Isso adicionará a dependência ao seu composer.json e criará a pasta vendor/. Para usar o Guzzle, basta importar a classe principal:

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

use GuzzleHttp\Client;

$client = new Client();

Dica profissional: Sempre especifique a versão mínima no composer.json para evitar quebras inesperadas. Atualmente, a versão 7.x é a recomendada para PHP 7.2+.

Criando seu Primeiro Cliente

Criar um cliente Guzzle é simples. Você pode definir uma URL base e outras configurações globais que serão aplicadas a todas as requisições:

$client = new Client([
    'base_uri' => 'https://api.exemplo.com/',
    'timeout'  => 5.0,
    'headers'  => [
        'Accept' => 'application/json',
        'User-Agent' => 'MeuApp/1.0'
    ]
]);

Realizando Requisições HTTP

Métodos HTTP Comuns

O Guzzle oferece métodos simplificados para cada verbo HTTP. As requisições mais comuns são GET, POST, PUT e DELETE:

// GET - Recuperar dados
$response = $client->get('usuarios/123');

// POST - Criar recurso
$response = $client->post('usuarios', [
    'json' => [
        'nome' => 'João Silva',
        'email' => 'joao@exemplo.com'
    ]
]);

// PUT - Atualizar recurso
$response = $client->put('usuarios/123', [
    'json' => ['nome' => 'João Santos']
]);

// DELETE - Remover recurso
$response = $client->delete('usuarios/123');

Acessando a Resposta

Toda requisição retorna um objeto Response. Você pode acessar o status, headers e body da seguinte forma:

$response = $client->get('usuarios');

// Status HTTP
$statusCode = $response->getStatusCode(); // Ex: 200

// Corpo como string
$body = $response->getBody()->getContents();

// Decodificar JSON automaticamente
$data = json_decode($body, true);

// Acessar headers específicos
$contentType = $response->getHeader('Content-Type');

Uma abordagem mais limpa é usar o parâmetro de opção para decodificar JSON automaticamente na resposta (requer Guzzle 7+):

// Retorna PSR-7 response e você decodifica manualmente
$response = $client->request('GET', 'usuarios', [
    'headers' => ['Accept' => 'application/json']
]);

$dados = json_decode($response->getBody(), true);

Tratamento de Erros e Autenticação

Capturando Exceções

Por padrão, Guzzle lança exceções para status HTTP 4xx e 5xx. Você deve sempre envolver suas requisições em try-catch:

use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\ServerException;
use GuzzleHttp\Exception\ConnectException;

try {
    $response = $client->get('usuarios/999');
    $dados = json_decode($response->getBody(), true);
} catch (ClientException $e) {
    // Erro 4xx (erro do cliente)
    echo "Erro do cliente: " . $e->getResponse()->getStatusCode();
} catch (ServerException $e) {
    // Erro 5xx (erro do servidor)
    echo "Erro do servidor: " . $e->getResponse()->getStatusCode();
} catch (ConnectException $e) {
    // Erro de conexão
    echo "Falha na conexão: " . $e->getMessage();
}

Autenticação com Tokens e Chaves

APIs frequentemente exigem autenticação. O Guzzle oferece opções simples para isso:

// Autenticação HTTP Basic
$client = new Client([
    'base_uri' => 'https://api.exemplo.com/',
    'auth' => ['usuario', 'senha']
]);

// Token Bearer (JWT ou similar)
$client = new Client([
    'base_uri' => 'https://api.exemplo.com/',
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ]
]);

// API Key no header
$client = new Client([
    'base_uri' => 'https://api.exemplo.com/',
    'headers' => [
        'X-API-Key' => 'sua-chave-api'
    ]
]);

Exemplo Prático Completo

Vamos consumir a API pública JSONPlaceholder para recuperar posts:

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

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

$client = new Client([
    'base_uri' => 'https://jsonplaceholder.typicode.com/',
    'timeout' => 5.0
]);

try {
    // GET de posts
    $response = $client->get('posts/1');
    $post = json_decode($response->getBody(), true);

    echo "Título: " . $post['title'] . "\n";
    echo "Corpo: " . $post['body'] . "\n";

    // POST de novo recurso
    $novoPost = $client->post('posts', [
        'json' => [
            'title' => 'Novo Post',
            'body' => 'Conteúdo do post',
            'userId' => 1
        ]
    ]);

    $resultado = json_decode($novoPost->getBody(), true);
    echo "Post criado com ID: " . $resultado['id'] . "\n";

} catch (GuzzleException $e) {
    echo "Erro na requisição: " . $e->getMessage();
}

Boas Práticas Profissionais

Encapsulamento e Reutilização

Em aplicações reais, crie uma classe dedicada para consumir sua API:

<?php
namespace App\Services;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

class UsuarioAPIService
{
    private $client;

    public function __construct(string $apiToken)
    {
        $this->client = new Client([
            'base_uri' => 'https://api.exemplo.com/',
            'headers' => ['Authorization' => 'Bearer ' . $apiToken],
            'timeout' => 5.0
        ]);
    }

    public function obterUsuario(int $id): array
    {
        try {
            $response = $this->client->get("usuarios/{$id}");
            return json_decode($response->getBody(), true);
        } catch (GuzzleException $e) {
            throw new \Exception("Erro ao obter usuário: " . $e->getMessage());
        }
    }

    public function criarUsuario(array $dados): array
    {
        $response = $this->client->post('usuarios', ['json' => $dados]);
        return json_decode($response->getBody(), true);
    }
}

Configurações Sensíveis em Variáveis de Ambiente

Nunca coloque tokens e URLs de API diretamente no código. Use variáveis de ambiente:

$client = new Client([
    'base_uri' => getenv('API_BASE_URI'),
    'headers' => ['Authorization' => 'Bearer ' . getenv('API_TOKEN')],
    'timeout' => 5.0
]);

Crie um arquivo .env (não versionado no Git):

API_BASE_URI=https://api.exemplo.com/
API_TOKEN=seu_token_secreto_aqui

Conclusão

Você agora domina os fundamentos do Guzzle para consumir APIs externas em PHP. Os pontos principais aprendidos foram: (1) instalação e configuração básica com URL base e headers globais para evitar repetição; (2) realização de requisições HTTP (GET, POST, PUT, DELETE) e acesso correto à resposta JSON; (3) tratamento robusto de exceções e implementação segura de autenticação com tokens. Use sempre classes de serviço para encapsular requisições e mantenha dados sensíveis em variáveis de ambiente. Na prática profissional, essas práticas garantem código mantível, testável e seguro.

Referências

• Documentação oficial do Guzzle
• PSR-7: HTTP Message Interface
• JSONPlaceholder - API Fake para Testes
• Composer - PHP Dependency Manager
• PHP: Variáveis de Ambiente