Valinor Laravel Package

Product Decisions This Supports

• Boundary strategy: where validation lives. Valinor makes a concrete architectural bet viable — validate once at the edge (HTTP payload, webhook, queue message, CSV import, third-party API response) and hand the rest of the app objects that cannot be in an invalid state. This directly informs the roadmap question "do we keep re-validating inside services, or do we hydrate typed DTOs once and trust them?"
• Build vs. buy for hydration/mapping. The realistic alternatives are: hand-written fromArray() factories per DTO (cheap to start, expensive at scale, inconsistent error messages), symfony/serializer + symfony/validator (powerful, framework-coupled, two stacks to configure), or a bespoke mapping layer (pure cost, no differentiation). Valinor is a single MIT, zero-dependency Composer package — a small build-vs-buy line item with a clear "buy" answer for teams not already deep in Symfony Serializer.
• API contract governance and error UX. Because failures surface as structured, human-readable mapping errors with the offending path, this feeds decisions about client-facing validation responses ("field X is invalid") versus generic 422s — a real product-experience decision, not just an engineering one.
• Upstream data quality tolerance. The casting configurators (MapAsInt, MapAsBool(true: ['on','yes']), MapExplodedStringToList, MapFromJson, MapFromKey, MapWithPrefix) let a product absorb messy partner data — booleans sent as "on", lists flattened into comma-separated strings, zipCode vs postalCode naming — at the boundary, instead of scattering defensive casts through the domain. That's a roadmap lever: "we can onboard partner X without a data-cleanup project."
• Outbound contract shaping and data exposure. The normalizer side (NormalizeKeyTo, NormalizeToSingleValue, IgnoreOnNormalization) supports keeping snake_case public APIs while the PHP codebase stays camelCase, and makes "never serialize this field" a declarative, reviewable attribute rather than a unset() someone forgets. This is a security/PR-review decision as much as a formatting one.
• Type-system investment. Support for PHPStan/Psalm types — shaped arrays, generics, integer ranges, non-empty-string — means domain invariants declared in docblocks get runtime enforcement. This strengthens the case for investing in static analysis in CI, since the same annotations pay off twice.
• Use cases worth prototyping: inbound webhook/partner-payload ingestion, config file parsing into typed settings objects, import pipelines (CSV/JSON), and read-model/DTO assembly from external APIs.

When to Consider This Package

Consider it when:

• You're on PHP 8.x (Laravel included) and routinely turn untrusted or inconsistent external arrays/JSON into domain objects.
• You want strict typed objects without adopting Symfony Serializer + Validator or writing per-DTO factories.
• Precise, path-aware error messages are a product requirement (forms, public APIs, import error reports).
• Dependency footprint matters — zero runtime dependencies simplifies security review and upgrade risk.
• Your team already uses PHPStan/Psalm and wants docblock types enforced at runtime, not just in CI.
• You need symmetry: map in (validate/hydrate) and normalize out (JSON/array/CSV) from the same class definitions.

Look elsewhere when:

• You already have a deep Symfony Serializer/Validator investment and the migration cost exceeds the gain.
• Requirements are simple enough for Laravel's native validation + FormRequests; adding a mapper would be over-engineering.
• You need OpenAPI/JSON:API/GraphQL codegen or spec-first contract generation — Valinor maps to your classes, it doesn't generate contracts.
• ORM entity hydration/identity-map behaviour is what you actually need (Doctrine-style proxies, lazy loading); this is a boundary mapper, not an ORM.
• You need vendor SLAs, commercial support, or an LTS policy — this is a single-maintainer OSS project.
• Very hot code paths where reflection-based mapping cost must be proven, not assumed — benchmark with cache warmup before committing.

Diligence flags: public dependent count is effectively zero/unreliable as an adoption signal; weigh the ~1.5k stars, published docs site, active release cadence (2.6.0 with a substantial feature set), and the Stryker mutation-testing badge instead. Require a short internal spike plus a documented fallback path before making it load-bearing.

How to Pitch It (Stakeholders)

For executives: Valinor is a free, MIT-licensed PHP library that converts raw input — API responses, webhooks, CSV, JSON, config files — into strongly-typed objects, rejecting anything malformed with clear, actionable error messages. It replaces the repetitive, per-project "glue code" we currently hand-write to validate and populate objects, which is where a large share of data-quality bugs originate: bad payloads pass silently, then surface as null-pointer crashes or corrupt records downstream. Adopting it moves failure to the boundary, where it's cheap, visible, and testable. The commercial case is modest but real: lower maintenance cost on every integration we build, faster onboarding of messy partner data, and a smaller, better-audited dependency surface (zero runtime dependencies). Risk is contained — it's a single package we can adopt incrementally behind our own interfaces and remove if needed.

For engineering: This is a mapper and normalizer, not a framework. One MapperBuilder maps source data into constructor-promoted, readonly DTOs and validates it against native PHP types plus PHPStan/Psalm types (generics, shaped arrays, integer ranges, non-empty-string). Failures throw a MappingError you can traverse for field paths — ideal for API error responses and import reports. The 2.6.0 configurators cover the boring-but-expensive cases: scalar casting for stringly-typed inputs, key remapping for inconsistent upstreams, JSON/CSV-string sub-field decoding, and per-property attributes to keep strictness global while relaxing locally. The normalizer gives us the reverse direction with key renaming and IgnoreOnNormalization for sensitive fields. Recommended path: pilot on one inbound integration, wrap the mapper behind our own port interface so the dependency stays swappable, add contract tests against real payload fixtures, benchmark with cache warmup before it lands on a hot path, and confirm the maintainer/bus-factor story before it becomes load-bearing.