1<?php
2
3declare(strict_types=1);
4
5namespace GuzzleHttp\Promise;
6
7/**
8 * A promise represents the eventual result of an asynchronous operation.
9 *
10 * The primary way of interacting with a promise is through its then method,
11 * which registers callbacks to receive either a promise’s eventual value or
12 * the reason why the promise cannot be fulfilled.
13 *
14 * @see https://promisesaplus.com/
15 */
16interface PromiseInterface
17{
18    public const PENDING = 'pending';
19    public const FULFILLED = 'fulfilled';
20    public const REJECTED = 'rejected';
21
22    /**
23     * Appends fulfillment and rejection handlers to the promise, and returns
24     * a new promise resolving to the return value of the called handler.
25     *
26     * @param callable $onFulfilled Invoked when the promise fulfills.
27     * @param callable $onRejected  Invoked when the promise is rejected.
28     */
29    public function then(
30        callable $onFulfilled = null,
31        callable $onRejected = null
32    ): PromiseInterface;
33
34    /**
35     * Appends a rejection handler callback to the promise, and returns a new
36     * promise resolving to the return value of the callback if it is called,
37     * or to its original fulfillment value if the promise is instead
38     * fulfilled.
39     *
40     * @param callable $onRejected Invoked when the promise is rejected.
41     */
42    public function otherwise(callable $onRejected): PromiseInterface;
43
44    /**
45     * Get the state of the promise ("pending", "rejected", or "fulfilled").
46     *
47     * The three states can be checked against the constants defined on
48     * PromiseInterface: PENDING, FULFILLED, and REJECTED.
49     */
50    public function getState(): string;
51
52    /**
53     * Resolve the promise with the given value.
54     *
55     * @param mixed $value
56     *
57     * @throws \RuntimeException if the promise is already resolved.
58     */
59    public function resolve($value): void;
60
61    /**
62     * Reject the promise with the given reason.
63     *
64     * @param mixed $reason
65     *
66     * @throws \RuntimeException if the promise is already resolved.
67     */
68    public function reject($reason): void;
69
70    /**
71     * Cancels the promise if possible.
72     *
73     * @see https://github.com/promises-aplus/cancellation-spec/issues/7
74     */
75    public function cancel(): void;
76
77    /**
78     * Waits until the promise completes if possible.
79     *
80     * Pass $unwrap as true to unwrap the result of the promise, either
81     * returning the resolved value or throwing the rejected exception.
82     *
83     * If the promise cannot be waited on, then the promise will be rejected.
84     *
85     * @return mixed
86     *
87     * @throws \LogicException if the promise has no wait function or if the
88     *                         promise does not settle after waiting.
89     */
90    public function wait(bool $unwrap = true);
91}
92