1<?php
2
3namespace React\Promise;
4
5interface ExtendedPromiseInterface extends PromiseInterface
6{
7    /**
8     * Consumes the promise's ultimate value if the promise fulfills, or handles the
9     * ultimate error.
10     *
11     * It will cause a fatal error if either `$onFulfilled` or
12     * `$onRejected` throw or return a rejected promise.
13     *
14     * Since the purpose of `done()` is consumption rather than transformation,
15     * `done()` always returns `null`.
16     *
17     * @param callable|null $onFulfilled
18     * @param callable|null $onRejected
19     * @param callable|null $onProgress This argument is deprecated and should not be used anymore.
20     * @return void
21     */
22    public function done(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
23
24    /**
25     * Registers a rejection handler for promise. It is a shortcut for:
26     *
27     * ```php
28     * $promise->then(null, $onRejected);
29     * ```
30     *
31     * Additionally, you can type hint the `$reason` argument of `$onRejected` to catch
32     * only specific errors.
33     *
34     * @param callable $onRejected
35     * @return ExtendedPromiseInterface
36     */
37    public function otherwise(callable $onRejected);
38
39    /**
40     * Allows you to execute "cleanup" type tasks in a promise chain.
41     *
42     * It arranges for `$onFulfilledOrRejected` to be called, with no arguments,
43     * when the promise is either fulfilled or rejected.
44     *
45     * * If `$promise` fulfills, and `$onFulfilledOrRejected` returns successfully,
46     *    `$newPromise` will fulfill with the same value as `$promise`.
47     * * If `$promise` fulfills, and `$onFulfilledOrRejected` throws or returns a
48     *    rejected promise, `$newPromise` will reject with the thrown exception or
49     *    rejected promise's reason.
50     * * If `$promise` rejects, and `$onFulfilledOrRejected` returns successfully,
51     *    `$newPromise` will reject with the same reason as `$promise`.
52     * * If `$promise` rejects, and `$onFulfilledOrRejected` throws or returns a
53     *    rejected promise, `$newPromise` will reject with the thrown exception or
54     *    rejected promise's reason.
55     *
56     * `always()` behaves similarly to the synchronous finally statement. When combined
57     * with `otherwise()`, `always()` allows you to write code that is similar to the familiar
58     * synchronous catch/finally pair.
59     *
60     * Consider the following synchronous code:
61     *
62     * ```php
63     * try {
64     *     return doSomething();
65     * } catch(\Exception $e) {
66     *     return handleError($e);
67     * } finally {
68     *     cleanup();
69     * }
70     * ```
71     *
72     * Similar asynchronous code (with `doSomething()` that returns a promise) can be
73     * written:
74     *
75     * ```php
76     * return doSomething()
77     *     ->otherwise('handleError')
78     *     ->always('cleanup');
79     * ```
80     *
81     * @param callable $onFulfilledOrRejected
82     * @return ExtendedPromiseInterface
83     */
84    public function always(callable $onFulfilledOrRejected);
85
86    /**
87     * Registers a handler for progress updates from promise. It is a shortcut for:
88     *
89     * ```php
90     * $promise->then(null, null, $onProgress);
91     * ```
92     *
93     * @param callable $onProgress
94     * @return ExtendedPromiseInterface
95     * @deprecated 2.6.0 Progress support is deprecated and should not be used anymore.
96     */
97    public function progress(callable $onProgress);
98}
99