WIP introduced Psalm templates with ability to restrict possible valu…

…es on type level

psalm.xml

@@ -1,14 +1,17 @@
 <?xml version="1.0"?>
 <psalm
     errorLevel="1"
+    findUnusedCode="false"
     resolveFromConfigFile="true"
+    findUnusedBaselineEntry="true"
     findUnusedPsalmSuppress="false"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd">
 
     <projectFiles>
         <directory name="src" />
+        <directory name="tests/Psalm" />
         <ignoreFiles>
             <directory name="vendor" />
         </ignoreFiles>
@@ -30,6 +33,11 @@
                 <file name="src/Doctrine/PlatenumDoctrineType.php" />
             </errorLevel>
         </DeprecatedMethod>
+        <ImpureByReferenceAssignment errorLevel="error">
+            <errorLevel type="suppress">
+                <file name="src/Enum/EnumTrait.php" />
+            </errorLevel>
+        </ImpureByReferenceAssignment>
     </issueHandlers>
 
 </psalm>

src/Doctrine/PlatenumDoctrineType.php

@@ -6,7 +6,10 @@
 use Doctrine\DBAL\Types\Type;
 use Thunder\Platenum\Enum\EnumTrait;
 
-/** @psalm-suppress PropertyNotSetInConstructor, MissingConstructor */
+/**
+ * @psalm-suppress PropertyNotSetInConstructor, MissingConstructor
+ * @psalm-external-mutation-free
+ */
 final class PlatenumDoctrineType extends Type
 {
     /** @var class-string */
@@ -107,6 +110,7 @@ public function getName(): string
 
     public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return ($this->platenumSql)($column, $platform);
     }
 
@@ -120,7 +124,7 @@ public function convertToDatabaseValue($value, AbstractPlatform $platform)
             throw new \LogicException(sprintf($message, self::class, gettype($value)));
         }
 
-        /** @psalm-suppress MixedMethodCall */
+        /** @psalm-suppress MixedMethodCall,ImpureFunctionCall */
         return ($this->platenumCallback)($value->getValue());
     }
 
@@ -130,7 +134,7 @@ public function convertToPHPValue($value, AbstractPlatform $platform)
             return null;
         }
 
-        /** @psalm-suppress MixedMethodCall */
+        /** @psalm-suppress MixedMethodCall,ImpureFunctionCall */
         return ($this->platenumClass)::fromValue(($this->platenumCallback)($value));
     }
 

src/Enum/AbstractCallbackEnum.php

@@ -4,8 +4,11 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 abstract class AbstractCallbackEnum implements \JsonSerializable
 {
+    /** @use CallbackEnumTrait<T> */
     use CallbackEnumTrait;
 }

src/Enum/AbstractConstantsEnum.php

@@ -4,8 +4,11 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 abstract class AbstractConstantsEnum implements \JsonSerializable
 {
+    /** @use ConstantsEnumTrait<T> */
     use ConstantsEnumTrait;
 }

src/Enum/AbstractDocblockEnum.php

@@ -4,8 +4,11 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 abstract class AbstractDocblockEnum implements \JsonSerializable
 {
+    /** @use DocblockEnumTrait<T> */
     use DocblockEnumTrait;
 }

src/Enum/AbstractStaticEnum.php

@@ -4,9 +4,12 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 abstract class AbstractStaticEnum implements \JsonSerializable
 {
+    /** @use StaticEnumTrait<T> */
     use StaticEnumTrait;
 
     /** @var array */

src/Enum/CallbackEnumTrait.php

@@ -6,9 +6,12 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 trait CallbackEnumTrait
 {
+    /** @use EnumTrait<T> */
     use EnumTrait;
 
     /** @var non-empty-array<class-string,callable():array<string,int|string>> */

src/Enum/ConstantsEnumTrait.php

@@ -4,9 +4,12 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 trait ConstantsEnumTrait
 {
+    /** @use EnumTrait<T> */
     use EnumTrait;
 
     private static function resolve(): array

src/Enum/DocblockEnumTrait.php

@@ -6,9 +6,12 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 trait DocblockEnumTrait
 {
+    /** @use EnumTrait<T> */
     use EnumTrait;
 
     private static function resolve(): array

src/Enum/EnumTrait.php

@@ -6,20 +6,22 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 trait EnumTrait
 {
     /** @var string */
     private $member;
-    /** @var int|string */
+    /** @psalm-var T */
     private $value;
 
-    /** @var non-empty-array<string,non-empty-array<string,int|string>> */
+    /** @psalm-var non-empty-array<string,non-empty-array<string,int|string>> */
     protected static $members = [];
     /** @var array<string,array<string,static>> */
     protected static $instances = [];
 
-    /** @param int|string $value */
+    /** @psalm-param T $value */
     /* final */ private function __construct(string $member, $value)
     {
         $this->member = $member;
@@ -51,8 +53,18 @@ final public static function fromMember(string $member): self
             static::throwDefaultInvalidMemberException($member);
         }
 
+        /** @psalm-suppress PropertyTypeCoercion */
+        return static::$instances[$class][$member] = static::fromMemberAndValue($member, static::$members[$class][$member]);
+    }
+
+    /**
+     * @psalm-param int|string $value
+     * @psalm-return static
+     */
+    /* final */ private static function fromMemberAndValue(string $member, $value): self
+    {
         /** @psalm-suppress UnsafeInstantiation */
-        return static::$instances[$class][$member] = new static($member, static::$members[$class][$member]);
+        return new static($member, $value);
     }
 
     /**
@@ -91,12 +103,15 @@ final public static function fromEnum($enum): self
     }
 
     /**
-     * @param static $enum
-     * @param-out AbstractConstantsEnum|AbstractDocblockEnum|AbstractStaticEnum|AbstractCallbackEnum|AbstractAttributeEnum $enum
+     * @param self &$enum
+     * @param-out self $enum
+     * @psalm-suppress ReferenceConstraintViolation
      */
     final public function fromInstance(&$enum): void
     {
-        $enum = static::fromEnum($enum);
+        /** @psalm-suppress ImpureMethodCall,ArgumentTypeCoercion */
+        $instance = static::fromEnum($enum);
+        $enum = $instance;
     }
 
     /**
@@ -154,12 +169,13 @@ final public function getMember(): string
         return $this->member;
     }
 
-    /** @return int|string */
+    /** @psalm-return T */
     final public function getValue()
     {
         return $this->value;
     }
 
+    /** @psalm-return T */
     #[\ReturnTypeWillChange]
     final public function jsonSerialize()
     {
@@ -209,7 +225,7 @@ final public function hasMember(string $members): bool
         return $members === $this->member;
     }
 
-    /** @param int|string $value */
+    /** @psalm-param T $value */
     final public function hasValue($value): bool
     {
         return $value === $this->value;
@@ -293,7 +309,7 @@ private static function resolveMembers(): void
         // reflection instead of method_exists because of PHP 7.4 bug #78632
         // @see https://bugs.php.net/bug.php?id=78632
         $hasResolve = (new \ReflectionClass($class))->hasMethod('resolve');
-        /** @var array<string,int|string> $members */
+        /** @psalm-var array<string,T> $members */
         $members = $hasResolve ? static::resolve() : $throwMissingResolve($class);
         if(empty($members)) {
             throw PlatenumException::fromEmptyMembers($class);
@@ -308,6 +324,7 @@ private static function resolveMembers(): void
             throw PlatenumException::fromNonUniformMemberValues($class, $members);
         }
 
+        /** @psalm-suppress MixedPropertyTypeCoercion */
         static::$members[$class] = $members;
     }
 

src/Enum/StaticEnumTrait.php

@@ -6,9 +6,12 @@
 
 /**
  * @author Tomasz Kowalczyk <[email protected]>
+ * @psalm-template T
+ * @psalm-immutable
  */
 trait StaticEnumTrait
 {
+    /** @use EnumTrait<T> */
     use EnumTrait;
 
     private static function resolve(): array

tests/Psalm/PsalmConstantsExtendsEnum.php

@@ -0,0 +1,18 @@
+<?php
+declare(strict_types=1);
+namespace Thunder\Platenum\Tests\Psalm;
+
+use Thunder\Platenum\Enum\AbstractConstantsEnum;
+
+/**
+ * @method static static FIRST()
+ * @method static static SECOND()
+ * @template-extends AbstractConstantsEnum<self::FIRST|self::SECOND>
+ * @psalm-immutable
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class PsalmConstantsExtendsEnum extends AbstractConstantsEnum
+{
+    public const FIRST = 1;
+    public const SECOND = 2;
+}

tests/Psalm/PsalmConstantsTraitEnum.php

@@ -0,0 +1,20 @@
+<?php
+declare(strict_types=1);
+namespace Thunder\Platenum\Tests\Psalm;
+
+use Thunder\Platenum\Enum\ConstantsEnumTrait;
+
+/**
+ * @method static static FIRST()
+ * @method static static SECOND()
+ * @psalm-template T self::FIRST|self::SECOND
+ * @psalm-immutable
+ */
+final class PsalmConstantsTraitEnum
+{
+    /** @use ConstantsEnumTrait<T> */
+    use ConstantsEnumTrait;
+
+    public const FIRST = 1;
+    public const SECOND = 2;
+}

tests/Psalm/PsalmEnum.php

@@ -0,0 +1,17 @@
+<?php
+declare(strict_types=1);
+namespace Thunder\Platenum\Tests\Psalm;
+
+final class PsalmEnum
+{
+}
+
+PsalmConstantsTraitEnum::FIRST();
+PsalmConstantsTraitEnum::SECOND();
+PsalmConstantsTraitEnum::fromMember('THIRD');
+PsalmConstantsTraitEnum::fromValue(4);
+
+PsalmConstantsExtendsEnum::FIRST();
+PsalmConstantsExtendsEnum::SECOND();
+PsalmConstantsExtendsEnum::fromMember('THIRD');
+PsalmConstantsExtendsEnum::fromValue(4);