reactphp / promise

Promises/A implementation for PHP.
https://reactphp.org/promise/
MIT License
2.38k stars 146 forks source link

Add `catch()` and `finally()`, deprecate `otherwise()` and `always()` #208

Closed clue closed 2 years ago

clue commented 2 years ago

This changeset adds new catch() and finally() methods to the PromiseInterface and deprecates the otherwise() and always() methods. The underlying idea is to rename otherwise() to catch() and always() to finally(), but instead of performing a hard rename and causing a BC break, this changeset proposes deprecating the old method names and using them as an alias for the new method names.

// old (deprecated)
$promise->otherwise($onRejected);
$promise->always($onFulfilledOrRejected);

// new
$promise->catch($onRejected);
$promise->finally($onFulfilledOrRejected);

The original method names have been added in #19 a while back. Back then, using the catch() and finally() method names was not possible as using reserved keywords is only supported as of PHP 7+. Promise v3 is PHP 7.1+ only (#138 / #149), so we can now use the method names that mimic a synchronous try/catch/finally block. Additionally, this also happens to be in line with ES6 promises as found in JavaScript.

Supersedes / closes #206, thanks @WyriHaximus for the original version! This PR follows the exact same idea with no functional difference, but adds additional documentation and duplicates all relevant test cases to achieve 100% code coverage for the affected code paths. Accordingly, there's a fair amount of duplication in the test suite now, which I consider a non-ideal but acceptable tradeoff. A potential promise v4 could remove this duplication at some point in the future.