Refactor Promise classes with generic types

This commit refactors the Promise interface and concrete classes to use generic types. This provides better support for static analysis tools, enforcing type safety and improving code readability.

Author: Radiergummi

src/FulfilledPromise.php

@@ -6,14 +6,20 @@
  * A promise already fulfilled.
  *
  * @author Joel Wurtz <joel.wurtz@gmail.com>
+ *
+ * @template-covariant T
+ * @implements Promise<T>
  */
 final class FulfilledPromise implements Promise
 {
     /**
-     * @var mixed
+     * @var T
      */
     private $result;
 
+    /**
+     * @param T $result
+     */
     public function __construct($result)
     {
         $this->result = $result;

src/Promise.php

@@ -12,6 +12,8 @@
  *
  * @author Joel Wurtz <joel.wurtz@gmail.com>
  * @author Márk Sági-Kazár <mark.sagikazar@gmail.com>
+ *
+ * @template-covariant T
  */
 interface Promise
 {
@@ -36,10 +38,11 @@ interface Promise
      * If you do not care about one of the cases, you can set the corresponding callable to null
      * The callback will be called when the value arrived and never more than once.
      *
-     * @param callable|null $onFulfilled called when a response will be available
-     * @param callable|null $onRejected  called when an exception occurs
+     * @param callable(T): V|null $onFulfilled called when a response will be available
+     * @param callable(\Exception): V|null $onRejected  called when an exception occurs
      *
-     * @return Promise a new resolved promise with value of the executed callback (onFulfilled / onRejected)
+     * @return Promise<V> a new resolved promise with value of the executed callback (onFulfilled / onRejected)
+     * @template V
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null);
 
@@ -61,7 +64,7 @@ public function getState();
      *
      * @param bool $unwrap Whether to return resolved value / throw reason or not
      *
-     * @return mixed Resolved value, null if $unwrap is set to false
+     * @return T Resolved value, null if $unwrap is set to false
      *
      * @throws \Exception the rejection reason if $unwrap is set to true and the request failed
      */

src/RejectedPromise.php

@@ -6,6 +6,9 @@
  * A rejected promise.
  *
  * @author Joel Wurtz <joel.wurtz@gmail.com>
+ *
+ * @template-covariant T
+ * @implements Promise<T>
  */
 final class RejectedPromise implements Promise
 {