Valinor Laravel Package

Product Decisions This Supports

• Build vs. Buy: Buy – Eliminates the need to build custom input validation/mapping logic, reducing technical debt and accelerating development.
• Feature Roadmap:
  • API/Service Layer: Enables strongly-typed DTOs for HTTP requests/responses, improving maintainability and reducing runtime errors.
  • Data Migration: Simplifies transformation of legacy data (e.g., JSON/CSV) into typed domain objects.
  • Security: Mitigates risks of malformed input by validating early (e.g., API payloads, user uploads).
  • Static Analysis: Integrates with PHPStan/Psalm to catch type mismatches before runtime, improving developer productivity.
• Use Cases:
  • API Development: Map raw HTTP requests (JSON/XML) to typed domain objects with validation.
  • Data Pipelines: Transform unstructured data (e.g., CSV exports) into structured objects.
  • Legacy System Integration: Bridge gaps between old (weakly typed) and new (strongly typed) codebases.
  • CLI Tools: Validate and parse command-line arguments or config files into typed structures.

When to Consider This Package

• Adopt if:

  • Your team uses PHP 8.1+ and relies on strong typing (PHPStan/Psalm).
  • You frequently deal with external data sources (APIs, databases, files) that need validation/mapping.
  • You want to reduce runtime errors by shifting validation to compile-time/static analysis.
  • Your project uses Symfony, Mezzio, or a custom framework (or can integrate manually).
  • You prioritize performance (caching reduces overhead for repeated mappings).

• Look elsewhere if:

  • Your codebase is not strongly typed (e.g., relies on dynamic arrays/duck typing).
  • You need minimal dependencies (Valinor requires PHPStan/Psalm for full static analysis benefits).
  • Your use case is simple (e.g., trivial key-value transformations without validation).
  • You’re using Laravel’s built-in request validation (though Valinor can complement it for complex DTOs).
  • Your team lacks PHPStan/Psalm adoption (static analysis features are a major selling point).

How to Pitch It (Stakeholders)

For Executives:

*"Valinor is a dependency-free PHP library that turns messy, untrusted input (like API requests or CSV files) into guaranteed, strongly-typed objects—automatically. This:

• Reduces bugs by validating data early (e.g., catching malformed API payloads before they hit business logic).
• Saves dev time by eliminating manual mapping/validation code (no more isset() checks or try-catch blocks for every input).
• Improves security by rejecting invalid input upfront (e.g., SQL injection via malformed JSON).
• Works with our existing stack (Symfony/Mezzio) or can be integrated manually. It’s used by [X] companies and backed by JetBrains/Blackfire. Think of it as TypeScript for PHP data—but at runtime and compile-time."

ROI Ask: "Would you prioritize reducing API-related bugs or accelerating data pipeline development?"

For Engineers:

*"Valinor lets you map raw input to typed objects with zero boilerplate, while catching errors via PHPStan/Psalm (static analysis) or runtime validation. Key benefits:

• No more array_key_exists() hell: Define your DTOs with PHPDoc types (e.g., non-empty-string, list<City>), and Valinor handles the rest.
• Framework-agnostic but integrates easily with Symfony (bundle) or Mezzio (official package). For custom setups, it’s a 10-minute integration.
• Performance-optimized: Built-in caching avoids reprocessing the same data structures.
• Security: Pure functions mean no side effects from malicious input (e.g., no accidental file writes during mapping).

Example:

// Before: Manual validation + mapping
if (!isset($data['name']) || !is_string($data['name'])) throw new \InvalidArgumentException();
$country = new Country($data['name'], ...);

// After: One line with validation
$country = $mapper->map(Country::class, $data); // Throws on error

Use it for:

• API request/response DTOs.
• Data migrations (e.g., CSV → domain objects).
• CLI argument parsing.
• Legacy system integrations.

Tradeoffs:

• Requires PHP 8.1+ and PHPStan/Psalm for full static analysis (but runtime validation works standalone).
• Slight learning curve for advanced features (e.g., custom constructors, shaped arrays).

Next Steps:

1. Spike: Try mapping a complex API payload to a DTO in 30 mins.
2. Integrate: Add the Symfony bundle or Mezzio package if using those frameworks.
3. Enable static analysis: Add the PHPStan/Psalm extensions to catch type errors early."*