minor #148 Improve PHPStan and Psalm annotations (B-Galati)

This PR was merged into the 1.x-dev branch.

Discussion
----------

Improve PHPStan and Psalm annotations

Hello!

I just upgrade the lib and notice some false positive with PHPStan analysis due to missing annotations.

So here are my fixes. Let me know if it's correct or not :-)

Commits
-------

4006590 Improve PHPStan and Psalm annotations

src/AutoDiscoveredValuesTrait.php

@@ -13,6 +13,8 @@
 use Elao\Enum\Exception\LogicException;
 
 /**
+ * @template T of int|string
+ *
  * Auto-discover enumerated values from public constants.
  */
 trait AutoDiscoveredValuesTrait
@@ -24,12 +26,10 @@ trait AutoDiscoveredValuesTrait
     private static $guessedReadables = [];
 
     /**
-     * @template T of int|string
-     *
      * @see EnumInterface::values()
      *
      * @return int[]|string[]
-     * @psalm-return list<T>
+     * @psalm-return T[]
      */
     public static function values(): array
     {

src/Bridge/Doctrine/DBAL/Types/AbstractEnumType.php

@@ -14,12 +14,16 @@
 use Doctrine\DBAL\Types\Type;
 use Elao\Enum\EnumInterface;
 
+/**
+ * @template T of EnumInterface
+ */
 abstract class AbstractEnumType extends Type
 {
     /**
      * The enum FQCN for which we should make the DBAL conversion.
      *
-     * @return class-string<EnumInterface>
+     * @return string&EnumInterface
+     * @psalm-return class-string<T>
      */
     abstract protected function getEnumClass(): string;
 
@@ -46,7 +50,8 @@ protected function onNullFromPhp()
     /**
      * {@inheritdoc}
      *
-     * @param EnumInterface $value
+     * @param EnumInterface|null $value
+     * @psalm-param T|null $value
      */
     public function convertToDatabaseValue($value, AbstractPlatform $platform)
     {
@@ -66,7 +71,6 @@ public function convertToPHPValue($value, AbstractPlatform $platform)
             return $this->onNullFromDatabase();
         }
 
-        /** @var string|EnumInterface $class */
         $class = $this->getEnumClass();
 
         return $class::get($this->cast($value));

src/Bridge/Doctrine/ODM/Types/AbstractCollectionEnumType.php

@@ -32,7 +32,7 @@ public function convertToDatabaseValue($value)
     /**
      * {@inheritdoc}
      *
-     * @phpstan-return array<TEnum>|null
+     * @psalm-return array<TEnum>|null
      */
     public function convertToPHPValue($value)
     {

src/Bridge/Doctrine/ODM/Types/AbstractEnumType.php

@@ -42,7 +42,7 @@ public function convertToDatabaseValue($value)
     /**
      * {@inheritdoc}
      *
-     * @phpstan-return TEnum
+     * @psalm-return TEnum
      */
     public function convertToPHPValue($value): ?EnumInterface
     {

src/ChoiceEnumTrait.php

@@ -13,6 +13,8 @@
 use Elao\Enum\Exception\LogicException;
 
 /**
+ * @template T of int|string
+ *
  * Discover readable enumerated values by returning the enumerated values as keys and their labels as values
  * in {@link \Elao\Enum\ChoiceEnumTrait::choices()}, replacing the need to provide both:
  * - {@link \Elao\Enum\ReadableEnumInterface::readables()}
@@ -25,10 +27,8 @@ trait ChoiceEnumTrait
     /**
      * @see EnumInterface::values()
      *
-     * @template T of int|string
-     *
      * @return int[]|string[]
-     * @psalm-return list<T>
+     * @psalm-return T[]
      */
     public static function values(): array
     {
@@ -48,10 +48,7 @@ public static function values(): array
     /**
      * @see ReadableEnumInterface::readables()
      *
-     * @template T of int|string
-     *
      * @return array<int|string, string> labels indexed by enumerated value
-     *
      * @psalm-return array<T, string>
      */
     public static function readables(): array
@@ -62,10 +59,7 @@ public static function readables(): array
     }
 
     /**
-     * @template T of int|string
-     *
      * @return array<int|string, string> The enumerated values as keys and their labels as values.
-     *
      * @psalm-return array<T, string>
      */
     abstract protected static function choices(): array;

src/Enum.php

@@ -25,6 +25,7 @@ abstract class Enum implements EnumInterface
      * This means you'll always get the exact same instance for a same enum value.
      *
      * @var EnumInterface<int|string>[]
+     * @psalm-var EnumInterface<T>[]
      */
     private static $instances;
 
@@ -37,7 +38,8 @@ abstract class Enum implements EnumInterface
     /**
      * The constructor is private and cannot be overridden: use the static get method instead.
      *
-     * @param mixed $value The raw value of an enumeration
+     * @param int|string $value The raw value of an enumeration
+     * @psalm-param T $value
      */
     final private function __construct($value)
     {

src/EnumInterface.php

@@ -18,8 +18,6 @@
 interface EnumInterface
 {
     /**
-     * @template T of int|string
-     *
      * @param int|string $value The value of a particular enumerated constant
      * @psalm-param T $value
      *
@@ -32,18 +30,14 @@ public static function get($value): self;
     /**
      * Returns any possible value for the enumeration.
      *
-     * @template T of int|string
-     *
-     * @return list<int|string>
-     * @psalm-return list<T>
+     * @return int[]|string[]
+     * @psalm-return T[]
      */
     public static function values(): array;
 
     /**
-     * @template T of int|string
-     *
      * @param int|string $value
-     * @psalm-param  T $value
+     * @psalm-param T $value
      *
      * @return bool True if the value is acceptable for this enumeration
      */
@@ -68,13 +62,15 @@ public function getValue();
      * Determines whether two enumerations instances should be considered the same.
      *
      * @param EnumInterface<int|string> $enum An enum object to compare with this instance
+     * @psalm-param EnumInterface<T> $enum
      */
     public function equals(EnumInterface $enum): bool;
 
     /**
      * Determines if the enumeration instance value is equal to the given value.
      *
      * @param int|string $value
+     * @psalm-param T $value
      */
     public function is($value): bool;
 }

src/ReadableEnumInterface.php

@@ -15,15 +15,13 @@
 
 /**
  * @template T of int|string
- * @implements EnumInterface<T>
+ * @extends EnumInterface<T>
  */
 interface ReadableEnumInterface extends EnumInterface, Stringable
 {
     /**
      * Gets an array of the human representations indexed by possible values.
      *
-     * @template T of int|string
-     *
      * @return string[] labels indexed by enumerated value
      * @psalm-return array<T, string>
      */
@@ -32,8 +30,6 @@ public static function readables(): array;
     /**
      * Gets the human representation for a given value.
      *
-     * @template T of int|string
-     *
      * @param int|string $value The value of a particular enumerated constant
      * @psalm-param T $value
      *

src/SimpleChoiceEnum.php

@@ -22,7 +22,9 @@
  */
 abstract class SimpleChoiceEnum extends ReadableEnum
 {
+    /* @use AutoDiscoveredValuesTrait<T> */
     use AutoDiscoveredValuesTrait;
+    /* @use ChoiceEnumTrait<T> */
     use ChoiceEnumTrait {
         ChoiceEnumTrait::values insteadof AutoDiscoveredValuesTrait;
     }