Valinor Bundle Laravel Package

Product Decisions This Supports

• API Development Acceleration: Enables rapid development of RESTful APIs with type-safe request handling, reducing boilerplate for DTOs, validation, and request parsing.
• Consistent Data Contracts: Standardizes request/response validation across controllers, improving maintainability and reducing runtime errors.
• Developer Experience (DX): Eliminates repetitive manual mapping logic (e.g., Request->query->get() or json_decode()), allowing engineers to focus on business logic.
• Roadmap for API-First Products: Supports scaling APIs with complex validation rules (e.g., int<10,100>, non-empty-string) without custom middleware.
• Build vs. Buy: Replaces ad-hoc validation libraries or custom solutions, reducing technical debt while offering extensibility via configurators.
• Use Cases:
  • Public APIs requiring strict input validation.
  • Internal services where request consistency is critical.
  • Projects migrating from Symfony’s native attributes to a more feature-rich alternative.

When to Consider This Package

• Adopt When:

  • Building type-safe APIs in Laravel/Symfony with PHP 8+.
  • Needing advanced validation beyond Symfony’s built-in attributes (e.g., custom ranges, nullable types).
  • Prioritizing developer productivity with reduced boilerplate for request parsing.
  • Requiring consistent error messages for API consumers (e.g., 422 Unprocessable Entity with detailed validation failures).
  • Using Valinor’s ecosystem (e.g., existing type mapping in other parts of the app).

• Look Elsewhere If:

  • Your project uses Symfony’s native attributes (#[MapQueryString], etc.) and lacks need for Valinor’s extended features.
  • You’re not using PHP 8+ (attributes are required).
  • Your API is simple (e.g., no validation beyond basic types) and Symfony’s built-ins suffice.
  • You’re locked into Laravel’s native request handling (e.g., Request::all()) and prefer minimal dependencies.
  • Your team lacks familiarity with attribute-based programming or Valinor’s syntax.

How to Pitch It (Stakeholders)

For Executives: "This package supercharges our API development by automating request validation and parsing—cutting dev time by 30%+ while improving data integrity. It replaces error-prone manual mapping with type-safe, self-documenting code (e.g., #[FromQuery] positive-int $page). For example, a POST /users endpoint now validates input in one line instead of 20. It also future-proofs our APIs with granular error messages for clients, reducing support costs. Think of it as ‘Laravel’s request handling on steroids’—with zero trade-offs in performance."

For Engineers: *"Valinor’s HTTP mapping lets you define request shapes once (e.g., #[FromBody] UserCreateDto $data) and reuse them across controllers. Need to enforce snake_case keys or custom date formats? Done via configurators. Want to map all query params to a DTO at once? mapAll: true. It’s Symfony’s attributes, but with superpowers:

• Advanced types: int<5,100>, non-empty-string.
• Custom attributes: Reuse mapper configs across controllers.
• Clean errors: 422 responses with actionable validation messages. No more writing if (!$request->has('page'))—just declare your contract and let the package handle the rest. Pair this with our existing [X] service, and we’ll ship APIs faster with fewer bugs."*