added Form::Enum validation rule for backed enums

Validates that a control's value is a valid case of a backed enum, catching
invalid input during form validation instead of letting it reach the typed
mapping sink (getValues(Dto::class)), where a non-member value would raise a
TypeError/ValueError and an unhandled HTTP 500.

Int-backed enums coerce the submitted string via filter_var() before tryFrom();
string-backed enums check is_string() + tryFrom(). The rule exports to JS as an
:equal membership check against the enum case values, so no new client-side
validator is needed. Passing a non-backed enum throws a clear
InvalidArgumentException instead of a cryptic fatal.

Author: dg

src/Forms/Form.php

@@ -48,6 +48,7 @@ class Form extends Container implements Nette\HtmlStringable
 		URL = ':url',
 		Pattern = ':pattern',
 		PatternInsensitive = ':patternCaseInsensitive',
+		Enum = ':enum',
 		Integer = ':integer',
 		Numeric = ':numeric',
 		Float = ':float',

src/Forms/Helpers.php

@@ -11,7 +11,7 @@
 use Nette\Utils\Html;
 use Nette\Utils\Image;
 use Nette\Utils\Strings;
-use function array_fill_keys, array_map, array_values, explode, filter_var, html_entity_decode, htmlspecialchars, in_array, ini_get, is_a, is_array, is_numeric, is_scalar, is_string, str_ends_with, str_replace, strip_tags, strpos, strtolower, strtr, substr, substr_replace;
+use function array_column, array_fill_keys, array_map, array_values, explode, filter_var, html_entity_decode, htmlspecialchars, in_array, ini_get, is_a, is_array, is_numeric, is_scalar, is_string, str_ends_with, str_replace, strip_tags, strpos, strtolower, strtr, substr, substr_replace;
 
 
 /**
@@ -149,7 +149,11 @@ public static function exportRules(Rules $rules): array
 				$item = ['op' => ($rule->isNegative ? '~' : '') . $op, 'msg' => $msg];
 			}
 
-			if (is_array($rule->arg)) {
+			if ($op === Form::Enum && is_string($rule->arg) && is_a($rule->arg, \BackedEnum::class, allow_string: true)) {
+				// the enum validator has no JS counterpart; export as membership check against the case values
+				$item['op'] = ($rule->isNegative ? '~' : '') . Form::Equal;
+				$item['arg'] = array_column(($rule->arg)::cases(), 'value');
+			} elseif (is_array($rule->arg)) {
 				$item['arg'] = [];
 				foreach ($rule->arg as $key => $value) {
 					$item['arg'][$key] = self::exportArgument($value, $rule->control);

src/Forms/Validator.php

@@ -10,7 +10,7 @@
 use Nette;
 use Nette\Utils\Strings;
 use Nette\Utils\Validators;
-use function array_map, count, explode, in_array, is_array, is_float, is_int, is_object, is_string, preg_replace, preg_replace_callback, rtrim, str_replace, strtolower;
+use function array_map, count, explode, filter_var, in_array, is_a, is_array, is_float, is_int, is_object, is_string, preg_replace, preg_replace_callback, rtrim, str_replace, strtolower;
 
 
 /**
@@ -32,6 +32,7 @@ final class Validator
 		Form::Length => 'Please enter a value between %d and %d characters long.',
 		Form::Email => 'Please enter a valid email address.',
 		Form::URL => 'Please enter a valid URL.',
+		Form::Enum => 'Please select a valid option.',
 		Form::Integer => 'Please enter a valid integer.',
 		Form::Float => 'Please enter a valid number.',
 		Form::Min => 'Please enter a value greater than or equal to %d.',
@@ -310,6 +311,32 @@ public static function validatePatternCaseInsensitive(Control $control, string $
 	}
 
 
+	/**
+	 * Checks whether the control's value is a valid case of the given backed enum.
+	 * @param  class-string  $enum  backed enum class
+	 */
+	public static function validateEnum(Control $control, string $enum): bool
+	{
+		if (!is_a($enum, \BackedEnum::class, allow_string: true)) {
+			throw new Nette\InvalidArgumentException("The Enum validator requires a backed enum class, '$enum' given.");
+		}
+
+		$intBacked = (new \ReflectionEnum($enum))->getBackingType()?->getName() === 'int';
+		foreach (static::toArray($control->getValue()) as $value) {
+			if ($intBacked) {
+				$value = filter_var($value, FILTER_VALIDATE_INT, FILTER_NULL_ON_FAILURE);
+				if ($value === null || $enum::tryFrom($value) === null) {
+					return false;
+				}
+			} elseif (!is_string($value) || $enum::tryFrom($value) === null) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+
 	/**
 	 * Checks whether the control's value is a non-negative integer string or int.
 	 */

tests/Forms/Rules.enum.phpt

@@ -0,0 +1,118 @@
+<?php declare(strict_types=1);
+
+/**
+ * Test: Nette\Forms\Form::Enum validation rule.
+ */
+
+use Nette\Forms\Form;
+use Nette\Forms\Helpers;
+use Tester\Assert;
+
+
+require __DIR__ . '/../bootstrap.php';
+
+
+enum StringEnum: string
+{
+	case Active = 'active';
+	case Inactive = 'inactive';
+}
+
+enum IntEnum: int
+{
+	case One = 1;
+	case Two = 2;
+}
+
+enum PureEnum
+{
+	case X;
+	case Y;
+}
+
+
+test('string-backed enum accepts a valid case and rejects others', function () {
+	$form = new Form;
+	$input = $form->addText('status');
+	$input->addRule(Form::Enum, null, StringEnum::class);
+
+	$input->setValue('active');
+	Assert::true($input->getRules()->validate());
+
+	$input->setValue('bogus');
+	Assert::false($input->getRules()->validate());
+	Assert::same(['Please select a valid option.'], $input->getErrors());
+});
+
+
+test('int-backed enum coerces submitted strings and rejects non-members', function () {
+	$form = new Form;
+	$input = $form->addText('value');
+	$input->addRule(Form::Enum, null, IntEnum::class);
+
+	$input->setValue('1'); // HTTP values arrive as strings
+	Assert::true($input->getRules()->validate());
+
+	$input->setValue('9'); // valid type, unknown case
+	Assert::false($input->getRules()->validate());
+
+	$input->setValue('abc'); // non-numeric, was TypeError before
+	Assert::false($input->getRules()->validate());
+});
+
+
+test('empty optional field skips the enum rule', function () {
+	$form = new Form;
+	$input = $form->addText('status');
+	$input->setRequired(false);
+	$input->addRule(Form::Enum, null, StringEnum::class);
+
+	$input->setValue('');
+	Assert::true($input->getRules()->validate());
+});
+
+
+test('multi-value control validates every item', function () {
+	$form = new Form;
+	$input = $form->addMultiSelect('tags', null, ['active' => 'A', 'inactive' => 'B', 'x' => 'X']);
+	$input->addRule(Form::Enum, null, StringEnum::class);
+
+	$input->setValue(['active', 'inactive']);
+	Assert::true($input->getRules()->validate());
+
+	$input->setValue(['active', 'x']);
+	Assert::false($input->getRules()->validate());
+});
+
+
+test('the rule exports to JS as a membership check against case values', function () {
+	$form = new Form;
+	$input = $form->addText('status');
+	$input->addRule(Form::Enum, 'Choose wisely', StringEnum::class);
+
+	Assert::same([
+		['op' => ':equal', 'msg' => 'Choose wisely', 'arg' => ['active', 'inactive']],
+	], Helpers::exportRules($input->getRules()));
+
+	$form2 = new Form;
+	$input2 = $form2->addText('value');
+	$input2->addRule(Form::Enum, 'Choose wisely', IntEnum::class);
+
+	Assert::same([
+		['op' => ':equal', 'msg' => 'Choose wisely', 'arg' => [1, 2]],
+	], Helpers::exportRules($input2->getRules()));
+});
+
+
+test('a non-backed enum yields a clear exception instead of a cryptic fatal', function () {
+	$form = new Form;
+	$input = $form->addText('status');
+	$input->addRule(Form::Enum, null, PureEnum::class);
+	$input->setValue('X');
+
+	Assert::exception(
+		fn() => $input->getRules()->validate(),
+		Nette\InvalidArgumentException::class,
+		"The Enum validator requires a backed enum class, '%a%' given.",
+	);
+});