What is Valinor (valinor-php.dev)?

Valinor is a PHP library that maps arbitrary input into a strongly-typed value object structure. You reach for it when data arrives as loose arrays or decoded JSON and you want it to land in real PHP objects with typed properties, instead of passing arrays around and validating them by hand. It is a library you integrate into an existing application, not a framework or a standalone app.

The problem it addresses

PHP gives you no built-in way to say "this array must become a User with an int id and a DateTimeImmutable birthday." The usual workarounds are:

• Reading $data['id'] and casting it, hoping the key exists and holds the right type.
• Writing validation rules separately from the object that consumes the data.
• Letting arrays flow through the codebase, so type errors surface late, at the point of use.

Valinor targets that gap: input goes in, a typed object structure comes out, and mismatches are reported rather than silently accepted.

What "strongly-typed value object structure" means in practice

The mapping is not limited to flat scalars. A value object can contain nested objects, collections, and union types, and the library resolves the input into that shape. Conceptually:

final class User
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly DateTimeImmutable $birthday,
    ) {}
}

Given input such as ['id' => 42, 'name' => 'Ada', 'birthday' => '1990-01-01'], the library's job is to produce a User instance — converting the date string, enforcing int and string, and failing loudly if the input cannot satisfy the constructor.

Where it fits in a PHP project

Because it is scoped to mapping, it composes with whatever else you use: a framework's request handling, a queue consumer, an API client, or a plain script.

When it is a good fit

• You decode JSON or receive arrays from an external boundary and want typed objects immediately.
• You want type errors to appear at the mapping step rather than deep inside business logic.
• You already define value objects with constructors and want input to conform to them.

When it is not the right tool

• You only need to validate a form and return error messages — a validation library may be a closer match.
• Your data is already typed objects and needs no conversion.
• You want an all-in-one framework; Valinor is deliberately just the mapping layer.

Getting oriented

The site itself is a redirect: visiting valinor-php.dev forwards to a latest/ path, which is where the current documentation lives. Start there for installation and the mapping API, since the exact method names and configuration options are version-specific and belong to the docs rather than to a summary.