krz/vox-populi

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