Home

In computer science, a Promise is a construct that bridges the gap between procedural code and asynchronous execution. In procedural languages like PHP, functions influence program flow by either returning a value or throwing an exception, but when dealing with asynchronous operations, we can't return a value (because it isn't ready yet), and we can't throw an exception (because there's no clear place to catch it).

This is where Promises come in. Instead of returning a value or throwing an exception, an asynchronous function returns a Promise: an object that will eventually be settled by fulfilling with a value or rejecting with an error — but not immediately.

In this library, that background work is encapsulated by the Deferred class, which allows execution to be deferred while still exposing a Promise object that can be resolved or rejected later.

This implementation follows the Web API's Promise specification in terms of syntax and expected behaviour — using then, catch, and finally — but is tailored to work natively in PHP.

Note

While the API is compatible with Promises/A+, this library differs in one important way: instead of returning a new Promise with each then, catch, or finally call, it maintains and returns the same instance throughout the chain. This design keeps memory usage lower, avoids deep call stacks, and results in simpler, more predictable code — especially helpful in procedural environments like PHP.

Example Usage

A basic usage example:

$exampleSlowFileReader->read()
->then(function(string $contents) {
	echo "Contents of file: $contents", PHP_EOL;
});

A more advanced example demonstrating chaining:

$exampleRemoteApi->getCustomerById(105)
->then(function(Customer $customer) {
	return $customer->loadLatestOrders(new DateTime("-5 weeks"));
})
->then(function(CustomerOrderList $orders) {
	echo "Customer {$orders->getCustomer()->getName()} ",
	     "has made ", count($orders), " orders in the last 5 weeks!", PHP_EOL;
})
->catch(function(Throwable $reason) {
	echo "Error loading customer data: $reason", PHP_EOL;
})
->finally(function() use($exampleRemoteApi) {
	$exampleRemoteApi->disconnect();
});

---

A Promise is controlled by its Deferred counterpart - learn about Deferred and Promise objects in the next page.