GuzzleHTTP/Promises for PHP: Complete Guide with Examples

\n\n

Welcome to a detailed guide on the GuzzleHTTP/Promises library for PHP. This library is one of the key components in the Guzzle ecosystem and provides a powerful implementation of the Promise pattern for asynchronous programming. If you work with HTTP requests, parallel tasks, or simply want to make your PHP code more efficient and readable — this article is for you.

\n\n

1. What It Is and Why You Need It

\n\n

GuzzleHTTP/Promises is a PHP library that implements the concept of Promises and asynchronous task execution. It is part of the Guzzle ecosystem but can be used completely independently of the HTTP client. The main idea of promises is that you create an object representing the result of an asynchronous operation, which may be available now, later, or never. This allows you to write code that does not block program execution while waiting for long-running operations to complete.

\n\n

Why is this needed in PHP? Traditionally, PHP is a synchronous language where each operation is executed sequentially. However, with the growing popularity of microservices, API integrations, and working with external services, the need for efficient management of parallel tasks has emerged. GuzzleHTTP/Promises solves this problem by allowing you to run multiple operations simultaneously (for example, several HTTP requests to different APIs) and process their results as they complete, without waiting for each one to finish in sequence.

\n\n

The library provides a full set of tools for working with asynchronous code: creating promises, combining them, chaining calls, error handling, and timeout management. It is the de facto standard for asynchronous work in the PHP community and is used in popular projects such as Laravel, Symfony, WordPress (via plugins), and of course, the Guzzle HTTP client itself.

\n\n

2. Installation

\n\n

Installation of the library is done via Composer, the standard package manager for PHP. Run the following command in the terminal in the root of your project:

\n\n

composer require guzzlehttp/promises

\n\n

If you are using the Guzzle HTTP client, the promises library is already included in its dependencies, and separate installation is not required. After installation, make sure the vendor/autoload.php file is included in your script:

\n\n

require 'vendor/autoload.php';

\n\n

3. Quick Start — Minimal Working Example

\n\n

Let's create a simple example of working with promises. We will create a promise that "resolves" after 1 second and returns the string "Hello, World!":

\n\n

use GuzzleHttp\\Promise\\Promise;\nuse GuzzleHttp\\Promise\\Utils;\n\n// Create a new promise\n$promise = new Promise(function () use (&$promise) {\n    // Simulate an asynchronous operation\n    usleep(1000000); // 1 second\n    $promise->resolve('Hello, World!');\n});\n\n// Add a handler for successful resolution\n$promise->then(function ($value) {\n    echo "Received: " . $value . PHP_EOL;\n});\n\n// Start the promise execution\nUtils::queue()->add(function () use ($promise) {\n    $promise->wait();\n});\n\n// Run the queue\nUtils::queue()->run();

\n\n

This example demonstrates the basic mechanics: creating a promise, resolving it, and handling the result via the then method.

\n\n