add phpdoc templates to PromiseInterface #175
Conversation
| @@ -82,7 +84,7 @@ public function cancel(): void; | |||
| * | |||
| * If the promise cannot be waited on, then the promise will be rejected. | |||
| * | |||
| * @return mixed | |||
| * @return T|PromiseInterface<T> | |||
There was a problem hiding this comment.
I don't think PromiseInterface<T> is entirely correct.
/** @var PromiseInterface<int> $promise */
$promise = new FulfilledPromise(2);
/** @var PromiseInterface<bool> $result */
$result = $promise->then(fn ($num) => $num %2 = 0);
The return of the callback should determine the new template type.
There was a problem hiding this comment.
In reality, then and otherwise should each handle the possible types their callback returns according to fulfillment and rejection
* @template TNextValue
* @param callable(TReason): TNextValue $onRejected Invoked when the promise is rejected.
*
* @return (TNextValue is PromiseInterface
* ? PromiseInterface<template-type<TNextValue, PromiseInterface, 'TValue'>, TReason|template-type<TNextValue, PromiseInterface, 'TReason'>>
* : PromiseInterface<TNextValue, TReason>
* )I'm in a bit of a rush, so I'll have to complete this suggestion later. @ojhaujjwal I'm done, but now I'm fully realizing how confusing promises can be 😕 ...
As an aside, I made a mistake earlier: neither guzzlehttp/promises nor guzzlehttp/guzzle have a static analyzer as a dependency, but some annotations mention psalm, not phpstan, so it might be wiser to use the vendor specific annotations (@phpstan-template and @psalm-template) until guzzlehttp makes their stance known
There was a problem hiding this comment.
Wait there was this PR that tackled the problem too, but did not see a response: #157 . It might be better to handle it as a stub rather than duplicate annotations for each static analyzer
There was a problem hiding this comment.
@bshaffer I think this PR is not complete yet, can you study the rejection/fulfillment a bit further? I don't know how this will play out with each phpstan version, whether that might require a new minimum version, or directly introduce a number of errors in downstreams
| @@ -12,6 +12,7 @@ | |||
| * the reason why the promise cannot be fulfilled. | |||
| * | |||
| * @see https://promisesaplus.com/ | |||
| * @template T | |||
There was a problem hiding this comment.
| * @template T | |
| * @template TValue = mixed | |
| * @template TReason = mixed |
| * @param callable $onFulfilled Invoked when the promise fulfills. | ||
| * @param callable $onRejected Invoked when the promise is rejected. | ||
| * @return PromiseInterface<T> |
There was a problem hiding this comment.
| * @param callable $onFulfilled Invoked when the promise fulfills. | |
| * @param callable $onRejected Invoked when the promise is rejected. | |
| * @return PromiseInterface<T> | |
| * @template TNextValue | |
| * @template TNextReason | |
| * @param callable(TValue): TNextValue $onFulfilled Invoked when the promise fulfills. | |
| * @param callable(TReason): TNextReason $onRejected Invoked when the promise is rejected. | |
| * | |
| * @return (TNextValue is PromiseInterface | |
| * ? (TNextReason is PromiseInterface | |
| * ? PromiseInterface<template-type<TNextValue, PromiseInterface, 'TValue'>, TReason|template-type<TNextReason, PromiseInterface, 'TReason'>> | |
| * : PromiseInterface<template-type<TNextValue, PromiseInterface, 'TValue'>, TNextReason> | |
| * ) | |
| * : (TNextReason is PromiseInterface | |
| * ? PromiseInterface<TNextValue, template-type<TNextReason, PromiseInterface, 'TReason'>> | |
| * : PromiseInterface<TNextValue, TNextReason> | |
| * ) | |
| * ) |
The result of fulfillment and rejection are 2 separate types and need to be handled separately. If onFulfillment returns a promise, that one might fail too, so the resulting rejection might come from either the current promise, or the next one.
Not to mention each callback might itself throw an exception, which usually is a rejection too I've ended up leaving out the \Throwable possibility, it might be better for the implementer to explicitly hint it when they handle that case
| @@ -82,7 +84,7 @@ public function cancel(): void; | |||
| * | |||
| * If the promise cannot be waited on, then the promise will be rejected. | |||
| * | |||
| * @return mixed | |||
| * @return T|PromiseInterface<T> | |||
There was a problem hiding this comment.
In reality, then and otherwise should each handle the possible types their callback returns according to fulfillment and rejection
* @template TNextValue
* @param callable(TReason): TNextValue $onRejected Invoked when the promise is rejected.
*
* @return (TNextValue is PromiseInterface
* ? PromiseInterface<template-type<TNextValue, PromiseInterface, 'TValue'>, TReason|template-type<TNextValue, PromiseInterface, 'TReason'>>
* : PromiseInterface<TNextValue, TReason>
* )I'm in a bit of a rush, so I'll have to complete this suggestion later. @ojhaujjwal I'm done, but now I'm fully realizing how confusing promises can be 😕 ...
As an aside, I made a mistake earlier: neither guzzlehttp/promises nor guzzlehttp/guzzle have a static analyzer as a dependency, but some annotations mention psalm, not phpstan, so it might be wiser to use the vendor specific annotations (@phpstan-template and @psalm-template) until guzzlehttp makes their stance known
partially addresses #163