What PHP Use Cases Is Valinor Designed For?

Updated

Valinor is a PHP library that maps any input into a strongly-typed value object structure. It fits best when you receive loosely-typed data (JSON payloads, request bodies, arrays, configuration) and want it to become typed PHP objects instead of staying as arrays you validate by hand. The core use cases are API input mapping, domain-layer value objects, and any place where you need input validation plus type conversion in one step.

Turning API requests and JSON into typed objects

The most direct use case is taking raw input from an HTTP request or a decoded JSON body and constructing typed objects from it.

A typical flow looks like this:

  1. Input: you have decoded JSON, e.g. {"id": 42, "name": "Ada", "active": true}.
  2. Action: you hand that array to Valinor and tell it the target class — a value object with typed properties such as int $id, string $name, bool $active.
  3. Expected result: you get back an instance of that class with correctly typed properties, or a clear error if the input doesn't match.

This replaces the common pattern of manually reading array keys, casting values, and checking types one by one. If your controllers currently do $data['id'] and cast it, Valinor moves that work into a single mapping step.

When this is worth it

  • Your endpoints accept structured payloads that map to known classes.
  • You want type errors surfaced at the boundary, not deep inside business logic.
  • You have several endpoints doing similar manual array-to-object conversion.

When it may be overkill

  • The input is a single scalar or a trivial two-field array.
  • You have no target class and genuinely want to keep working with arrays.

Using value objects in the domain layer instead of loose arrays

Valinor's description emphasizes a strongly-typed value object structure. That points at a second use case: keeping arrays out of your domain layer.

Instead of passing array $user through services and repositories, you define a value object and map incoming data into it once. Downstream code then depends on typed properties and methods rather than on array keys that can be misspelled or missing.

This matters when:

  • The same data shape is passed across multiple layers.
  • You want static analysis and IDE completion to work on the data.
  • You want a single place where the shape is defined and enforced.

Where input validation and type conversion are needed together

Valinor's role sits at the intersection of two jobs that are often done separately: checking that input is valid, and converting it into the type you actually want.

Because mapping and validation happen in the same step, you avoid the split where one library validates an array and separate code then casts it. If a value can't be converted to the declared type, the mapping fails rather than producing a silently wrong object.

A concrete scenario: an API accepts a status field as a string, but your domain wants an enum. Rather than validating the string and then converting it in a second pass, you declare the target type and let the mapping handle both.

Projects where Valinor is a good fit

Valinor is aimed at PHP projects that care about type safety. It tends to make sense when:

  • You use typed properties and value objects as a normal part of your design.
  • You have clear boundaries where external data enters the system (HTTP, queues, config, third-party responses).
  • You want mapping logic to be declarative — describing the target structure — rather than a sequence of manual casts.
  • You already rely on static analysis and want runtime data to match the types your code assumes.

It is less compelling for small scripts, prototypes, or codebases that intentionally work with arrays throughout.

What to check before adopting it

The library's own description is the reliable starting point: it maps any input into a strongly-typed value object structure. To decide whether it fits your project, look at:

  • Your entry points: how many places convert external data into objects today?
  • Your target classes: do you already have value objects, or would you need to introduce them?
  • Your error handling: do you want mapping failures to be explicit and centralized?

If most of your data already arrives as typed objects, or if your input is unstructured and unpredictable, the benefit is smaller. If you repeatedly convert arrays into typed objects at the edges of your application, that is exactly the case Valinor is designed for.