Valinor Bundle Laravel Package

Technical Evaluation

Architecture Fit

This package introduces attribute-based HTTP request mapping (route/query/body) with Valinor’s advanced type system, aligning well with modern Laravel/Symfony architectures. It replaces manual parsing (e.g., $request->query->get()) with declarative, type-safe argument injection, reducing boilerplate and improving maintainability. The integration with Symfony’s #[AsController] and #[Route] attributes ensures seamless adoption in API-heavy applications.

Key strengths:

• Strong typing: Supports PHP 8.1+ union types (non-empty-string, int<10,100>) and custom validation.
• Flexibility: Per-controller configurators (e.g., key case conversion, date formats) enable consistent API contracts.
• Error handling: Centralized 422 Unprocessable Entity responses with detailed validation messages.
• Extensibility: Custom MapRequestAttribute allows team-specific defaults (e.g., snake_case enforcement).

Trade-offs:

• Performance overhead: Runtime mapping adds minimal latency but may impact high-throughput endpoints (benchmark before production use).
• Learning curve: Requires familiarity with Valinor’s type system and attribute-based DI.
• Symfony overlap: Symfony’s native #[MapQueryString]/#[MapRequestPayload] (Symfony 6.3+) offers similar functionality but lacks Valinor’s advanced features (e.g., int<min,max>).

Integration Feasibility

High for Laravel/Symfony applications with:

• API-first architectures (REST/GraphQL) where request validation is critical.
• Teams using PHP 8.1+ (required for union types).
• Existing Valinor usage (reduces friction for type mapping).

Challenges:

• Legacy codebases: Manual request parsing (e.g., $_GET, $request->request->all()) would require refactoring.
• Middleware conflicts: If using custom request transformation middleware, conflicts may arise (e.g., JSON parsing before mapping).
• Testing impact: Unit tests relying on raw $request objects may need updates to mock mapped arguments.

Technical Risk

Key Questions for TPM

1. Adoption Scope:

   • Should this replace all manual request parsing, or only new endpoints?
   • How will existing middleware (e.g., auth, CORS) interact with mapped requests?

2. Type Safety:

   • Are union types (non-empty-string, int<min,max>) justified for all endpoints, or only critical ones?
   • Should the team standardize on a subset (e.g., only positive-int) to reduce complexity?

3. Error Handling:

   • How should HttpRequestMappingError be logged vs. surfaced to clients (e.g., API docs)?
   • Will custom error formats (e.g., JSON:API) be needed?

4. Performance:

   • Are there high-traffic endpoints where mapping overhead is unacceptable?
   • Could mapper builders be pre-configured globally to reduce runtime setup?

5. Tooling:

   • Should IDE support (e.g., PHPStorm hints for #[FromQuery]) be documented for the team?
   • Will custom attributes (e.g., MyAppMapRequest) be version-controlled or auto-generated?

Integration Approach

Stack Fit

Primary Use Case: Laravel/Symfony APIs with:

• Complex request validation (e.g., pagination, filters, DTOs).
• Consistent API contracts (e.g., snake_case vs. camelCase).
• High test coverage (type safety reduces runtime errors).

Secondary Use Case: Legacy systems migrating from manual parsing to structured validation.

Compatibility:

• Laravel: Works via Symfony bridge (tested on Laravel 9+).
• Symfony: Native support (Symfony 5.4+).
• Other Frameworks: Not applicable (Symfony/Laravel-specific).

Migration Path

Compatibility

• Symfony 6.3+: Native #[MapQueryString] may reduce need for Valinor in simple cases.
• Laravel 9+: No conflicts (Symfony bridge handles dependencies).
• Custom Middleware: Ensure middleware doesn’t modify $request before mapping (e.g., JSON parsing).
• Legacy Code: Use #[MapRequest(ignoreMissing: true)] to avoid breaking existing optional params.

Sequencing

1. Start with GET endpoints (query params are simpler than body mapping).
2. Prioritize endpoints with validation rules (e.g., pagination, filters).
3. Introduce custom attributes after pilot to avoid configuration sprawl.
4. Update tests to mock mapped arguments (e.g., #[FromRoute] string $id).
5. Monitor performance in staging before full rollout.

Operational Impact

Maintenance

• Pros:
  • Reduced boilerplate: No manual $request->query->get() calls.
  • Centralized validation: Rules defined in types (e.g., positive-int) vs. scattered in controllers.
  • Consistent errors: 422 responses with machine-readable messages.
• Cons:
  • Mapper configuration drift: Per-controller configurators may lead to inconsistent rules.
  • Debugging complexity: Stack traces for HttpRequestMappingError may require familiarity with Valinor.

Mitigations:

• Document team-wide mapper defaults (e.g., "All APIs use snake_case keys").
• Use custom attributes (e.g., #[ApiMapRequest]) to enforce consistency.

Support

• Developer Onboarding:
  • Training needed: 1–2 hours to understand attributes, union types, and configurators.
  • Documentation: Link to Valinor’s HTTP mapping guide and team-specific examples.
• Common Issues:
  • Type mismatches: E.g., sending "abc" for positive-int → clear error messages help.
  • Key case conflicts: E.g., camelCase vs. snake_case → enforce via RestrictKeysToSnakeCase.
• Support Tools:
  • IDE hints: PHPStorm recognizes #[FromQuery], #[FromBody] for autocomplete.
  • API docs: Swagger/OpenAPI can auto-generate schemas from mapped types.

Scaling

• Performance:
  • Benchmark: Compare mapped vs. manual parsing for 10k RPS (expect <5% overhead).
  • Optimizations:
    • Cache MapperBuilder instances for reused configurations.
    • Disable mapping for non-critical endpoints (e.g., health checks).
• Team Scaling:
  • Onboarding: New devs can contribute without deep request-parsing knowledge.
  • Consistency: Custom attributes reduce cognitive load for API contracts.
• Infrastructure:
  • No direct impact on DB/queue scaling, but 422 errors may increase logging volume.

Failure Modes