Documentation

Promise

Interfaces

PromiseInterface: A promise represents the eventual result of an asynchronous operation.
PromisorInterface: Interface used with classes that return a promise.
TaskQueueInterface
PromiseInterface: A promise represents the eventual result of an asynchronous operation.
PromisorInterface: Interface used with classes that return a promise.
TaskQueueInterface

Classes

AggregateException: Exception thrown when too many errors occur in the some() or any() methods.
CancellationException: Exception that is set as the reason for a promise that has been cancelled.
Coroutine: Creates a promise that is resolved using a generator that yields values or promises (somewhat similar to C#'s async keyword).
Create
Each
EachPromise: Represents a promise that iterates over many promises and invokes side-effect functions in the process.
FulfilledPromise: A promise that has been fulfilled.
Is
Promise: Promises/A+ implementation that avoids recursion when possible.
RejectedPromise: A promise that has been rejected.
RejectionException: A special exception that is thrown when waiting on a rejected promise.
TaskQueue: A task queue that executes tasks in a FIFO order.
Utils
AggregateException: Exception thrown when too many errors occur in the some() or any() methods.
CancellationException: Exception that is set as the reason for a promise that has been cancelled.
Coroutine: Creates a promise that is resolved using a generator that yields values or promises (somewhat similar to C#'s async keyword).
Create
Each
EachPromise: Represents a promise that iterates over many promises and invokes side-effect functions in the process.
FulfilledPromise: A promise that has been fulfilled.
Is
Promise: Promises/A+ implementation that avoids recursion when possible.
RejectedPromise: A promise that has been rejected.
RejectionException: A special exception that is thrown when waiting on a rejected promise.
TaskQueue: A task queue that executes tasks in a FIFO order.
Utils

Functions

queue() : TaskQueueInterface: Get the global task queue used for promise resolution.
task() : PromiseInterface: Adds a function to run in the task queue when it is next `run()` and returns a promise that is fulfilled or rejected with the result.
promise_for() : PromiseInterface: Creates a promise for a value if the value is not a promise.
rejection_for() : PromiseInterface: Creates a rejected promise for a reason if the reason is not a promise. If the provided reason is a promise, then it is returned as-is.
exception_for() : Exception|Throwable: Create an exception for a rejected promise value.
iter_for() : Iterator: Returns an iterator for the given value.
inspect() : array<string|int, mixed>: Synchronously waits on a promise to resolve and returns an inspection state array.
inspect_all() : array<string|int, mixed>: Waits on all of the provided promises, but does not unwrap rejected promises as thrown exception.
unwrap() : array<string|int, mixed>: Waits on all of the provided promises and returns the fulfilled values.
all() : PromiseInterface: Given an array of promises, return a promise that is fulfilled when all the items in the array are fulfilled.
some() : PromiseInterface: Initiate a competitive race between multiple promises or values (values will become immediately fulfilled promises).
any() : PromiseInterface: Like some(), with 1 as count. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.
settle() : PromiseInterface: Returns a promise that is fulfilled when all of the provided promises have been fulfilled or rejected.
each() : PromiseInterface: Given an iterator that yields promises or values, returns a promise that is fulfilled with a null value when the iterator has been consumed or the aggregate promise has been fulfilled or rejected.
each_limit() : PromiseInterface: Like each, but only allows a certain number of outstanding promises at any given time.
each_limit_all() : PromiseInterface: Like each_limit, but ensures that no promise in the given $iterable argument is rejected. If any promise is rejected, then the aggregate promise is rejected with the encountered rejection.
is_fulfilled() : bool: Returns true if a promise is fulfilled.
is_rejected() : bool: Returns true if a promise is rejected.
is_settled() : bool: Returns true if a promise is fulfilled or rejected.
coroutine() : PromiseInterface: Create a new coroutine.
queue() : TaskQueueInterface: Get the global task queue used for promise resolution.
task() : PromiseInterface: Adds a function to run in the task queue when it is next `run()` and returns a promise that is fulfilled or rejected with the result.
promise_for() : PromiseInterface: Creates a promise for a value if the value is not a promise.
rejection_for() : PromiseInterface: Creates a rejected promise for a reason if the reason is not a promise. If the provided reason is a promise, then it is returned as-is.
exception_for() : Exception|Throwable: Create an exception for a rejected promise value.
iter_for() : Iterator: Returns an iterator for the given value.
inspect() : array<string|int, mixed>: Synchronously waits on a promise to resolve and returns an inspection state array.
inspect_all() : array<string|int, mixed>: Waits on all of the provided promises, but does not unwrap rejected promises as thrown exception.
unwrap() : array<string|int, mixed>: Waits on all of the provided promises and returns the fulfilled values.
all() : PromiseInterface: Given an array of promises, return a promise that is fulfilled when all the items in the array are fulfilled.
some() : PromiseInterface: Initiate a competitive race between multiple promises or values (values will become immediately fulfilled promises).
any() : PromiseInterface: Like some(), with 1 as count. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.
settle() : PromiseInterface: Returns a promise that is fulfilled when all of the provided promises have been fulfilled or rejected.
each() : PromiseInterface: Given an iterator that yields promises or values, returns a promise that is fulfilled with a null value when the iterator has been consumed or the aggregate promise has been fulfilled or rejected.
each_limit() : PromiseInterface: Like each, but only allows a certain number of outstanding promises at any given time.
each_limit_all() : PromiseInterface: Like each_limit, but ensures that no promise in the given $iterable argument is rejected. If any promise is rejected, then the aggregate promise is rejected with the encountered rejection.
is_fulfilled() : bool: Returns true if a promise is fulfilled.
is_rejected() : bool: Returns true if a promise is rejected.
is_settled() : bool: Returns true if a promise is fulfilled or rejected.
coroutine() : PromiseInterface: Create a new coroutine.

queue()

Get the global task queue used for promise resolution.

queue will be removed in guzzlehttp/promises:2.0. Use Utils::queue instead.


    
                    queue([TaskQueueInterface $assign = null ]) : TaskQueueInterface

This task queue MUST be run in an event loop in order for promises to be settled asynchronously. It will be automatically run when synchronously waiting on a promise.


while ($eventLoop->isRunning()) {
    GuzzleHttp\Promise\queue()->run();
}

Parameters

$assign : TaskQueueInterface = null: Optionally specify a new queue instance.

Return values

TaskQueueInterface

task()

Adds a function to run in the task queue when it is next `run()` and returns a promise that is fulfilled or rejected with the result.

task will be removed in guzzlehttp/promises:2.0. Use Utils::task instead.


    
                    task(callable $task) : PromiseInterface

Parameters

$task : callable: Task function to run.

Return values

PromiseInterface

promise_for()

Creates a promise for a value if the value is not a promise.

promise_for will be removed in guzzlehttp/promises:2.0. Use Create::promiseFor instead.


    
                    promise_for(mixed $value) : PromiseInterface

Parameters

$value : mixed: Promise or value.

Return values

PromiseInterface

rejection_for()

Creates a rejected promise for a reason if the reason is not a promise. If the provided reason is a promise, then it is returned as-is.

rejection_for will be removed in guzzlehttp/promises:2.0. Use Create::rejectionFor instead.


    
                    rejection_for(mixed $reason) : PromiseInterface

Parameters

$reason : mixed: Promise or reason.

Return values

PromiseInterface

exception_for()

Create an exception for a rejected promise value.

exception_for will be removed in guzzlehttp/promises:2.0. Use Create::exceptionFor instead.


    
                    exception_for(mixed $reason) : Exception|Throwable

Parameters

$reason : mixed

Return values

Exception|Throwable

iter_for()

Returns an iterator for the given value.

iter_for will be removed in guzzlehttp/promises:2.0. Use Create::iterFor instead.


    
                    iter_for(mixed $value) : Iterator

Parameters

$value : mixed

Return values

Iterator

inspect()

Synchronously waits on a promise to resolve and returns an inspection state array.

inspect will be removed in guzzlehttp/promises:2.0. Use Utils::inspect instead.


    
                    inspect(PromiseInterface $promise) : array<string|int, mixed>

Returns a state associative array containing a "state" key mapping to a valid promise state. If the state of the promise is "fulfilled", the array will contain a "value" key mapping to the fulfilled value of the promise. If the promise is rejected, the array will contain a "reason" key mapping to the rejection reason of the promise.

Parameters

$promise : PromiseInterface: Promise or value.

Return values

array<string|int, mixed>

inspect_all()

Waits on all of the provided promises, but does not unwrap rejected promises as thrown exception.

inspect will be removed in guzzlehttp/promises:2.0. Use Utils::inspectAll instead.


    
                    inspect_all(array<string|int, PromiseInterface> $promises) : array<string|int, mixed>

Returns an array of inspection state arrays.

Parameters

$promises : array<string|int, PromiseInterface>: Traversable of promises to wait upon.

Return values

array<string|int, mixed>

unwrap()

Waits on all of the provided promises and returns the fulfilled values.

unwrap will be removed in guzzlehttp/promises:2.0. Use Utils::unwrap instead.


    
                    unwrap(iterable<string|int, PromiseInterface> $promises) : array<string|int, mixed>

Returns an array that contains the value of each promise (in the same order the promises were provided). An exception is thrown if any of the promises are rejected.

Parameters

$promises : iterable<string|int, PromiseInterface>: Iterable of PromiseInterface objects to wait on.

Return values

array<string|int, mixed>

all()

Given an array of promises, return a promise that is fulfilled when all the items in the array are fulfilled.

all will be removed in guzzlehttp/promises:2.0. Use Utils::all instead.


    
                    all(mixed $promises[, bool $recursive = false ]) : PromiseInterface

The promise's fulfillment value is an array with fulfillment values at respective positions to the original array. If any promise in the array rejects, the returned promise is rejected with the rejection reason.

Parameters

$promises : mixed: Promises or values.
$recursive : bool = false: If true, resolves new promises that might have been added to the stack during its own resolution.

Return values

PromiseInterface

some()

Initiate a competitive race between multiple promises or values (values will become immediately fulfilled promises).

some will be removed in guzzlehttp/promises:2.0. Use Utils::some instead.


    
                    some(int $count, mixed $promises) : PromiseInterface

When count amount of promises have been fulfilled, the returned promise is fulfilled with an array that contains the fulfillment values of the winners in order of resolution.

This promise is rejected with a AggregateException if the number of fulfilled promises is less than the desired $count.

Parameters

$count : int: Total number of promises.
$promises : mixed: Promises or values.

Return values

PromiseInterface

any()

Like some(), with 1 as count. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.

any will be removed in guzzlehttp/promises:2.0. Use Utils::any instead.


    
                    any(mixed $promises) : PromiseInterface

Parameters

$promises : mixed: Promises or values.

Return values

PromiseInterface

settle()

Returns a promise that is fulfilled when all of the provided promises have been fulfilled or rejected.

settle will be removed in guzzlehttp/promises:2.0. Use Utils::settle instead.


    
                    settle(mixed $promises) : PromiseInterface

The returned promise is fulfilled with an array of inspection state arrays.

Parameters

$promises : mixed: Promises or values.

Return values

PromiseInterface

each()

Given an iterator that yields promises or values, returns a promise that is fulfilled with a null value when the iterator has been consumed or the aggregate promise has been fulfilled or rejected.

each will be removed in guzzlehttp/promises:2.0. Use Each::of instead.


    
                    each(mixed $iterable[, callable $onFulfilled = null ][, callable $onRejected = null ]) : PromiseInterface

$onFulfilled is a function that accepts the fulfilled value, iterator index, and the aggregate promise. The callback can invoke any necessary side effects and choose to resolve or reject the aggregate if needed.

$onRejected is a function that accepts the rejection reason, iterator index, and the aggregate promise. The callback can invoke any necessary side effects and choose to resolve or reject the aggregate if needed.

Parameters

$iterable : mixed: Iterator or array to iterate over.
$onFulfilled : callable = null
$onRejected : callable = null

Return values

PromiseInterface

each_limit()

Like each, but only allows a certain number of outstanding promises at any given time.

each_limit will be removed in guzzlehttp/promises:2.0. Use Each::ofLimit instead.


    
                    each_limit(mixed $iterable, int|callable $concurrency[, callable $onFulfilled = null ][, callable $onRejected = null ]) : PromiseInterface

$concurrency may be an integer or a function that accepts the number of pending promises and returns a numeric concurrency limit value to allow for dynamic a concurrency size.

Parameters

$iterable : mixed
$concurrency : int|callable
$onFulfilled : callable = null
$onRejected : callable = null

Return values

PromiseInterface

each_limit_all()

Like each_limit, but ensures that no promise in the given $iterable argument is rejected. If any promise is rejected, then the aggregate promise is rejected with the encountered rejection.

each_limit_all will be removed in guzzlehttp/promises:2.0. Use Each::ofLimitAll instead.


    
                    each_limit_all(mixed $iterable, int|callable $concurrency[, callable $onFulfilled = null ]) : PromiseInterface

Parameters

$iterable : mixed
$concurrency : int|callable
$onFulfilled : callable = null

Return values

PromiseInterface

is_fulfilled()

Returns true if a promise is fulfilled.

is_fulfilled will be removed in guzzlehttp/promises:2.0. Use Is::fulfilled instead.


    
                    is_fulfilled(PromiseInterface $promise) : bool

Parameters

$promise : PromiseInterface

Return values

bool

is_rejected()

Returns true if a promise is rejected.

is_rejected will be removed in guzzlehttp/promises:2.0. Use Is::rejected instead.


    
                    is_rejected(PromiseInterface $promise) : bool

Parameters

$promise : PromiseInterface

Return values

bool

is_settled()

Returns true if a promise is fulfilled or rejected.

is_settled will be removed in guzzlehttp/promises:2.0. Use Is::settled instead.


    
                    is_settled(PromiseInterface $promise) : bool

Parameters

$promise : PromiseInterface

Return values

bool

coroutine()

Create a new coroutine.

coroutine will be removed in guzzlehttp/promises:2.0. Use Coroutine::of instead.


    
                    coroutine(callable $generatorFn) : PromiseInterface

Parameters

$generatorFn : callable

Return values

PromiseInterface

queue()

Get the global task queue used for promise resolution.

queue will be removed in guzzlehttp/promises:2.0. Use Utils::queue instead.


    
                    queue([TaskQueueInterface $assign = null ]) : TaskQueueInterface

This task queue MUST be run in an event loop in order for promises to be settled asynchronously. It will be automatically run when synchronously waiting on a promise.


while ($eventLoop->isRunning()) {
    GuzzleHttp\Promise\queue()->run();
}

Parameters

$assign : TaskQueueInterface = null: Optionally specify a new queue instance.

Return values

TaskQueueInterface

task()

Adds a function to run in the task queue when it is next `run()` and returns a promise that is fulfilled or rejected with the result.

task will be removed in guzzlehttp/promises:2.0. Use Utils::task instead.


    
                    task(callable $task) : PromiseInterface

Parameters

$task : callable: Task function to run.

Return values

PromiseInterface

promise_for()

Creates a promise for a value if the value is not a promise.

promise_for will be removed in guzzlehttp/promises:2.0. Use Create::promiseFor instead.


    
                    promise_for(mixed $value) : PromiseInterface

Parameters

$value : mixed: Promise or value.

Return values

PromiseInterface

rejection_for()

Creates a rejected promise for a reason if the reason is not a promise. If the provided reason is a promise, then it is returned as-is.

rejection_for will be removed in guzzlehttp/promises:2.0. Use Create::rejectionFor instead.


    
                    rejection_for(mixed $reason) : PromiseInterface

Parameters

$reason : mixed: Promise or reason.

Return values

PromiseInterface

exception_for()

Create an exception for a rejected promise value.

exception_for will be removed in guzzlehttp/promises:2.0. Use Create::exceptionFor instead.


    
                    exception_for(mixed $reason) : Exception|Throwable

Parameters

$reason : mixed

Return values

Exception|Throwable

iter_for()

Returns an iterator for the given value.

iter_for will be removed in guzzlehttp/promises:2.0. Use Create::iterFor instead.


    
                    iter_for(mixed $value) : Iterator

Parameters

$value : mixed

Return values

Iterator

inspect()

Synchronously waits on a promise to resolve and returns an inspection state array.

inspect will be removed in guzzlehttp/promises:2.0. Use Utils::inspect instead.


    
                    inspect(PromiseInterface $promise) : array<string|int, mixed>

Parameters

$promise : PromiseInterface: Promise or value.

Return values

array<string|int, mixed>

inspect_all()

Waits on all of the provided promises, but does not unwrap rejected promises as thrown exception.

inspect will be removed in guzzlehttp/promises:2.0. Use Utils::inspectAll instead.


    
                    inspect_all(array<string|int, PromiseInterface> $promises) : array<string|int, mixed>

Returns an array of inspection state arrays.

Parameters

$promises : array<string|int, PromiseInterface>: Traversable of promises to wait upon.

Return values

array<string|int, mixed>

unwrap()

Waits on all of the provided promises and returns the fulfilled values.

unwrap will be removed in guzzlehttp/promises:2.0. Use Utils::unwrap instead.


    
                    unwrap(iterable<string|int, PromiseInterface> $promises) : array<string|int, mixed>

Returns an array that contains the value of each promise (in the same order the promises were provided). An exception is thrown if any of the promises are rejected.

Parameters

$promises : iterable<string|int, PromiseInterface>: Iterable of PromiseInterface objects to wait on.

Return values

array<string|int, mixed>

all()

Given an array of promises, return a promise that is fulfilled when all the items in the array are fulfilled.

all will be removed in guzzlehttp/promises:2.0. Use Utils::all instead.


    
                    all(mixed $promises[, bool $recursive = false ]) : PromiseInterface

Parameters

$promises : mixed: Promises or values.
$recursive : bool = false: If true, resolves new promises that might have been added to the stack during its own resolution.

Return values

PromiseInterface

some()

Initiate a competitive race between multiple promises or values (values will become immediately fulfilled promises).

some will be removed in guzzlehttp/promises:2.0. Use Utils::some instead.


    
                    some(int $count, mixed $promises) : PromiseInterface

When count amount of promises have been fulfilled, the returned promise is fulfilled with an array that contains the fulfillment values of the winners in order of resolution.

This promise is rejected with a AggregateException if the number of fulfilled promises is less than the desired $count.

Parameters

$count : int: Total number of promises.
$promises : mixed: Promises or values.

Return values

PromiseInterface

any()

Like some(), with 1 as count. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.

any will be removed in guzzlehttp/promises:2.0. Use Utils::any instead.


    
                    any(mixed $promises) : PromiseInterface

Parameters

$promises : mixed: Promises or values.

Return values

PromiseInterface

settle()

Returns a promise that is fulfilled when all of the provided promises have been fulfilled or rejected.

settle will be removed in guzzlehttp/promises:2.0. Use Utils::settle instead.


    
                    settle(mixed $promises) : PromiseInterface

The returned promise is fulfilled with an array of inspection state arrays.

Parameters

$promises : mixed: Promises or values.

Return values

PromiseInterface

each()

Given an iterator that yields promises or values, returns a promise that is fulfilled with a null value when the iterator has been consumed or the aggregate promise has been fulfilled or rejected.

each will be removed in guzzlehttp/promises:2.0. Use Each::of instead.


    
                    each(mixed $iterable[, callable $onFulfilled = null ][, callable $onRejected = null ]) : PromiseInterface

Parameters

$iterable : mixed: Iterator or array to iterate over.
$onFulfilled : callable = null
$onRejected : callable = null

Return values

PromiseInterface

each_limit()

Like each, but only allows a certain number of outstanding promises at any given time.

each_limit will be removed in guzzlehttp/promises:2.0. Use Each::ofLimit instead.


    
                    each_limit(mixed $iterable, int|callable $concurrency[, callable $onFulfilled = null ][, callable $onRejected = null ]) : PromiseInterface

$concurrency may be an integer or a function that accepts the number of pending promises and returns a numeric concurrency limit value to allow for dynamic a concurrency size.

Parameters

$iterable : mixed
$concurrency : int|callable
$onFulfilled : callable = null
$onRejected : callable = null

Return values

PromiseInterface

each_limit_all()

Like each_limit, but ensures that no promise in the given $iterable argument is rejected. If any promise is rejected, then the aggregate promise is rejected with the encountered rejection.

each_limit_all will be removed in guzzlehttp/promises:2.0. Use Each::ofLimitAll instead.


    
                    each_limit_all(mixed $iterable, int|callable $concurrency[, callable $onFulfilled = null ]) : PromiseInterface

Parameters

$iterable : mixed
$concurrency : int|callable
$onFulfilled : callable = null

Return values

PromiseInterface

is_fulfilled()

Returns true if a promise is fulfilled.

is_fulfilled will be removed in guzzlehttp/promises:2.0. Use Is::fulfilled instead.


    
                    is_fulfilled(PromiseInterface $promise) : bool

Parameters

$promise : PromiseInterface

Return values

bool

is_rejected()

Returns true if a promise is rejected.

is_rejected will be removed in guzzlehttp/promises:2.0. Use Is::rejected instead.


    
                    is_rejected(PromiseInterface $promise) : bool

Parameters

$promise : PromiseInterface

Return values

bool

is_settled()

Returns true if a promise is fulfilled or rejected.

is_settled will be removed in guzzlehttp/promises:2.0. Use Is::settled instead.


    
                    is_settled(PromiseInterface $promise) : bool

Parameters

$promise : PromiseInterface

Return values

bool

coroutine()

Create a new coroutine.

coroutine will be removed in guzzlehttp/promises:2.0. Use Coroutine::of instead.


    
                    coroutine(callable $generatorFn) : PromiseInterface

Parameters

$generatorFn : callable

Return values

PromiseInterface

Promise

Table of Contents

Interfaces

Classes

Functions

Functions

queue()

Parameters

Return values

task()

Parameters

Return values

promise_for()

Parameters

Return values

rejection_for()

Parameters

Return values

exception_for()

Parameters

Return values

iter_for()

Parameters

Return values

inspect()

Parameters

Return values

inspect_all()

Parameters

Tags

Return values

unwrap()

Parameters

Tags

Return values

all()

Parameters

Return values

some()

Parameters

Return values

any()

Parameters

Return values

settle()

Parameters

Tags

Return values

each()

Parameters

Return values

each_limit()

Parameters

Return values

each_limit_all()

Parameters

Return values

is_fulfilled()

Parameters

Return values

is_rejected()

Parameters

Return values

is_settled()