feat: added support for enum values in request parameter

Author: rasstislav

.docs/mapping.md

@@ -66,6 +66,7 @@ class UsersController extends BaseV1Controller
 - `required=true|false` - required by default, but you could make parameter optional
 - `deprecated=true|false` - used in [openapi](schema.md#openapi) schema
 - `allowEmpty=true|false` - make parameter nullable
+- `enum={"only", "these", "values"}` - allowable values
 
 ### Data types
 
@@ -105,6 +106,7 @@ api:
                 float: Apitte\Core\Mapping\Parameter\FloatTypeMapper
                 bool: Apitte\Core\Mapping\Parameter\BooleanTypeMapper
                 datetime: Apitte\Core\Mapping\Parameter\DateTimeTypeMapper
+                enum: Apitte\Core\Mapping\Parameter\EnumTypeMapper
 ```
 
 ### Custom datatypes

src/Core/Annotation/Controller/RequestParameter.php

@@ -31,14 +31,17 @@ class RequestParameter
 
 	private bool $allowEmpty;
 
+	private ?array $enum;
+
 	public function __construct(
 		string $name,
 		string $type,
 		string $in = EndpointParameter::IN_PATH,
 		bool $required = true,
 		bool $allowEmpty = false,
 		bool $deprecated = false,
-		?string $description = null
+		?string $description = null,
+		?array $enum = null
 	)
 	{
 		if ($name === '') {
@@ -60,6 +63,7 @@ public function __construct(
 		$this->deprecated = $deprecated;
 		$this->description = $description;
 		$this->in = $in;
+		$this->enum = $enum;
 	}
 
 	public function getName(): string
@@ -97,4 +101,9 @@ public function isAllowEmpty(): bool
 		return $this->allowEmpty;
 	}
 
+	public function getEnum(): ?array
+	{
+		return $this->enum;
+	}
+
 }

src/Core/DI/Loader/DoctrineAnnotationLoader.php

@@ -317,6 +317,7 @@ private function addEndpointParameterToSchemaMethod(SchemaMethod $schemaMethod,
 		$endpointParameter->setRequired($requestParameter->isRequired());
 		$endpointParameter->setDeprecated($requestParameter->isDeprecated());
 		$endpointParameter->setAllowEmpty($requestParameter->isAllowEmpty());
+		$endpointParameter->setEnum($requestParameter->getEnum());
 	}
 
 	private function addNegotiationToSchemaMethod(SchemaMethod $schemaMethod, Negotiation $negotiation): void

src/Core/DI/Loader/NeonLoader.php

@@ -69,6 +69,7 @@ private function setEndpointParameters(Method $method, array $parametersSettings
 			$parameter->setRequired($settings['required'] ?? true);
 			$parameter->setAllowEmpty($settings['allowEmpty'] ?? false);
 			$parameter->setDeprecated($settings['deprecated'] ?? false);
+			$parameter->setEnum($settings['enum'] ?? null);
 		}
 	}
 

src/Core/DI/Plugin/CoreMappingPlugin.php

@@ -7,6 +7,7 @@
 use Apitte\Core\DI\ApiExtension;
 use Apitte\Core\Mapping\Parameter\BooleanTypeMapper;
 use Apitte\Core\Mapping\Parameter\DateTimeTypeMapper;
+use Apitte\Core\Mapping\Parameter\EnumTypeMapper;
 use Apitte\Core\Mapping\Parameter\FloatTypeMapper;
 use Apitte\Core\Mapping\Parameter\IntegerTypeMapper;
 use Apitte\Core\Mapping\Parameter\StringTypeMapper;
@@ -33,6 +34,7 @@ class CoreMappingPlugin extends Plugin
 		'float' => FloatTypeMapper::class,
 		'bool' => BooleanTypeMapper::class,
 		'datetime' => DateTimeTypeMapper::class,
+		'enum' => EnumTypeMapper::class,
 	];
 
 	public static function getName(): string

src/Core/Exception/Runtime/InvalidArgumentTypeException.php

@@ -11,6 +11,7 @@ class InvalidArgumentTypeException extends RuntimeException
 	public const TYPE_FLOAT = 'float';
 	public const TYPE_BOOLEAN = 'bool';
 	public const TYPE_DATETIME = 'datetime';
+	public const TYPE_ENUM = 'enum';
 
 	private string $type;
 

src/Core/Mapping/Parameter/EnumTypeMapper.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types = 1);
+
+namespace Apitte\Core\Mapping\Parameter;
+
+use Apitte\Core\Exception\Runtime\InvalidArgumentTypeException;
+
+class EnumTypeMapper implements ITypeMapper
+{
+
+	public function normalize(mixed $value, ?array $enumValues = null): string
+	{
+		if (!in_array($value, $enumValues)) {
+			throw new InvalidArgumentTypeException(InvalidArgumentTypeException::TYPE_ENUM);
+		}
+
+		return $value;
+	}
+
+}

src/Core/Mapping/Parameter/ITypeMapper.php

@@ -10,6 +10,6 @@ interface ITypeMapper
 	/**
 	 * @throws InvalidArgumentTypeException
 	 */
-	public function normalize(mixed $value): mixed;
+	public function normalize(mixed $value/*, ?array $enumValues = null*/): mixed;
 
 }

src/Core/Mapping/RequestParameterMapping.php

@@ -22,6 +22,7 @@ class RequestParameterMapping
 		InvalidArgumentTypeException::TYPE_FLOAT => '%s request parameter "%s" should be of type float or integer.',
 		InvalidArgumentTypeException::TYPE_BOOLEAN => '%s request parameter "%s" should be of type boolean. Pass "true" for true or "false" for false.',
 		InvalidArgumentTypeException::TYPE_DATETIME => '%s request parameter "%s" should be of type datetime in format ISO 8601 (Y-m-d\TH:i:sP).',
+		InvalidArgumentTypeException::TYPE_ENUM => '%s request parameter "%s" is not in the allowed values `[%s]`.',
 	];
 
 	protected static string $customException = '%s request parameter "%s" should be of type %s.%s';
@@ -210,13 +211,14 @@ protected function normalize(mixed $value, EndpointParameter $parameter, ITypeMa
 		}
 
 		try {
-			return $mapper->normalize($value);
+			return $mapper->normalize($value, $parameter->getEnum());
 		} catch (InvalidArgumentTypeException $e) {
 			if (array_key_exists($e->getType(), self::$exceptions)) {
 				throw new ClientErrorException(sprintf(
 					self::$exceptions[$e->getType()],
 					ucfirst($parameter->getIn()),
-					$parameter->getName()
+					$parameter->getName(),
+					$parameter->getEnum() ? implode(', ', $parameter->getEnum()) : ''
 				));
 			} else {
 				throw new ClientErrorException(sprintf(

src/Core/Schema/EndpointParameter.php

@@ -10,13 +10,15 @@ class EndpointParameter
 	public const TYPE_FLOAT = 'float';
 	public const TYPE_BOOLEAN = 'bool';
 	public const TYPE_DATETIME = 'datetime';
+	public const TYPE_ENUM = 'enum';
 
 	public const TYPES = [
 		self::TYPE_STRING,
 		self::TYPE_INTEGER,
 		self::TYPE_FLOAT,
 		self::TYPE_BOOLEAN,
 		self::TYPE_DATETIME,
+		self::TYPE_ENUM,
 	];
 
 	public const IN_QUERY = 'query';
@@ -45,6 +47,8 @@ class EndpointParameter
 
 	private bool $allowEmpty = false;
 
+	private ?array $enum = null;
+
 	public function __construct(string $name, string $type = self::TYPE_STRING)
 	{
 		$this->name = $name;
@@ -72,6 +76,8 @@ public function getSchemaType(): string
 				return 'boolean';
 			case self::TYPE_INTEGER:
 				return 'integer';
+			case self::TYPE_ENUM:
+				return 'string';
 			default:
 				// custom type
 				return 'string';
@@ -128,4 +134,14 @@ public function setAllowEmpty(bool $allowEmpty): void
 		$this->allowEmpty = $allowEmpty;
 	}
 
+	public function getEnum(): ?array
+	{
+		return $this->enum;
+	}
+
+	public function setEnum(?array $enum): void
+	{
+		$this->enum = $enum;
+	}
+
 }