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