Weave Code
Valinor Laravel Package
cuyz/valinor
Valinor maps raw input (JSON/arrays) into fully typed PHP objects, validating along the way with clear, human-readable errors. Supports advanced types (PHPStan/Psalm), shaped arrays, generics, ranges, and can normalize objects back to JSON/CSV while preserving structure.
Valinor maps raw inputs (JSON, arrays, etc.) into strongly typed PHP objects, constructing and validating them so your domain stays in a guaranteed valid state. When data is invalid, it reports precise, human-readable errors, making failures easy to debug and handle.
It also includes a normalization layer to transform objects back into structured formats (JSON, CSV…) while preserving shape.
- Typed mapping to constructors and readonly properties
- Rich validation with detailed mapping errors
- Supports advanced types (shaped arrays, generics, ranges via PHPStan/Psalm)
- Works with multiple sources (e.g., JSON and arrays)
- Normalization for exporting structured data
Frequently asked questions about Valinor
- How does Valinor compare to Laravel’s built-in Form Request validation for API input?
- Valinor complements Laravel’s Form Requests by enabling compile-time validation via PHPStan/Psalm, reducing runtime errors. While Form Requests handle HTTP-specific rules (e.g., required fields), Valinor excels at mapping raw JSON/arrays into domain objects (e.g., DTOs) with strict type enforcement. Use Form Requests for HTTP validation and Valinor for domain-layer mapping.
- Can Valinor replace Laravel’s Validator facade entirely for API request validation?
- No, Valinor is not a direct replacement for Laravel’s Validator. It focuses on mapping and validating untrusted input into strongly-typed objects, while Validator handles HTTP-specific rules (e.g., sanitization, presence checks). Combine both: use Validator for request-level rules and Valinor for domain object construction.
- What Laravel versions and PHP versions does Valinor support?
- Valinor supports Laravel 10+ and requires PHP 8.1+. It has no Laravel-specific dependencies, so it works with any Laravel version that meets these requirements. Always check the [latest documentation](https://valinor-php.dev) for minor version quirks.
- How do I integrate Valinor with Laravel’s service container for caching?
- Register the `MapperBuilder` and `NormalizerBuilder` as Laravel services in `AppServiceProvider::boot()`. Use the `FileSystemCache` adapter (default) or integrate Redis/Memcached via custom adapters. Pre-warm the cache during deployment with an Artisan command to avoid latency spikes.
- Does Valinor work with Eloquent models directly, or should I use DTOs?
- Valinor works best with DTOs (plain PHP objects) to avoid coupling with Eloquent’s magic methods (e.g., `__get`, `__set`). For Eloquent models, map to DTOs first, then hydrate the model separately. This keeps validation and mapping decoupled from ORM concerns.
- How do I handle Valinor’s MappingError in a Laravel API response?
- Catch `MappingError` and convert it to Laravel’s `HttpResponse` with a JSON error format. Wrap it in a custom exception class (e.g., `ValidationException`) to standardize API error responses. Example: `throw new HttpResponse(json_encode(['error' => $error->getMessage()]), 422);`.
- What are the performance implications of Valinor in high-traffic APIs?
- Valinor introduces minimal overhead when caching is enabled. For high-throughput APIs, pre-warm the cache during deployment and use Redis/Memcached for distributed caching. Benchmark with your expected payload size—complex nested objects may require optimization.
- How do I configure PHPStan/Psalm to work with Valinor’s advanced types?
- Install the [Valinor extension](https://github.com/CuyZ/Valinor/tree/master/ext/phpstan) for PHPStan or [Psalm plugin](https://github.com/CuyZ/Valinor/tree/master/ext/psalm). Configure your static analysis tool to include Valinor’s rules, then test in CI. Conflicts may arise with Laravel’s default configs—adjust `level` or `disallowedTypes` as needed.
- Can Valinor handle malformed JSON or nested generics in Laravel APIs?
- Yes, Valinor validates and rejects malformed input with clear error messages. For nested generics (e.g., `list<list<string>>`), ensure your PHPStan/Psalm config supports recursive types. Test edge cases in CI with fuzzed JSON payloads to catch runtime issues early.
- Are there alternatives to Valinor for Laravel that offer similar functionality?
- Alternatives include **JMS Serializer** (feature-rich but heavier) and **Spatie’s Laravel Data** (Laravel-specific but less flexible). Valinor stands out for its dependency-free core, advanced type support (shaped arrays, generics), and normalization capabilities. Choose Valinor if you prioritize type safety and framework agnosticism.
Weaver
How can I help you explore Laravel packages today?