added Expect::enum()

Author: dg

src/Schema/Expect.php

@@ -175,4 +175,19 @@ public static function listable(string|Schema $type): Type
 			->items($type)
 			->before(fn($value) => is_array($value) || $value === null ? $value : [$value]);
 	}
+
+
+	/**
+	 * Creates a schema for a backed enum case, given as the case itself or its backing value.
+	 * @param  class-string<\BackedEnum>  $class
+	 */
+	public static function enum(string $class): Type
+	{
+		if (!is_subclass_of($class, \BackedEnum::class)) {
+			throw new Nette\InvalidArgumentException("Class '$class' is not a backed enum.");
+		}
+
+		$backing = (string) (new \ReflectionEnum($class))->getBackingType();
+		return (new Type("$backing|$class"))->castTo($class);
+	}
 }

src/Schema/Helpers.php

@@ -125,7 +125,7 @@ public static function getCastStrategy(string $type): \Closure
 		} elseif (is_subclass_of($type, \BackedEnum::class)) {
 			return static function ($value, Context $context) use ($type) {
 				try {
-					return $type::from($value);
+					return $value === null || $value instanceof $type ? $value : $type::from($value);
 				} catch (\TypeError | \ValueError) {
 					$context->addError(
 						'The %label% %path% expects to be %expected%, %value% given.',

tests/Schema/Expect.enum.phpt

@@ -25,3 +25,79 @@ test('unit enum as standalone type', function () {
 		(new Processor)->process($schema, 'Clubs');
 	}, ['The item expects to be Suit, \'Clubs\' given.']);
 });
+
+
+enum Color: string
+{
+	case Red = 'red';
+	case Blue = 'blue';
+}
+
+enum Level: int
+{
+	case Low = 1;
+	case High = 2;
+}
+
+
+test('backing value is cast to a case', function () {
+	Assert::same(Color::Red, (new Processor)->process(Expect::enum(Color::class), 'red'));
+	Assert::same(Level::High, (new Processor)->process(Expect::enum(Level::class), 2));
+});
+
+
+test('case instance passes through', function () {
+	Assert::same(Color::Blue, (new Processor)->process(Expect::enum(Color::class), Color::Blue));
+});
+
+
+test('invalid value lists the allowed ones', function () {
+	checkValidationErrors(function () {
+		(new Processor)->process(Expect::enum(Color::class), 'green');
+	}, ["The item expects to be 'red'|'blue', 'green' given."]);
+
+	checkValidationErrors(function () {
+		(new Processor)->process(Expect::enum(Level::class), 3);
+	}, ['The item expects to be 1|2, 3 given.']);
+});
+
+
+test('wrong type is rejected before casting', function () {
+	checkValidationErrors(function () {
+		(new Processor)->process(Expect::enum(Color::class), []);
+	}, ['The item expects to be string or Color, array given.']);
+});
+
+
+test('default and nullable', function () {
+	$schema = Expect::structure([
+		'color' => Expect::enum(Color::class)->default(Color::Red),
+		'level' => Expect::enum(Level::class)->nullable(),
+	]);
+
+	Assert::equal(
+		(object) ['color' => Color::Red, 'level' => null],
+		(new Processor)->process($schema, []),
+	);
+
+	Assert::equal(
+		(object) ['color' => Color::Blue, 'level' => null],
+		(new Processor)->process($schema, ['color' => 'blue', 'level' => null]),
+	);
+});
+
+
+testException(
+	'pure enum is rejected',
+	fn() => Expect::enum(Suit::class),
+	Nette\InvalidArgumentException::class,
+	"Class 'Suit' is not a backed enum.",
+);
+
+
+testException(
+	'ordinary class is rejected',
+	fn() => Expect::enum(stdClass::class),
+	Nette\InvalidArgumentException::class,
+	"Class 'stdClass' is not a backed enum.",
+);