From 454139ac83aa2f121a9dcb8f04d2fd58ea328dcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A0=82=E5=90=89=E8=AF=83=E5=BE=B7=E6=8B=89=E6=9B=BC?=
 =?UTF-8?q?=E6=9F=A5=E7=9A=84=E8=8B=B1=E8=B1=AA?= <devhalo@163.com>
Date: Thu, 6 Aug 2026 15:28:07 +0800
Subject: [PATCH] =?UTF-8?q?=E6=A0=B8=E5=BF=83=E5=BA=93=E6=96=B0=E5=A2=9EEn?=
 =?UTF-8?q?umTrait?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/Trait/EnumTrait.php | 126 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 src/Trait/EnumTrait.php

diff --git a/src/Trait/EnumTrait.php b/src/Trait/EnumTrait.php
new file mode 100644
index 0000000..b9b3832
--- /dev/null
+++ b/src/Trait/EnumTrait.php
@@ -0,0 +1,126 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Core\Trait;
+
+use InvalidArgumentException;
+use ReflectionClass;
+
+/**
+ * PHP 原生枚举辅助方法（values/descriptions/valueMap/fromValue 等）.
+ */
+trait EnumTrait
+{
+    public static function values(): array
+    {
+        self::validateEnumStructure();
+
+        $values = [];
+        foreach (self::cases() as $case) {
+            $values[] = $case->value;
+        }
+        return $values;
+    }
+
+    public static function descriptions(): array
+    {
+        self::validateEnumStructure();
+
+        $descriptions = [];
+        foreach (self::cases() as $case) {
+            $descriptions[] = $case->description();
+        }
+        return $descriptions;
+    }
+
+    public static function valueMap(): array
+    {
+        self::validateEnumStructure();
+
+        $map = [];
+        foreach (self::cases() as $case) {
+            $map[$case->value] = $case->description();
+        }
+        return $map;
+    }
+
+    public static function fromValue(int|string $value): self
+    {
+        self::validateEnumStructure();
+
+        $firstCase = self::cases()[0] ?? null;
+        if ($firstCase) {
+            $expectedType = gettype($firstCase->value);
+            $actualType = gettype($value);
+            if ($expectedType !== $actualType) {
+                throw new InvalidArgumentException(sprintf(
+                    '枚举值类型不匹配，%s期望%s类型，实际为%s',
+                    self::class,
+                    $expectedType,
+                    $actualType
+                ));
+            }
+        }
+
+        $enum = self::tryFrom($value);
+        if (! $enum) {
+            throw new InvalidArgumentException(sprintf(
+                '无效的%s值: %s，允许值: %s',
+                self::class,
+                $value,
+                implode(', ', self::values())
+            ));
+        }
+        return $enum;
+    }
+
+    public static function fromDescription(string $description): ?self
+    {
+        self::validateEnumStructure();
+
+        foreach (self::cases() as $case) {
+            if ($case->description() === $description) {
+                return $case;
+            }
+        }
+        return null;
+    }
+
+    public static function isValidValue(int|string $value): bool
+    {
+        self::validateEnumStructure();
+
+        foreach (self::cases() as $case) {
+            if ($case->value === $value) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static function validateEnumStructure(): void
+    {
+        if (! (new ReflectionClass(self::class))->isEnum()) {
+            throw new InvalidArgumentException(sprintf(
+                'EnumTrait仅允许枚举类使用，%s不是枚举',
+                self::class
+            ));
+        }
+
+        if (! method_exists(self::class, 'description')) {
+            throw new InvalidArgumentException(sprintf(
+                '枚举类%s必须实现description()方法（返回字符串描述）',
+                self::class
+            ));
+        }
+
+        $sampleCase = self::cases()[0] ?? null;
+        if ($sampleCase && ! is_string($sampleCase->description())) {
+            throw new InvalidArgumentException(sprintf(
+                '枚举类%s的description()方法必须返回字符串',
+                self::class
+            ));
+        }
+    }
+}