Valinor Laravel Package

Product Decisions This Supports

Build vs. Buy: Strongly-Typed Data Mapping

• Buy: Eliminates the need to build custom parsers/validators for JSON, HTTP requests, or nested data structures. Reduces technical debt by leveraging a battle-tested, dependency-free library with PHPStan/Psalm support for static analysis.
• Roadmap Alignment: Accelerates development for APIs, CLI tools, or internal services requiring type safety and validation without sacrificing flexibility. Ideal for teams adopting PHP 8+ and modern tooling (e.g., Symfony, Laravel, or standalone SAPI apps).

Feature Enablement

• API Development:
  • HTTP Request Mapping: Replace manual Request object parsing (e.g., $request->query->get()) with type-safe controller signatures using #[FromRoute], #[FromQuery], and #[FromBody]. Example: Validate pagination params (int<1,100> $limit) directly in method signatures.
  • Normalization: Standardize output formats (e.g., JSON, CSV) for consistency across microservices or third-party integrations.
• Data Pipelines:
  • Transform legacy arrays or JSON into immutable DTOs with runtime validation. Example: Convert a user’s raw API response into a User object with non-empty-string email validation.
• CLI/Internal Tools:
  • Validate CLI arguments or config files (e.g., YAML/TOML) with the same rigor as HTTP requests. Example: Enforce positive-int for --limit flags.

Use Cases

1. API Contracts:
   • Enforce openAPI/Swagger-like validation without external tools. Example: Reject null for required fields or validate DateTime ranges.
2. Legacy System Modernization:
   • Gradually introduce type safety to untyped arrays by wrapping them in mapped objects (e.g., User::fromArray($legacyData)).
3. Multi-Framework Compatibility:
   • Works with any PHP app (Laravel, Symfony, Slim, or standalone). No framework lock-in.
4. Performance-Critical Paths:
   • Blackfire-optimized for high-throughput systems (e.g., real-time data processing).

When to Consider This Package

Adopt If:

• Your team uses PHP 8.0+ and values static analysis (PHPStan/Psalm).
• You need runtime validation for:
  • HTTP APIs (route/query/body params).
  • Nested data structures (e.g., arrays of objects with constraints like list<City>).
  • CLI/config inputs (e.g., validating YAML/TOML files).
• You want to reduce boilerplate for:
  • Manual json_decode() + isset() checks.
  • Custom validation logic (e.g., regex, ranges).
• You’re building scalable services where data integrity is critical (e.g., payments, user auth).

Look Elsewhere If:

• You’re using PHP < 8.0 (limited support for modern types like non-empty-string).
• Your stack relies on framework-specific solutions (e.g., Symfony’s ParamConverter, Laravel’s Form Requests) and you don’t want abstraction overhead.
• You need database ORM features (use Doctrine or Eloquent instead).
• Your use case is simple (e.g., flat JSON with no validation). A basic json_decode() may suffice.
• You require active maintenance (project is MIT-licensed but community-driven; check GitHub activity for critical updates).

How to Pitch It (Stakeholders)

For Executives/Business Leaders

Problem:

"Our APIs and internal tools spend cycles manually parsing and validating data, leading to bugs in production (e.g., invalid user inputs, malformed payloads). This increases support costs and slows down feature delivery."

Solution:

"Valinor is a lightweight, dependency-free library that automates data mapping and validation using PHP’s native type system. It turns raw inputs (JSON, HTTP requests, CLI args) into type-safe objects with clear error messages—reducing bugs by 30–50% and cutting dev time by 20% on new endpoints. Used by teams at [Company X] to enforce API contracts without writing custom parsers."

ROI:

• Faster Development: No more writing repetitive validation logic.
• Fewer Bugs: Catches invalid data at runtime with human-readable errors.
• Future-Proof: Works with modern PHP tooling (PHPStan, Psalm) and scales with your tech stack.

Ask:

"Should we allocate 2 sprints to integrate Valinor for our API layer and CLI tools, targeting a 20% reduction in data-related bugs?"

For Engineers/Architects

Why Valinor?

"This is PHP’s answer to Rust’s serde or Python’s pydantic—but for HTTP requests, JSON, and nested data. Key benefits:"

1. Type Safety Without Compromises:

   • Validate non-empty-string, int<1,100>, list<City>, and more at runtime.
   • Works with PHPStan/Psalm for static analysis (catch errors early).

2. HTTP Request Superpowers:

   • Clean controller signatures:

     public function createUser(
         #[FromBody] UserDto $user, // Auto-validates JSON body
         #[FromQuery] int $page = 1 // Validates query params
     ) { ... }
     

   • No more manual $request->query->get() or $request->request->all().
   • Supports PSR-7 for framework-agnostic use.

3. Performance:

   • Blackfire-optimized for high-throughput systems.
   • Zero dependencies (unlike Symfony’s Validator or Laravel’s Form Requests).

4. Flexibility:

   • Works with any input: JSON, arrays, HTTP requests, CLI args.
   • Normalization: Convert objects back to JSON/CSV for APIs or exports.

Migration Path:

• Start with critical APIs (e.g., user auth, payments).
• Replace manual validation in controllers with #[FromRoute/Query/Body] attributes.
• Gradually adopt for internal tools (e.g., CLI config validation).

Alternatives Compared:

Proposal:

"Let’s pilot Valinor for our /users API and CLI migration tool. If it reduces validation bugs by 30% in 2 weeks, we’ll expand it to all new endpoints. The learning curve is low—similar to Symfony’s attributes but more powerful."