Weave Code
Valinor Laravel Package
cuyz/valinor
Valinor maps raw inputs (JSON/arrays) into validated, strongly typed PHP objects. Supports advanced PHPStan/Psalm types (shaped arrays, generics, ranges), produces precise human-readable errors, and can normalize data back to formats like JSON or CSV.
Dependency free PHP library that helps to map any input into a strongly-typed structure.
Frequently asked questions about Valinor
- How does Valinor compare to Laravel’s built-in validation (e.g., Form Requests) for API input handling?
- Valinor complements Laravel’s validation by enabling **compile-time guarantees** via PHPStan/Psalm annotations, reducing runtime errors. While Laravel’s validation focuses on runtime checks, Valinor maps raw input (e.g., JSON) directly into typed domain objects, ensuring data integrity from the start. Use both for layered validation: Valinor for DTOs and Laravel’s validation for form-level rules.
- Can Valinor replace Laravel’s Eloquent models for API responses? How does normalization work?
- Yes, Valinor can normalize Eloquent results into structured JSON/CSV while preserving shape. Use the `NormalizerBuilder` to convert domain objects back to arrays or JSON, which integrates seamlessly with Laravel’s `JsonResource`. This ensures consistent API responses without manual serialization logic, even for complex nested objects.
- What Laravel versions and PHP versions does Valinor support?
- Valinor supports **PHP 8.1+** and is framework-agnostic, but works flawlessly with Laravel 9+. It leverages modern PHP features like named arguments and enums, making it ideal for Laravel’s latest versions. Check the [documentation](https://valinor-php.dev) for exact compatibility details.
- How do I handle Valinor’s `MappingError` exceptions in Laravel’s exception handling?
- Catch `MappingError` in your Laravel middleware or controllers and translate it into `ValidationException` for consistency. For APIs, return structured error responses (e.g., JSON) with Valinor’s detailed error messages. Example: `throw new ValidationException($error->getErrors());` in a `render()` method.
- Does Valinor work with Laravel’s service container (IoC) for dependency injection?
- Valinor’s `MapperBuilder` and `NormalizerBuilder` can be registered as singletons in Laravel’s container for reuse. Cache instances during bootstrapping to avoid warmup delays. For DI, bind Valinor’s mappers to interfaces or use decorators to inject Laravel services (e.g., logging) into the mapping pipeline.
- How can I test Valinor mappings in Laravel’s test suite?
- Unit test mappings with PHPUnit by mocking `Source` objects (e.g., `Source::json()`) and asserting `MappingError` for invalid inputs. For integration tests, use Laravel’s HTTP tests to validate API routes that rely on Valinor-mapped DTOs. Enforce PHPStan/Psalm in CI to catch mapping issues early.
- What are the performance implications of Valinor in production?
- Valinor uses caching (e.g., `FileWatchingCache`) to optimize repeated mappings. Pre-warm the cache during Laravel’s bootstrapping to avoid delays. For large-scale mappings (e.g., bulk imports), monitor memory usage—Valinor’s pure-function design minimizes overhead, but complex nested objects may require optimization.
- Can Valinor handle CLI input (e.g., Artisan commands) or is it API-focused?
- Valinor is input-agnostic and works with CLI input via `Source::array()` or `Source::json()`. Use it in Artisan commands to validate and map command arguments into typed objects, ensuring consistency with your domain layer. Example: `Source::fromGlobals()` for parsing `$_SERVER` or `$_GET` in CLI contexts.
- Are there alternatives to Valinor for typed mapping in Laravel?
- Alternatives include **JMS Serializer**, **Symfony’s Serializer**, or **Spatie’s Laravel Data**, but Valinor stands out for its **strict validation**, PHPStan/Psalm integration, and normalization features. Unlike JMS, Valinor enforces type safety at construction time, reducing runtime errors. For Laravel-specific needs, Valinor’s `HttpRequest` mapper is more lightweight than full-stack serializers.
- How do I integrate Valinor with Laravel’s Form Request validation?
- Use Valinor in `FormRequest::rules()` to validate raw input before mapping. For example, validate a JSON field with `json:required|string` in Laravel’s rules, then map the validated data into a DTO using Valinor. This combines Laravel’s validation rules with Valinor’s typed object construction for a robust pipeline.
Weaver
How can I help you explore Laravel packages today?