Valinor Laravel Package

Product Decisions This Supports

• Strongly-typed API contracts: Enables adoption of PHP 8.1+ features (e.g., readonly, non-empty-string, generics) for input validation in APIs, CLI tools, or microservices, reducing runtime errors.
• Decoupling from frameworks: Eliminates reliance on Laravel/Symfony validators (e.g., Illuminate/Validation, Symfony/Validator) for HTTP request mapping, simplifying dependency management.
• Normalization pipeline: Supports data transformation (e.g., JSON ↔ DTOs, CSV exports) without manual serialization logic, reducing boilerplate.
• HTTP-first design: Aligns with REST/gRPC roadmaps by providing type-safe request handling (route/query/body) with minimal framework coupling.
• Build vs. buy: Justifies in-house adoption over commercial tools (e.g., API Platform, OpenAPI generators) for projects needing fine-grained control over validation rules.
• Use cases:
  • API gateways: Validate and transform incoming requests into domain objects.
  • CLI tools: Parse user input (e.g., flags, JSON configs) into typed structures.
  • Event-driven systems: Deserialize messages (e.g., Kafka, RabbitMQ) into strongly-typed events.
  • Legacy migration: Gradually introduce typing to existing array-based codebases.

When to Consider This Package

• Adopt when:

  • Your team uses PHP 8.1+ and wants to leverage native typing (e.g., non-empty-string, generics, readonly).
  • You’re building APIs, microservices, or CLI tools where input validation is critical.
  • You need framework-agnostic solutions (avoids locking into Laravel/Symfony validators).
  • Your project requires reusable validation logic (e.g., shared DTOs across services).
  • You want to reduce boilerplate for JSON/HTTP request parsing (e.g., no manual json_decode() + isset() checks).

• Look elsewhere if:

  • You’re using PHP < 8.1 (limited support for modern types).
  • Your stack is heavily coupled to a framework (e.g., Symfony’s Serializer or Laravel’s FormRequest) and migration isn’t a priority.
  • You need database schema validation (consider Doctrine or Symfony Validator).
  • Your use case is simple (e.g., basic form handling with minimal validation).
  • You require active maintenance (package is MIT-licensed but community-driven; check release frequency).

How to Pitch It (Stakeholders)

For Executives:

"Valinor is a lightweight, dependency-free library that turns raw input (JSON, HTTP requests, etc.) into strongly-typed PHP objects—like a compiler for your data. This reduces bugs by catching invalid inputs early (e.g., missing fields, wrong types) and cuts development time by eliminating manual validation code. For example, instead of writing 50 lines of if/else checks for API requests, we’d use type hints and annotations to auto-validate inputs. It’s especially valuable for APIs, microservices, and CLI tools where data integrity is critical. The MIT license and zero dependencies make it easy to adopt without vendor lock-in."

ROI:

• Faster development: 30–50% less boilerplate for input parsing/validation.
• Fewer bugs: Runtime errors caught at compile-time (via PHPStan/Psalm).
• Scalable: Works across APIs, CLI, and event-driven systems.

For Engineering Teams:

*"Valinor solves two key pain points:

1. Manual validation is tedious: No more writing repetitive isset()/filter_var() checks for JSON/HTTP inputs.
2. Strong typing is hard to enforce: PHP’s dynamic nature makes it easy to pass wrong data types. Valinor uses PHP 8.1+ features (e.g., non-empty-string, generics) to enforce types at map-time, with clear error messages.

Key features:

• HTTP request mapping: Auto-parses route/query/body into typed objects (e.g., #[FromRoute] string $userId).
• Normalization: Convert objects back to JSON/arrays for APIs or storage.
• Framework-agnostic: Works with Laravel, Symfony, or raw PHP—no framework dependencies.
• PSR-7 support: Integrates with PSR-15 middleware or PSR-7 requests.

Example:

// Before: Manual validation
$user = [
    'name' => $_POST['name'] ?? '',
    'age'  => (int)($_POST['age'] ?? 0),
];
if (empty($user['name'])) throw new \InvalidArgumentException('Name required');

// After: Type-safe mapping
$user = (new MapperBuilder())
    ->mapper()
    ->map(User::class, Source::json($json));

Why now?

• If you’re using PHP 8.1+, this lets you write once, validate everywhere.
• Reduces tech debt by centralizing validation logic in DTOs (reusable across services).
• Works alongside existing tools (e.g., use with Laravel’s FormRequest for hybrid validation)."*

Migration Path:

1. Start with simple DTOs (e.g., API request/response objects).
2. Replace manual json_decode() + isset() checks with Valinor::map().
3. Gradually adopt HTTP attributes (#[FromRoute], #[FromQuery]) for controllers.
4. Use normalization for API responses or data exports.