GuzzleHTTP/Promises para PHP: guia completo com exemplos práticos

Bem-vindo ao guia detalhado sobre a biblioteca GuzzleHTTP/Promises para PHP. Essa biblioteca é uma das peças-chave do ecossistema Guzzle e oferece uma implementação poderosa do padrão "Promise" para programação assíncrona. Se você trabalha com requisições HTTP, tarefas paralelas ou simplesmente deseja tornar seu código PHP mais eficiente e legível, este artigo é para você.

1. O que é e para que serve

GuzzleHTTP/Promises é uma biblioteca PHP que implementa o conceito de Promises (promessas) e execução assíncrona de tarefas. Ela faz parte do ecossistema Guzzle, mas pode ser usada de forma totalmente independente do cliente HTTP. A ideia principal das Promises é criar um objeto que representa o resultado de uma operação assíncrona — que pode ser obtido agora, depois ou nunca. Isso permite escrever código que não bloqueia a execução do programa enquanto aguarda a conclusão de operações demoradas.

Por que isso é necessário no PHP? Tradicionalmente, o PHP é uma linguagem síncrona, onde cada operação é executada sequencialmente. No entanto, com o crescimento dos microsserviços, integrações de API e trabalho com serviços externos, surgiu a necessidade de gerenciar tarefas paralelas de forma eficiente. O GuzzleHTTP/Promises resolve esse problema permitindo executar várias operações simultaneamente (por exemplo, várias requisições HTTP para diferentes APIs) e processar os resultados à medida que são concluídos, sem precisar esperar todas em sequência.

A biblioteca oferece um conjunto completo de ferramentas para trabalhar com código assíncrono: criação de Promises, combinação delas, encadeamento de chamadas, tratamento de erros e gerenciamento de tempo limite. Ela é o padrão de facto para trabalho assíncrono na comunidade PHP e é usada em projetos populares como Laravel, Symfony, WordPress (através de plugins) e, claro, o próprio cliente HTTP Guzzle.

2. Instalação

A instalação da biblioteca é feita via Composer, o gerenciador de pacotes padrão do PHP. Execute o seguinte comando no terminal, na raiz do seu projeto:

composer require guzzlehttp/promises

Se você já usa o cliente HTTP Guzzle, a biblioteca de Promises já está incluída nas dependências dele, e não é necessária instalação separada. Após a instalação, certifique-se de que o arquivo vendor/autoload.php está incluído no seu script:

require 'vendor/autoload.php';

3. Início rápido — exemplo mínimo funcional

Vamos criar um exemplo simples de uso de Promises. Criaremos uma Promise que é "resolvida" após 1 segundo e retorna a string "Olá, Mundo!":

use GuzzleHttp\Promise\Promise;
use GuzzleHttp\Promise\Utils;

// Cria uma nova Promise
$promise = new Promise(function () use (&$promise) {
    // Simula uma operação assíncrona
    usleep(1000000); // 1 segundo
    $promise->resolve('Olá, Mundo!');
});

// Adiciona um handler para execução bem-sucedida
$promise->then(function ($value) {
    echo "Recebido: " . $value . PHP_EOL;
});

// Inicia a execução da Promise
Utils::queue()->add(function () use ($promise) {
    $promise->wait();
});

// Executa a fila
Utils::queue()->run();

Este exemplo demonstra a mecânica básica: criação de uma Promise, sua resolução (resolve) e tratamento do resultado através do método then.

4. Principais métodos/funções/classes

Conheça 8+ componentes-chave da biblioteca com descrições detalhadas e exemplos.

4.1. Classe GuzzleHttp\Promise\Promise

Assinatura: new Promise(callable $waitFn = null, callable $canceller = null)

O que faz: Cria uma nova Promise. Opcionalmente, aceita uma função de espera ($waitFn), chamada quando o método wait() é invocado, e uma função de cancelamento ($canceller).