Initial commit after upgrading to php 8.3 and splitting to seperated tool chain

src/EnumTrait.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tez\Utils\Enum;
+
+/**
+ * Base trait for pure (unit) enums.
+ * Provides identity checks, lookup, filtering, and ordering helpers.
+ * Use BackedEnumTrait instead when your enum has backing values.
+ *
+ * @phpstan-require-implements \UnitEnum
+ *
+ * @method static list<static> cases()
+ */
+trait EnumTrait
+{
+    /**
+     * Returns true if this case matches the given value by identity or name.
+     * Null always returns false.
+     */
+    public function is(int|string|\UnitEnum|null $value): bool
+    {
+        if ($value === null) {
+            return false;
+        }
+
+        if ($value === $this) {
+            return true;
+        }
+
+        if (is_string($value)) {
+            return $this->name === $value;
+        }
+
+        return false;
+    }
+
+    /** @return array<string, string> */
+    public static function toArray(): array
+    {
+        return array_reduce(
+            static::cases(),
+            static fn($carry, $case) => $carry + [$case->name => $case->name],
+            [],
+        );
+    }
+
+    /**
+     * Returns true if this case matches any value in the given list.
+     *
+     * @param int[]|string[]|\UnitEnum[]|null $values
+     */
+    public function isOneOf(?array $values): bool
+    {
+        foreach ($values ?? [] as $value) {
+            if ($this->is($value)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns true if this case does not match any value in the given list.
+     *
+     * @param int[]|string[]|\UnitEnum[]|null $values
+     */
+    public function isNoneOf(?array $values): bool
+    {
+        return !$this->isOneOf($values);
+    }
+
+    /**
+     * Finds a case by identity, name, or (for BackedEnums) backing value.
+     * Returns null when no match is found or when $value is null.
+     * Set $ignoreCase to true for case-insensitive name and string-value matching.
+     */
+    public static function find(\UnitEnum|string|int|null $value, bool $ignoreCase = false): ?static
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if ($value instanceof static) {
+            return $value;
+        }
+
+        foreach (self::cases() as $case) {
+            if ($case instanceof \BackedEnum && !($value instanceof \UnitEnum)) {
+                $caseVal   = $ignoreCase && is_string($case->value) ? strtoupper($case->value) : $case->value;
+                $searchVal = $ignoreCase && is_string($value) ? strtoupper($value) : $value;
+
+                if ($caseVal === $searchVal) {
+                    return $case;
+                }
+            }
+
+            if (is_string($value)) {
+                $caseName   = $ignoreCase ? strtoupper($case->name) : $case->name;
+                $searchName = $ignoreCase ? strtoupper($value) : $value;
+
+                if ($caseName === $searchName) {
+                    return $case;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns all cases for which the callback returns true.
+     *
+     * @return list<static>
+     */
+    public static function filter(callable $callback): array
+    {
+        return array_values(array_filter(static::cases(), $callback));
+    }
+
+    /** Returns the zero-based position of this case in the enum definition. */
+    public function ordinal(): int
+    {
+        $index = array_search($this, static::cases(), true);
+        assert($index !== false);
+
+        return $index;
+    }
+
+    /** Returns the first defined case. */
+    public static function first(): static
+    {
+        return static::cases()[0];
+    }
+
+    /** Returns the last defined case. */
+    public static function last(): static
+    {
+        $cases = static::cases();
+
+        return $cases[count($cases) - 1];
+    }
+}