Http Contracts Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require boson-php/http-contracts
   

   No additional configuration is required—this is a pure PHP package with no Laravel-specific dependencies.

2. First Use Case: HTTP Request/Response Contracts Use the package to define strict contracts for HTTP interactions (e.g., API requests/responses). Example:

   use Boson\Http\Contracts\RequestContract;
   use Boson\Http\Contracts\ResponseContract;
   
   // Define a contract for a user creation request
   $requestContract = new RequestContract(
       path: '/api/users',
       method: 'POST',
       requiredHeaders: ['Content-Type' => 'application/json'],
       requiredBody: ['name' => 'string', 'email' => 'string']
   );
   
   // Validate a request against the contract
   $isValid = $requestContract->validate($request);
   

3. Where to Look First

   • Contracts: Browse src/Contracts/ for RequestContract, ResponseContract, and MiddlewareContract.
   • Validation: Focus on src/Validation/ for rules and utilities.
   • Examples: Check tests/ for usage patterns (if available).

Implementation Patterns

1. Request/Response Validation

• Workflow:
  1. Define contracts for incoming requests and expected responses.
  2. Validate requests early (e.g., in middleware or controllers).
  3. Enforce response contracts in API layers (e.g., after service logic).
• Example:

  // Middleware to validate incoming requests
  public function handle($request, Closure $next)
  {
      $contract = new RequestContract(...);
      if (!$contract->validate($request)) {
          abort(400, 'Invalid request format');
      }
      return $next($request);
  }
  

2. Middleware Integration

• Use contracts to standardize middleware behavior. Example:

  use Boson\Http\Contracts\MiddlewareContract;
  
  class ValidateApiKey implements MiddlewareContract
  {
      public function handle($request, Closure $next)
      {
          $contract = new RequestContract(
              requiredHeaders: ['X-API-KEY' => 'string']
          );
          if (!$contract->validate($request)) {
              abort(403);
          }
          return $next($request);
      }
  }
  

• Register middleware in app/Http/Kernel.php:

  protected $middleware = [
      \App\Http\Middleware\ValidateApiKey::class,
  ];
  

3. API Response Standardization

• Enforce consistent response formats across controllers:

  use Boson\Http\Contracts\ResponseContract;
  
  public function store(Request $request)
  {
      $responseContract = new ResponseContract(
          statusCode: 201,
          requiredBody: ['id' => 'integer', 'name' => 'string']
      );
      $data = User::create($request->validated());
      return response()->json($data)->assert($responseContract);
  }
  

4. Testing Contracts

• Write tests to validate contracts against mock requests/responses:

  public function test_request_validation()
  {
      $contract = new RequestContract(...);
      $request = new Request([], [], [], [], [], ['HTTP_X_API_KEY' => 'valid']);
      $this->assertTrue($contract->validate($request));
  }
  

Gotchas and Tips

Pitfalls

1. Overhead for Simple APIs

   • Avoid using contracts for trivial endpoints (e.g., health checks). The package adds validation layers that may not be worth the complexity.

2. Lack of Laravel-Specific Features

   • No built-in integration with Laravel’s FormRequest or ApiResource. You’ll need to manually bridge contracts with Laravel’s validation (e.g., using Validator::make()).

3. No Built-in Error Messages

   • Customize error responses manually:

     if (!$contract->validate($request)) {
         abort(400, $contract->getErrors());
     }
     

4. Subtree Split Dependency

   • Since this is a subtree split of boson-php/boson, ensure compatibility with the parent package if used together. Check for breaking changes in the parent repo.

Debugging Tips

• Validation Errors: Use $contract->getErrors() to debug failed validations.
• Contract Mismatches: Log contracts before validation to verify definitions:

  \Log::debug('Request contract:', $contract->toArray());
  

Extension Points

1. Custom Validators Extend Boson\Http\Validation\Validator to add domain-specific rules:

   class CustomValidator extends Validator
   {
       protected function validateEmailFormat($value)
       {
           return filter_var($value, FILTER_VALIDATE_EMAIL) !== false;
       }
   }
   

2. Response Assertions Add assertions to ResponseContract for Laravel’s JsonResponse:

   $response = response()->json($data);
   $response->assert($contract); // Hypothetical; implement custom logic.
   

3. Middleware Chaining Chain multiple contracts in middleware for layered validation:

   $contracts = [
       new RequestContract(...),
       new RequestContract(...),
   ];
   foreach ($contracts as $contract) {
       if (!$contract->validate($request)) {
           abort(400);
       }
   }
   

Config Quirks

• No Configuration File: All settings are code-based. Define contracts programmatically in classes or closures.
• Immutable Contracts: Contracts are likely immutable. Clone or rebuild them for dynamic use cases.