Add basic template annotations

This adds basic type safety annotations for static analyzers like PHPStan and Psalm. This will cover around 80% of the use cases and a follow-up PR for all supported versions will be proposed later to get it to a 100% of close to a 100%.

This PR is a requirement for reactphp/async#40

Author: WyriHaximus

src/PromiseInterface.php

@@ -2,6 +2,7 @@
 
 namespace React\Promise;
 
+/** @template T */
 interface PromiseInterface
 {
     /**
@@ -32,10 +33,11 @@ interface PromiseInterface
      *      than once.
      *  3. `$onProgress` (deprecated) may be called multiple times.
      *
-     * @param callable|null $onFulfilled
+     * @template TReturn of mixed
+     * @param callable(T): TReturn $onFulfilled
      * @param callable|null $onRejected
      * @param callable|null $onProgress This argument is deprecated and should not be used anymore.
-     * @return PromiseInterface
+     * @return (TReturn is PromiseInterface ? TReturn : PromiseInterface<TReturn>)
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
 }