|
1 | | -CHANGELOG for 3.x |
2 | | -================= |
3 | | - |
4 | | -* 3.0.0 (xxxx-xx-xx) |
5 | | - |
6 | | - New major release. |
7 | | - |
8 | | - * Introduce a global task queue to eliminate recursion and reduce stack size |
9 | | - when chaining promises (#28). |
10 | | - * BC break: The progression API has been removed (#32). |
11 | | - * BC break: The promise-array related functions (`all()`, `race()`, `any()`, |
12 | | - `some()`, `map()`, `reduce()`) now require an array of promises or values |
13 | | - as input. Before, arrays and promises which resolve to an array were |
14 | | - supported, other input types resolved to empty arrays or `null` (#35). |
15 | | - * BC break: `race()` now returns a forever pending promise when called with |
16 | | - an empty array (#83). |
17 | | - The behavior is now also in line with the ES6 specification. |
18 | | - * BC break: The interfaces `PromiseInterface`, `ExtendedPromiseInterface` |
19 | | - and `CancellablePromiseInterface` have been merged into a single |
20 | | - `PromiseInterface` (#75). |
21 | | - |
22 | | - Please note, that the following code (which has been commonly used to |
23 | | - conditionally cancel a promise) is not longer possible: |
24 | | - |
25 | | - ```php |
26 | | - if ($promise instanceof CancellablePromiseInterface) { |
27 | | - $promise->cancel(); |
28 | | - } |
29 | | - ``` |
30 | | - |
31 | | - If only supporting react/promise >= 3.0, it can be simply changed to: |
32 | | - |
33 | | - ```php |
34 | | - if ($promise instanceof PromiseInterface) { |
35 | | - $promise->cancel(); |
36 | | - } |
37 | | - ``` |
38 | | - |
39 | | - If also react/promise < 3.0 must be supported, the following code can be |
40 | | - used: |
41 | | - |
42 | | - ```php |
43 | | - if ($promise instanceof PromiseInterface) { |
44 | | - \React\Promise\resolve($promise)->cancel(); |
45 | | - } |
46 | | - ``` |
47 | | - * BC break: When rejecting a promise, a `\Throwable` or `\Exception` |
48 | | - instance is enforced as the rejection reason (#93). |
49 | | - This means, it is not longer possible to reject a promise without a reason |
50 | | - or with another promise. |
| 1 | +# Changelog |
| 2 | + |
| 3 | +## 3.0.0 (2023-07-11) |
| 4 | + |
| 5 | +A major new feature release, see [**release announcement**](https://clue.engineering/2023/announcing-reactphp-promise-v3). |
| 6 | + |
| 7 | +* We'd like to emphasize that this component is production ready and battle-tested. |
| 8 | + We plan to support all long-term support (LTS) releases for at least 24 months, |
| 9 | + so you have a rock-solid foundation to build on top of. |
| 10 | + |
| 11 | +* The v3 release will be the way forward for this package. However, we will still |
| 12 | + actively support v2 and v1 to provide a smooth upgrade path for those not yet |
| 13 | + on the latest versions. |
| 14 | + |
| 15 | +This update involves some major new features and a minor BC break over the |
| 16 | +`v2.0.0` release. We've tried hard to avoid BC breaks where possible and |
| 17 | +minimize impact otherwise. We expect that most consumers of this package will be |
| 18 | +affected by BC breaks, but updating should take no longer than a few minutes. |
| 19 | +See below for more details: |
| 20 | + |
| 21 | +* BC break: PHP 8.1+ recommended, PHP 7.1+ required. |
| 22 | + (#138 and #149 by @WyriHaximus) |
| 23 | + |
| 24 | +* Feature / BC break: The `PromiseInterface` now includes the functionality of the old ~~`ExtendedPromiseInterface`~~ and ~~`CancellablePromiseInterface`~~. |
| 25 | + Each promise now always includes the `then()`, `catch()`, `finally()` and `cancel()` methods. |
| 26 | + The new `catch()` and `finally()` methods replace the deprecated ~~`otherwise()`~~ and ~~`always()`~~ methods which continue to exist for BC reasons. |
| 27 | + The old ~~`ExtendedPromiseInterface`~~ and ~~`CancellablePromiseInterface`~~ are no longer needed and have been removed as a consequence. |
| 28 | + (#75 by @jsor and #208 by @clue and @WyriHaximus) |
| 29 | + |
| 30 | + ```php |
| 31 | + // old (multiple interfaces may or may not be implemented) |
| 32 | + assert($promise instanceof PromiseInterface); |
| 33 | + assert(method_exists($promise, 'then')); |
| 34 | + if ($promise instanceof ExtendedPromiseInterface) { assert(method_exists($promise, 'otherwise')); } |
| 35 | + if ($promise instanceof ExtendedPromiseInterface) { assert(method_exists($promise, 'always')); } |
| 36 | + if ($promise instanceof CancellablePromiseInterface) { assert(method_exists($promise, 'cancel')); } |
| 37 | + |
| 38 | + // new (single PromiseInterface with all methods) |
| 39 | + assert($promise instanceof PromiseInterface); |
| 40 | + assert(method_exists($promise, 'then')); |
| 41 | + assert(method_exists($promise, 'catch')); |
| 42 | + assert(method_exists($promise, 'finally')); |
| 43 | + assert(method_exists($promise, 'cancel')); |
| 44 | + ``` |
| 45 | + |
| 46 | +* Feature / BC break: Improve type safety of promises. Require `mixed` fulfillment value argument and `Throwable` (or `Exception`) as rejection reason. |
| 47 | + Add PHPStan template types to ensure strict types for `resolve(T $value): PromiseInterface<T>` and `reject(Throwable $reason): PromiseInterface<never>`. |
| 48 | + It is no longer possible to resolve a promise without a value (use `null` instead) or reject a promise without a reason (use `Throwable` instead). |
| 49 | + (#93, #141 and #142 by @jsor, #138, #149 and #247 by @WyriHaximus and #213 and #246 by @clue) |
| 50 | + |
| 51 | + ```php |
| 52 | + // old (arguments used to be optional) |
| 53 | + $promise = resolve(); |
| 54 | + $promise = reject(); |
| 55 | + |
| 56 | + // new (already supported before) |
| 57 | + $promise = resolve(null); |
| 58 | + $promise = reject(new RuntimeException()); |
| 59 | + ``` |
| 60 | + |
| 61 | +* Feature / BC break: Report all unhandled rejections by default and remove ~~`done()`~~ method. |
| 62 | + Add new `set_rejection_handler()` function to set the global rejection handler for unhandled promise rejections. |
| 63 | + (#248, #249 and #224 by @clue) |
| 64 | + |
| 65 | + ```php |
| 66 | + // Unhandled promise rejection with RuntimeException: Unhandled in example.php:2 |
| 67 | + reject(new RuntimeException('Unhandled')); |
| 68 | + ``` |
| 69 | + |
| 70 | +* BC break: Remove all deprecated APIs and reduce API surface. |
| 71 | + Remove ~~`some()`~~, ~~`map()`~~, ~~`reduce()`~~ functions, use `any()` and `all()` functions instead. |
| 72 | + Remove internal ~~`FulfilledPromise`~~ and ~~`RejectedPromise`~~ classes, use `resolve()` and `reject()` functions instead. |
| 73 | + Remove legacy promise progress API (deprecated third argument to `then()` method) and deprecated ~~`LazyPromise`~~ class. |
| 74 | + (#32 and #98 by @jsor and #164, #219 and #220 by @clue) |
| 75 | + |
| 76 | +* BC break: Make all classes final to encourage composition over inheritance. |
| 77 | + (#80 by @jsor) |
| 78 | + |
| 79 | +* Feature / BC break: Require `array` (or `iterable`) type for `all()` + `race()` + `any()` functions and bring in line with ES6 specification. |
| 80 | + These functions now require a single argument with a variable number of promises or values as input. |
| 81 | + (#225 by @clue and #35 by @jsor) |
| 82 | + |
| 83 | +* Fix / BC break: Fix `race()` to return a forever pending promise when called with an empty `array` (or `iterable`) and bring in line with ES6 specification. |
| 84 | + (#83 by @jsor and #225 by @clue) |
| 85 | + |
| 86 | +* Minor performance improvements by initializing `Deferred` in the constructor and avoiding `call_user_func()` calls. |
| 87 | + (#151 by @WyriHaximus and #171 by @Kubo2) |
| 88 | + |
| 89 | +* Minor documentation improvements. |
| 90 | + (#110 by @seregazhuk, #132 by @CharlotteDunois, #145 by @danielecr, #178 by @WyriHaximus, #189 by @srdante, #212 by @clue, #214, #239 and #243 by @SimonFrings and #231 by @nhedger) |
| 91 | + |
| 92 | +The following changes had to be ported to this release due to our branching |
| 93 | +strategy, but also appeared in the [`2.x` branch](https://github.com/reactphp/promise/tree/2.x): |
| 94 | + |
| 95 | +* Feature: Support union types and address deprecation of `ReflectionType::getClass()` (PHP 8+). |
| 96 | + (#197 by @cdosoftei and @SimonFrings) |
| 97 | + |
| 98 | +* Feature: Support intersection types (PHP 8.1+). |
| 99 | + (#209 by @bzikarsky) |
| 100 | + |
| 101 | +* Feature: Support DNS types (PHP 8.2+). |
| 102 | + (#236 by @nhedger) |
| 103 | + |
| 104 | +* Feature: Port all memory improvements from `2.x` to `3.x`. |
| 105 | + (#150 by @clue and @WyriHaximus) |
| 106 | + |
| 107 | +* Fix: Fix checking whether cancellable promise is an object and avoid possible warning. |
| 108 | + (#161 by @smscr) |
| 109 | + |
| 110 | +* Improve performance by prefixing all global functions calls with \ to skip the look up and resolve process and go straight to the global function. |
| 111 | + (#134 by @WyriHaximus) |
| 112 | + |
| 113 | +* Improve test suite, update PHPUnit and PHP versions and add `.gitattributes` to exclude dev files from exports. |
| 114 | + (#107 by @carusogabriel, #148 and #234 by @WyriHaximus, #153 by @reedy, #162, #230 and #240 by @clue, #173, #177, #185 and #199 by @SimonFrings, #193 by @woodongwong and #210 by @bzikarsky) |
| 115 | + |
| 116 | +The following changes were originally planned for this release but later reverted |
| 117 | +and are not part of the final release: |
| 118 | + |
| 119 | +* Add iterative callback queue handler to avoid recursion (later removed to improve Fiber support). |
| 120 | + (#28, #82 and #86 by @jsor, #158 by @WyriHaximus and #229 and #238 by @clue) |
| 121 | + |
| 122 | +* Trigger an `E_USER_ERROR` instead of throwing an exception from `done()` (later removed entire `done()` method to globally report unhandled rejections). |
| 123 | + (#97 by @jsor and #224 and #248 by @clue) |
| 124 | + |
| 125 | +* Add type declarations for `some()` (later removed entire `some()` function). |
| 126 | + (#172 by @WyriHaximus and #219 by @clue) |
| 127 | + |
| 128 | +## 2.0.0 (2013-12-10) |
| 129 | + |
| 130 | +See [`2.x` CHANGELOG](https://github.com/reactphp/promise/blob/2.x/CHANGELOG.md) for more details. |
| 131 | + |
| 132 | +## 1.0.0 (2012-11-07) |
| 133 | + |
| 134 | +See [`1.x` CHANGELOG](https://github.com/reactphp/promise/blob/1.x/CHANGELOG.md) for more details. |
0 commit comments