Merge promise interfaces

[jsor]

Merge PromiseInterface, ExtendedPromiseInterface and CancellablePromiseInterface into a single PromiseInterface.

The CancellablePromiseInterface is kept for backward compatibility but is marked as deprecated and must not be used anymore. (Edit: Also removed in 251b4e5)

Closes #44

[WyriHaximus]

So much 👍 on this, type hinting is a P.I.T.A. if you want to be compatible and ensure the promise can be canceled

[jsor]

I mostly kept CancellablePromiseInterface for @clue because i've seen him using instanceof checks a lot in his libs, eg: https://github.com/reactphp/promise-timer/blob/master/src/functions.php#L23 😃

[kelunik]

Are you sure merging CancellablePromiseInterface is a good idea? Most operations can't be canceled I guess.

[jsor]

@kelunik All promises have a cancel method. If calling this method has any effect is up to the producer of the promise.

[kelunik]

@jsor Might make sense then as long as cancel is don't care then instead of abort.

[jsor]

I'm not sure i understand what that has to do with the interface merge? The interfaces are only separate for backward compatibility reasons because they were introduced separately. All promise implementations in react/promise implement all 3 interfaces.

[kelunik]

Ah, fine then. I thought cancelability was an optional thing before.

[jsor]

I've now also removed CancellablePromiseInterface.

When supporting react/promise ~1.2|~2.1|~3.0 as a dependency, the following code is not longer possible:

if ($promise instanceof CancellablePromiseInterface) {
    $promise->cancel();
}

A possible solution is to pass $promise through resolve().

React\Promise\resolve($promise)->cancel();

Please note, that this adds some overhead if $promise is not already a promise instance, eg. a scalar.

Another solution would be to just test against PromiseInterface.

if ($promise instanceof PromiseInterface) {
    $promise->cancel();
}

All promise implementations from react/promise < 3.0 implement both PromiseInterface and CancellablePromiseInterface, so every instance of PromiseInterface is also an instance of CancellablePromiseInterface.

This would break though, when $promise is a custom third-party promise implementation which only implements PromiseInterface but not CancellablePromiseInterface.

The safest solution would probably be a combination of the two methods:

if ($promise instanceof PromiseInterface) {
    React\Promise\resolve($promise)->cancel();
}

[clue]

Nice! The changes make perfect sense and the upgrade guide is much appreciated! 👍