orisai/object-mapper – strict data validation and mapping to objects

Another of my children from Orisai family is mature enough to be released into the wild. Today it's
the orisai/object-mapper and its integration into
Nette, orisai/nette-object-mapper. Object-based validator and data mapper.

Usage is quite simple

1. define an object, add validation rules above properties which should be mapped
2. get Processor instance from DI
3. pass data to Processor along with name of the class to which the data shall be mapped
4. if an exception is thrown, pass it to the ErrorPrinter

use Orisai\ObjectMapper\MappedObject;
use Orisai\ObjectMapper\Rules\MappedObjectValue;
use Orisai\ObjectMapper\Rules\StringValue;

final class UserInput implements MappedObject
{

	#[StringValue(notEmpty: true)]
	public string $firstName;

	#[StringValue(notEmpty: true)]
	public string $lastName;

	#[MappedObjectValue(UserAddressInput::class)]
	public UserAddressInput $address;

}

use Orisai\ObjectMapper\MappedObject;

final class UserAddressInput implements MappedObject
{
	// ...
}

use Orisai\ObjectMapper\Exception\InvalidData;
use Orisai\ObjectMapper\Printers\ErrorVisualPrinter;
use Orisai\ObjectMapper\Printers\TypeToStringConverter;
use Orisai\ObjectMapper\Processing\Processor;

$processor = $container->getByType(Processor::class);
$errorPrinter = new ErrorVisualPrinter(new TypeToStringConverter());

$data = [
	'firstName' => 'Tony',
	'lastName' => 'Stark',
	'address' => [],
];

try {
	$user = $processor->process($data, UserInput::class);
} catch (InvalidData $exception) {
	$error = $errorPrinter->printError($exception);

	throw new Exception("Validation failed due to following error:\n$error");
}

echo "User name is: {$user->firstName} {$user->lastName}";

Implemented features

Rules.
Each property has to define a rule to be validated and mapped. And there is a few of them already – for scalar
values like int, string and bool, for null, for arrays and lists, for combining rules via || and &&, for nested
mapped objects and for value objects like datetime and enums,

use Orisai\ObjectMapper\Processing\MappedObject;
use Orisai\ObjectMapper\Rules\AnyOf;
use Orisai\ObjectMapper\Rules\NullValue;
use Orisai\ObjectMapper\Rules\StringValue;

class ExampleInput implements MappedObject
{

	#[AnyOf([
		new StringValue(),
		new NullValue(),
	])]
	public string $stringOrNull;

}

Callbacks.
Before and after each mapped object and field processing, extra data validations and transformations can be done.

use Orisai\ObjectMapper\Callbacks\Before;
use Orisai\ObjectMapper\Processing\MappedObject;
use Orisai\ObjectMapper\Rules\StringValue;

#[Before('beforeCallback')]
class CallbackUsingInput implements MappedObject
{

	#[StringValue]
	public string $string;

	private function beforeCallback(mixed $value): mixed
	{
		// BC, before object was implemented only string was expected in its place
		if (is_string($value)) {
			$value = ['string' => $value];
		}

		return $value;
	}

}

Field names.
By default, field names on input match names of mapped properties, but the field name can be changed to any string or
int.

use Orisai\ObjectMapper\MappedObject;
use Orisai\ObjectMapper\Modifiers\FieldName;
use Orisai\ObjectMapper\Rules\MixedValue;

final class CustomMappingInput implements MappedObject
{

     #[MixedValue]
     #[FieldName('customFieldName')]
    public mixed $property;

}

$data = [
	'customFieldName' => 'anything',
];
$input = $processor->process($data, CustomMappingInput::class);
// $input == CustomMappingInput(property: 'anything')

Processing modes.
Does your API support PATCH requests and only need to send changed fields and not the others,
otherwise required fields? There's a mode for that. Do you need to send all fields, including otherwise optional ones?
Yeah, another mode.

Annotations and attributes.
All rules, callbacks and other types of definitions can be written as doctrine annotations
as well as PHP 8 attributes. PHP attributes are great, but they are fully usable only since PHP 8.1. With doctrine
annotations PHP 7.4+ is also supported.

Error printers.
All errors are represented by an abstract structure and the whole hierarchy can be printed to a string
or an array. If you need to, you can easily come up with your own format.

Type printers.
Mapped object can be printed the same way the errors are for easy overview of the expected data.

If you would like to know about all the current features and how to use them,
please read the docs. It
would be way to long for this post to explain everything.

Implemented, yet undocumented

Custom rules. There is still some work left that has to be done around metadata validation and documentation, but it
should be quite simple to implement your own rules. Take inspiration in the existing ones.

Validation without mapping. It is possible to just validate data, without mapping them to objects. Helpful in case you
need to save the raw, yet valid data for later. I am just not sure yet how to handle this feature in callbacks and if it
should cover just object mapping or include any data transformations, e.g. casting numeric-string to an int.

Skipped fields. It is possible to completely skip some mapped fields during validation and validate them separately
later during the request, when an additional required context is available. I implemented this feature long time ago and
I no longer have a use case for it, and I am unsure whether I should keep it. Let me know if it sounds like something
you would find helpful.

Last edited by Marek Bartoš (2023-07-05 19:29)