Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add phpdoc templates to PromiseInterface #175

Open
wants to merge 1 commit into
base: 2.0
Choose a base branch
from
Open

add phpdoc templates to PromiseInterface #175

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/PromiseInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
* the reason why the promise cannot be fulfilled.
*
* @see https://promisesaplus.com/
* @template T
Copy link

@brutal-factories brutal-factories Dec 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @template T
* @template TValue = mixed
* @template TReason = mixed

*/
interface PromiseInterface
{
Expand All @@ -25,6 +26,7 @@ interface PromiseInterface
*
* @param callable $onFulfilled Invoked when the promise fulfills.
* @param callable $onRejected Invoked when the promise is rejected.
* @return PromiseInterface<T>
Comment on lines 27 to +29
Copy link

@brutal-factories brutal-factories Dec 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @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

*/
public function then(
?callable $onFulfilled = null,
Expand Down Expand Up @@ -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>
Copy link

@ojhaujjwal ojhaujjwal Dec 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

@brutal-factories brutal-factories Dec 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

*
* @throws \LogicException if the promise has no wait function or if the
* promise does not settle after waiting.
Expand Down