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%.

By adding these annotations methods returning a promise can hint their resolving type by adding `@return PromiseInterface<bool>` when they for example resolve to a boolean. By doing that Psalm and PHPStan will understand that the following bit of code will not become an issue because the method's contract promised a boolean through the promise:

```php
$promise->then(static function (bool $isEnabled) {});
```

However, the following will yield errors:

```php
$promise->then(static function (string $isEnabled) {});
```

This PR is a requirement for reactphp/async#40

Author: WyriHaximus

.gitattributes

@@ -1,6 +1,8 @@
 /.gitattributes export-ignore
 /.github/ export-ignore
 /.gitignore export-ignore
+/phpstan.neon.dist export-ignore
 /phpunit.xml.dist export-ignore
 /phpunit.xml.legacy export-ignore
 /tests/ export-ignore
+/types/ export-ignore

.github/workflows/ci.yml

@@ -44,3 +44,17 @@ jobs:
       - run: composer self-update --2.2 # downgrade Composer for HHVM
       - run: hhvm $(which composer) install
       - run: hhvm vendor/bin/phpunit
+
+  PHPStan:
+    name: PHPStan
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        php:
+          - 8.1
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+      - run: vendor/bin/phpstan

phpstan.neon.dist

@@ -0,0 +1,4 @@
+parameters:
+  paths:
+    - types
+  level: max

src/React/Promise/PromiseInterface.php

@@ -2,7 +2,13 @@
 
 namespace React\Promise;
 
+/** @template T */
 interface PromiseInterface
 {
+    /**
+     * @template TReturn of mixed
+     * @param callable(T): TReturn $fulfilledHandler
+     * @return (TReturn is PromiseInterface ? TReturn : PromiseInterface<TReturn>)
+     */
     public function then($fulfilledHandler = null, $errorHandler = null, $progressHandler = null);
 }

types/PromiseInterface.php

@@ -0,0 +1,9 @@
+<?php
+
+use function PHPStan\Testing\assertType;
+use function React\Promise\resolve;
+
+$passThroughBoolFn = static fn (bool $bool): bool => $bool;
+
+assertType('React\Promise\PromiseInterface<bool>', resolve(true));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then($passThroughBoolFn));