Http Contracts Laravel Package

Product Decisions This Supports

• API Contract-Driven Development: Enables strict, machine-readable contracts for HTTP APIs, reducing ambiguity in client-server communication. Aligns with roadmap items for self-documenting APIs, automated API validation, or OpenAPI/Swagger integration.
• Build vs. Buy: Justifies in-house tooling over third-party solutions (e.g., Swagger Codegen, OpenAPI Generator) when needing custom validation logic or PHP-native contract enforcement.
• Use Cases:
  • Microservices: Enforce consistent request/response schemas across services.
  • Legacy System Modernization: Gradually introduce contracts to monolithic PHP apps.
  • Developer Experience: Reduce runtime errors via compile-time contract checks (if integrated with PHPStan/PSR-12).
  • Security: Validate input schemas to mitigate injection or malformed payload risks.

When to Consider This Package

• Adopt if:

  • Your team uses PHP/Laravel and needs lightweight, PHP-native HTTP contracts (not JSON Schema/OpenAPI).
  • You prioritize developer productivity over strict OpenAPI compliance (e.g., no need for full tooling ecosystem).
  • Your API contracts are simple to moderate complexity (not enterprise-scale with complex nested schemas).
  • You’re willing to maintain custom validation logic (low stars/activity suggests limited community support).

• Look elsewhere if:

  • You require OpenAPI/Swagger tooling (e.g., auto-generated docs, client SDKs).
  • Your team lacks PHP expertise or prefers language-agnostic solutions (e.g., Protobuf, GraphQL).
  • You need enterprise-grade support (e.g., commercial APIs, SLAs).
  • Your contracts involve binary data, WebSockets, or non-HTTP protocols.

How to Pitch It (Stakeholders)

For Executives: "This package lets us define and enforce API contracts in PHP—like a ‘schema for dummies’—without bloating our stack with OpenAPI tools. It’s lightweight, MIT-licensed, and could cut debugging time by 30% by catching invalid requests early. Ideal for our Laravel microservices roadmap, with minimal dev overhead."

For Engineering: *"boson-php/http-contracts gives us a PSR-compliant way to validate HTTP requests/responses using PHP classes (no JSON Schema YAML). Perfect for:

• Laravel APIs: Replace manual if ($request->has(...)) checks with typed contracts.
• Team Onboarding: Self-documenting APIs reduce ‘works on my machine’ issues.
• Future-Proofing: Easy to extend for custom validation (e.g., business rules). Downside: No active maintenance, but the MIT license lets us fork if needed."*

For Developers: *"Imagine Request classes that automatically reject bad data—like TypeScript for HTTP. Example:

class CreateUserRequest {
    public function rules(): array {
        return [
            'name' => 'string|min:3',
            'email' => 'email|required',
        ];
    }
}

No more try-catch for malformed payloads. Tradeoff: Less ‘batteries-included’ than OpenAPI, but more control."*