feat(support): add enums support (#878)

Co-authored-by: Brent Roose <[email protected]>

Author: gturpin-dev

src/Tempest/Console/src/HasConsole.php

@@ -70,7 +70,7 @@ public function confirm(
         string $question,
         bool $default = false,
         ?string $yes = null,
-        ?string $no = null
+        ?string $no = null,
     ): bool {
         return $this->console->confirm(
             question: $question,

src/Tempest/Support/src/IsEnumHelper.php

@@ -0,0 +1,237 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Support;
+
+use ValueError;
+use UnitEnum;
+use Traversable;
+use Tempest\Support\ArrayHelper;
+use IteratorAggregate;
+use Iterator;
+use InvalidArgumentException;
+use BackedEnum;
+use ArrayIterator;
+
+/**
+ * This trait provides a bunch of helper methods to work with enums
+ *
+ * @template TEnum of \UnitEnum
+ */
+trait IsEnumHelper
+{
+    /**
+     * Gets the enum case by name
+     *
+     * @throws ValueError if the case name is not valid
+     */
+    public static function fromName(string $name): static
+    {
+        return static::tryFromName($name) ?? throw new ValueError(sprintf('"%s" is not a valid case name for enum "%s"', $name, static::class));
+    }
+
+    /**
+     * Gets the enum case by name or null if the case name is not valid
+     */
+    public static function tryFromName(string $name): ?static
+    {
+        $cases = array_filter(
+            static::cases(),
+            fn (UnitEnum $case) => $case->name === $name,
+        );
+
+        return array_shift($cases);
+    }
+
+    /**
+     * Gets the enum case by name, for Pure enums
+     * This will not override the `from()` method for Backed enums
+     */
+    public static function from(string $case): static
+    {
+        return static::fromName($case);
+    }
+
+    /**
+     * Gets the enum case by name, for Pure enums or null if the case is not valid
+     * This will not override the `tryFrom()` method for Backed enums
+     */
+    public static function tryFrom(string $case): ?static
+    {
+        return static::tryFromName($case);
+    }
+
+    /**
+     * Check if the current enum case is equal to the given enum
+     *
+     * @param UnitEnum $enum The enum to compare
+     *
+     * @return bool True if the enums are equal, false otherwise
+     */
+    public function is(UnitEnum $enum): bool
+    {
+        return $this === $enum;
+    }
+
+    /**
+     * Check if the current enum case is not equal to the given enum
+     *
+     * @param UnitEnum $enum The enum to compare
+     *
+     * @return bool True if the enums are not equal, false otherwise
+     */
+    public function isNot(UnitEnum $enum): bool
+    {
+        return ! $this->is($enum);
+    }
+
+    /**
+     * Check if the current enum case is in the given list of enums
+     *
+     * @param Traversable<UnitEnum>|array<UnitEnum> $enums The list of enums to check
+     *
+     * @return bool True if the current enum is in the list, false otherwise
+     */
+    public function in(Traversable|array $enums): bool
+    {
+        $iterator = match (true) {
+            is_array($enums) => new ArrayIterator($enums),
+            $enums instanceof Iterator => $enums,
+            $enums instanceof IteratorAggregate => $enums->getIterator(),
+            default => throw new InvalidArgumentException(sprintf('The given value must be an iterable value, "%s" given', get_debug_type($enums))),
+        };
+
+        foreach ($iterator as $enum) {
+            if ($this->is($enum)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Check if the current enum case is not in the given list of enums
+     *
+     * @param Traversable<UnitEnum>|array<UnitEnum> $enums The list of enums to check
+     *
+     * @return bool True if the current enum is not in the list, false otherwise
+     */
+    public function notIn(Traversable|array $enums): bool
+    {
+        return ! $this->in($enums);
+    }
+
+    /**
+     * Check if the current enum has the name in its cases
+     *
+     * @param string $name The enum case name
+     *
+     * @return bool True if the name is in the enum, false otherwise
+     */
+    public static function has(string $name): bool
+    {
+        $caseNames = array_column(static::cases(), 'name');
+
+        return in_array($name, $caseNames, strict: true); /** @phpstan-ignore-line function.impossibleType ( prevent to always evaluate to true/false as in enum context the result is predictable ) */
+    }
+
+    /**
+     * Check if the current enum does not have the name in its cases
+     *
+     * @param string $name The enum case name
+     *
+     * @return bool True if the name is not in the enum, false otherwise
+     */
+    public static function hasNot(string $name): bool
+    {
+        return ! self::has($name);
+    }
+
+    /**
+     * Check if the current enum has the value in its cases
+     * For Pure enums, this method is the equivalent of `has()`
+     *
+     * @param string|int $value The value to check
+     *
+     * @return bool True if the value is in the enum, false otherwise
+     */
+    public static function hasValue(string|int $value): bool
+    {
+        /** @var class-string<TEnum> */
+        $class = static::class;
+
+        $caseValues = is_subclass_of($class, BackedEnum::class)
+            ? array_column(static::cases(), 'value')
+            : array_column(static::cases(), 'name');
+
+        return in_array($value, $caseValues, strict: true);  /** @phpstan-ignore-line function.impossibleType ( prevent to always evaluate to true/false as in enum context the result is predictable ) */
+    }
+
+    /**
+     * Check if the current enum does not have the value in its cases
+     * For Pure enums, this method is the equivalent of `hasNot()`
+     *
+     * @param string|int $value The value to check
+     *
+     * @return bool True if the value is not in the enum, false otherwise
+     */
+    public static function hasNotValue(string|int $value): bool
+    {
+        return ! self::hasValue($value);
+    }
+
+    /**
+     * Gets an array of case names
+     * Both pure and backed enums will return their names
+     *
+     * @return array<int, string>
+     */
+    public static function names(): array
+    {
+        return array_column(static::cases(), 'name');
+    }
+
+    /**
+     * Gets an array of case values
+     * Pure enums will return their names, backed enums will return their values
+     *
+     * @return array<int, int|string>
+     */
+    public static function values(): array
+    {
+        /** @var class-string<TEnum> */
+        $class = static::class;
+
+        return is_subclass_of($class, BackedEnum::class)
+            ? array_column(static::cases(), 'value')
+            : array_column(static::cases(), 'name');
+    }
+
+    /**
+     * Wrap all enum cases in an array
+     *
+     * @return ArrayHelper<static>
+     */
+    public static function collect(): ArrayHelper
+    {
+        return arr(static::cases());
+    }
+
+    /**
+     * Returns an associative array of case names and values
+     * For pure enums, this method is the equivalent of `values()`
+     *
+     * @return array<int|string, int|string>
+     */
+    public static function options(): array
+    {
+        /** @var class-string<TEnum> */
+        $class = static::class;
+
+        return is_subclass_of($class, BackedEnum::class)
+            ? array_column(static::cases(), 'value', 'name')
+            : self::values();
+    }
+}

src/Tempest/Support/tests/Fixtures/Enums/EmptyEnum.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Support\Tests\Fixtures\Enums;
+
+use Tempest\Support\IsEnumHelper;
+
+enum EmptyEnum: string
+{
+    use IsEnumHelper;
+}

src/Tempest/Support/tests/Fixtures/Enums/SampleIntegerBackedEnum.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Support\Tests\Fixtures\Enums;
+
+use Tempest\Support\IsEnumHelper;
+
+enum SampleIntegerBackedEnum: int
+{
+    use IsEnumHelper;
+
+    case SUCCESS = 200;
+    case CREATED = 201;
+    case NOT_FOUND = 404;
+    case SERVER_ERROR = 500;
+}

src/Tempest/Support/tests/Fixtures/Enums/SampleStatusBackedEnum.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Support\Tests\Fixtures\Enums;
+
+use Tempest\Support\IsEnumHelper;
+
+enum SampleStatusBackedEnum: string
+{
+    use IsEnumHelper;
+
+    case PUBLISH = 'publish';
+    case DRAFT = 'draft';
+    case TRASH = 'trash';
+}

src/Tempest/Support/tests/Fixtures/Enums/SampleStatusPureEnum.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Support\Tests\Fixtures\Enums;
+
+use Tempest\Support\IsEnumHelper;
+
+enum SampleStatusPureEnum
+{
+    use IsEnumHelper;
+
+    case PUBLISH;
+    case DRAFT;
+    case TRASH;
+}