Skip to content

Commit 29e035e

Browse files
WyriHaximusWyriHaximus
committed
Rename otherwise to catch, and always to finally
Due to limitations in the PHP language these methods these two methods couldn't use keywords as names. With PHP 7+ this is possible, and it makes it a lot clearer what the methods do. Refs: #19
1 parent 9647500 commit 29e035e

12 files changed

+92
-44
lines changed

‎README.md‎

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,10 @@ Table of Contents
2929
* [PromiseInterface](#promiseinterface)
3030
* [PromiseInterface::then()](#promiseinterfacethen)
3131
* [PromiseInterface::done()](#promiseinterfacedone)
32-
* [PromiseInterface::otherwise()](#promiseinterfaceotherwise)
33-
* [PromiseInterface::always()](#promiseinterfacealways)
32+
* [~~PromiseInterface::otherwise()~~](#promiseinterfaceotherwise)
33+
* [PromiseInterface::catch()](#promiseinterfacecatch)
34+
* [~~PromiseInterface::always()~~](#promiseinterfacealways)
35+
* [PromiseInterface::finally()](#promiseinterfacefinally)
3436
* [PromiseInterface::cancel()](#promiseinterfacecancel)
3537
* [Promise](#promise-2)
3638
* [Functions](#functions)
@@ -206,10 +208,14 @@ Since the purpose of `done()` is consumption rather than transformation,
206208
* [PromiseInterface::then()](#promiseinterfacethen)
207209
* [done() vs. then()](#done-vs-then)
208210

209-
#### PromiseInterface::otherwise()
211+
#### ~~PromiseInterface::otherwise()~~
212+
213+
The `otherwise` method has been deprecated in favour of [`catch`](#promiseinterfacecatch)
214+
215+
#### PromiseInterface::catch()
210216

211217
```php
212-
$promise->otherwise(callable $onRejected);
218+
$promise->catch(callable $onRejected);
213219
```
214220

215221
Registers a rejection handler for promise. It is a shortcut for:
@@ -223,19 +229,23 @@ only specific errors.
223229

224230
```php
225231
$promise
226-
->otherwise(function (\RuntimeException $reason) {
232+
->catch(function (\RuntimeException $reason) {
227233
// Only catch \RuntimeException instances
228234
// All other types of errors will propagate automatically
229235
})
230-
->otherwise(function (\Throwable $reason) {
236+
->catch(function (\Throwable $reason) {
231237
// Catch other errors
232238
});
233239
```
234240

235-
#### PromiseInterface::always()
241+
#### ~~PromiseInterface::always()~~
242+
243+
The `otherwise` method has been deprecated in favour of [`finally`](#promiseinterfacefinally)
244+
245+
#### PromiseInterface::finally()
236246

237247
```php
238-
$newPromise = $promise->always(callable $onFulfilledOrRejected);
248+
$newPromise = $promise->finally(callable $onFulfilledOrRejected);
239249
```
240250

241251
Allows you to execute "cleanup" type tasks in a promise chain.
@@ -254,8 +264,8 @@ when the promise is either fulfilled or rejected.
254264
rejected promise, `$newPromise` will reject with the thrown exception or
255265
rejected promise's reason.
256266

257-
`always()` behaves similarly to the synchronous finally statement. When combined
258-
with `otherwise()`, `always()` allows you to write code that is similar to the familiar
267+
`finally()` behaves similarly to the synchronous finally statement. When combined
268+
with `catch()`, `finally()` allows you to write code that is similar to the familiar
259269
synchronous catch/finally pair.
260270

261271
Consider the following synchronous code:
@@ -275,8 +285,8 @@ written:
275285

276286
```php
277287
return doSomething()
278-
->otherwise('handleError')
279-
->always('cleanup');
288+
->catch('handleError')
289+
->finally('cleanup');
280290
```
281291

282292
#### PromiseInterface::cancel()

‎src/Internal/FulfilledPromise.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,21 @@ public function done(callable $onFulfilled = null, callable $onRejected = null):
6161
}
6262

6363
public function otherwise(callable $onRejected): PromiseInterface
64+
{
65+
return $this->catch($onRejected);
66+
}
67+
68+
public function catch(callable $onRejected): PromiseInterface
6469
{
6570
return $this;
6671
}
6772

6873
public function always(callable $onFulfilledOrRejected): PromiseInterface
74+
{
75+
return $this->finally($onFulfilledOrRejected);
76+
}
77+
78+
public function finally(callable $onFulfilledOrRejected): PromiseInterface
6979
{
7080
return $this->then(function ($value) use ($onFulfilledOrRejected): PromiseInterface {
7181
return resolve($onFulfilledOrRejected())->then(function () use ($value) {

‎src/Internal/RejectedPromise.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,11 @@ public function done(callable $onFulfilled = null, callable $onRejected = null):
6262
}
6363

6464
public function otherwise(callable $onRejected): PromiseInterface
65+
{
66+
return $this->catch($onRejected);
67+
}
68+
69+
public function catch(callable $onRejected): PromiseInterface
6570
{
6671
if (!_checkTypehint($onRejected, $this->reason)) {
6772
return $this;
@@ -71,6 +76,11 @@ public function otherwise(callable $onRejected): PromiseInterface
7176
}
7277

7378
public function always(callable $onFulfilledOrRejected): PromiseInterface
79+
{
80+
return $this->finally($onFulfilledOrRejected);
81+
}
82+
83+
public function finally(callable $onFulfilledOrRejected): PromiseInterface
7484
{
7585
return $this->then(null, function (\Throwable $reason) use ($onFulfilledOrRejected): PromiseInterface {
7686
return resolve($onFulfilledOrRejected())->then(function () use ($reason): PromiseInterface {

‎src/Promise.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,11 @@ public function done(callable $onFulfilled = null, callable $onRejected = null):
7171
}
7272

7373
public function otherwise(callable $onRejected): PromiseInterface
74+
{
75+
return $this->catch($onRejected);
76+
}
77+
78+
public function catch(callable $onRejected): PromiseInterface
7479
{
7580
return $this->then(null, static function ($reason) use ($onRejected) {
7681
if (!_checkTypehint($onRejected, $reason)) {
@@ -82,6 +87,11 @@ public function otherwise(callable $onRejected): PromiseInterface
8287
}
8388

8489
public function always(callable $onFulfilledOrRejected): PromiseInterface
90+
{
91+
return $this->finally($onFulfilledOrRejected);
92+
}
93+
94+
public function finally(callable $onFulfilledOrRejected): PromiseInterface
8595
{
8696
return $this->then(static function ($value) use ($onFulfilledOrRejected) {
8797
return resolve($onFulfilledOrRejected())->then(function () use ($value) {

‎src/PromiseInterface.php‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,14 @@ public function then(?callable $onFulfilled = null, ?callable $onRejected = null
5050
*/
5151
public function done(callable $onFulfilled = null, callable $onRejected = null): void;
5252

53+
/**
54+
* @see catch
55+
* @deprecated Use catch instead
56+
* @param callable $onRejected
57+
* @return PromiseInterface
58+
*/
59+
public function otherwise(callable $onRejected): PromiseInterface;
60+
5361
/**
5462
* Registers a rejection handler for promise. It is a shortcut for:
5563
*
@@ -63,7 +71,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null):
6371
* @param callable $onRejected
6472
* @return PromiseInterface
6573
*/
66-
public function otherwise(callable $onRejected): PromiseInterface;
74+
public function catch(callable $onRejected): PromiseInterface;
6775

6876
/**
6977
* Allows you to execute "cleanup" type tasks in a promise chain.

‎tests/PromiseTest.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ public function shouldNotLeaveGarbageCyclesWhenRemovingLastReferenceToPendingPro
228228
{
229229
gc_collect_cycles();
230230
$promise = new Promise(function () { });
231-
$promise->otherwise(function () { });
231+
$promise->catch(function () { });
232232
unset($promise);
233233

234234
$this->assertSame(0, gc_collect_cycles());
@@ -239,7 +239,7 @@ public function shouldNotLeaveGarbageCyclesWhenRemovingLastReferenceToPendingPro
239239
{
240240
gc_collect_cycles();
241241
$promise = new Promise(function () { });
242-
$promise->always(function () { });
242+
$promise->finally(function () { });
243243
unset($promise);
244244

245245
$this->assertSame(0, gc_collect_cycles());

‎tests/PromiseTest/PromiseFulfilledTestTrait.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ public function otherwiseShouldNotInvokeRejectionHandlerForFulfilledPromise()
266266
$adapter = $this->getPromiseTestAdapter();
267267

268268
$adapter->resolve(1);
269-
$adapter->promise()->otherwise($this->expectCallableNever());
269+
$adapter->promise()->catch($this->expectCallableNever());
270270
}
271271

272272
/** @test */
@@ -284,7 +284,7 @@ public function alwaysShouldNotSuppressValueForFulfilledPromise()
284284

285285
$adapter->resolve($value);
286286
$adapter->promise()
287-
->always(function () {})
287+
->finally(function () {})
288288
->then($mock);
289289
}
290290

@@ -303,7 +303,7 @@ public function alwaysShouldNotSuppressValueWhenHandlerReturnsANonPromiseForFulf
303303

304304
$adapter->resolve($value);
305305
$adapter->promise()
306-
->always(function () {
306+
->finally(function () {
307307
return 1;
308308
})
309309
->then($mock);
@@ -324,7 +324,7 @@ public function alwaysShouldNotSuppressValueWhenHandlerReturnsAPromiseForFulfill
324324

325325
$adapter->resolve($value);
326326
$adapter->promise()
327-
->always(function () {
327+
->finally(function () {
328328
return resolve(1);
329329
})
330330
->then($mock);
@@ -345,7 +345,7 @@ public function alwaysShouldRejectWhenHandlerThrowsForFulfilledPromise()
345345

346346
$adapter->resolve(1);
347347
$adapter->promise()
348-
->always(function () use ($exception) {
348+
->finally(function () use ($exception) {
349349
throw $exception;
350350
})
351351
->then(null, $mock);
@@ -366,7 +366,7 @@ public function alwaysShouldRejectWhenHandlerRejectsForFulfilledPromise()
366366

367367
$adapter->resolve(1);
368368
$adapter->promise()
369-
->always(function () use ($exception) {
369+
->finally(function () use ($exception) {
370370
return reject($exception);
371371
})
372372
->then(null, $mock);

‎tests/PromiseTest/PromisePendingTestTrait.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,14 +58,14 @@ public function otherwiseShouldNotInvokeRejectionHandlerForPendingPromise()
5858
$adapter = $this->getPromiseTestAdapter();
5959

6060
$adapter->settle();
61-
$adapter->promise()->otherwise($this->expectCallableNever());
61+
$adapter->promise()->catch($this->expectCallableNever());
6262
}
6363

6464
/** @test */
6565
public function alwaysShouldReturnAPromiseForPendingPromise()
6666
{
6767
$adapter = $this->getPromiseTestAdapter();
6868

69-
self::assertInstanceOf(PromiseInterface::class, $adapter->promise()->always(function () {}));
69+
self::assertInstanceOf(PromiseInterface::class, $adapter->promise()->finally(function () {}));
7070
}
7171
}

‎tests/PromiseTest/PromiseRejectedTestTrait.php‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -325,7 +325,7 @@ public function otherwiseShouldInvokeRejectionHandlerForRejectedPromise()
325325
->with($this->identicalTo($exception));
326326

327327
$adapter->reject($exception);
328-
$adapter->promise()->otherwise($mock);
328+
$adapter->promise()->catch($mock);
329329
}
330330

331331
/** @test */
@@ -343,7 +343,7 @@ public function otherwiseShouldInvokeNonTypeHintedRejectionHandlerIfReasonIsAnEx
343343

344344
$adapter->reject($exception);
345345
$adapter->promise()
346-
->otherwise(function ($reason) use ($mock) {
346+
->catch(function ($reason) use ($mock) {
347347
$mock($reason);
348348
});
349349
}
@@ -363,7 +363,7 @@ public function otherwiseShouldInvokeRejectionHandlerIfReasonMatchesTypehintForR
363363

364364
$adapter->reject($exception);
365365
$adapter->promise()
366-
->otherwise(function (InvalidArgumentException $reason) use ($mock) {
366+
->catch(function (InvalidArgumentException $reason) use ($mock) {
367367
$mock($reason);
368368
});
369369
}
@@ -379,7 +379,7 @@ public function otherwiseShouldNotInvokeRejectionHandlerIfReaonsDoesNotMatchType
379379

380380
$adapter->reject($exception);
381381
$adapter->promise()
382-
->otherwise(function (InvalidArgumentException $reason) use ($mock) {
382+
->catch(function (InvalidArgumentException $reason) use ($mock) {
383383
$mock($reason);
384384
});
385385
}
@@ -399,7 +399,7 @@ public function alwaysShouldNotSuppressRejectionForRejectedPromise()
399399

400400
$adapter->reject($exception);
401401
$adapter->promise()
402-
->always(function () {})
402+
->finally(function () {})
403403
->then(null, $mock);
404404
}
405405

@@ -418,7 +418,7 @@ public function alwaysShouldNotSuppressRejectionWhenHandlerReturnsANonPromiseFor
418418

419419
$adapter->reject($exception);
420420
$adapter->promise()
421-
->always(function () {
421+
->finally(function () {
422422
return 1;
423423
})
424424
->then(null, $mock);
@@ -439,7 +439,7 @@ public function alwaysShouldNotSuppressRejectionWhenHandlerReturnsAPromiseForRej
439439

440440
$adapter->reject($exception);
441441
$adapter->promise()
442-
->always(function () {
442+
->finally(function () {
443443
return resolve(1);
444444
})
445445
->then(null, $mock);
@@ -461,7 +461,7 @@ public function alwaysShouldRejectWhenHandlerThrowsForRejectedPromise()
461461

462462
$adapter->reject($exception1);
463463
$adapter->promise()
464-
->always(function () use ($exception2) {
464+
->finally(function () use ($exception2) {
465465
throw $exception2;
466466
})
467467
->then(null, $mock);
@@ -483,7 +483,7 @@ public function alwaysShouldRejectWhenHandlerRejectsForRejectedPromise()
483483

484484
$adapter->reject($exception1);
485485
$adapter->promise()
486-
->always(function () use ($exception2) {
486+
->finally(function () use ($exception2) {
487487
return reject($exception2);
488488
})
489489
->then(null, $mock);

‎tests/PromiseTest/PromiseSettledTestTrait.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,6 @@ public function alwaysShouldReturnAPromiseForSettledPromise()
7474
$adapter = $this->getPromiseTestAdapter();
7575

7676
$adapter->settle();
77-
self::assertInstanceOf(PromiseInterface::class, $adapter->promise()->always(function () {}));
77+
self::assertInstanceOf(PromiseInterface::class, $adapter->promise()->finally(function () {}));
7878
}
7979
}

0 commit comments

Comments
 (0)