Api Problem Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require phpro/api-problem-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   Phpro\ApiProblemBundle\PhproApiProblemBundle::class => ['all' => true],
   

2. First Use Case Throw a problem in a controller:

   use Phpro\ApiProblemBundle\Exception\ProblemException;
   
   public function show(User $user)
   {
       if (!$user->isActive()) {
           throw new ProblemException('User is inactive', 403, [
               'type' => 'https://example.com/probs/inactive-user',
               'status' => '403',
               'title' => 'Inactive User',
               'detail' => 'The requested user is inactive',
           ]);
       }
       return $user;
   }
   

3. Where to Look First

   • ProblemException: Core class for throwing RFC7807-compliant errors.
   • ProblemFactory: Customize default problem structures.
   • ProblemResponseListener: Built-in Symfony event listener (adapt for Laravel via middleware).

Implementation Patterns

Common Workflows

1. Validation Errors Use ProblemException with validation_errors type:

   throw new ProblemException('Validation failed', 422, [
       'type' => 'https://example.com/probs/validation-error',
       'errors' => ['email' => ['The email field is required.']],
   ]);
   

2. API Gateway Integration Catch exceptions globally and convert to problems:

   // Laravel middleware (app/Http/Middleware/ConvertExceptions.php)
   public function handle($request, Closure $next)
   {
       try {
           return $next($request);
       } catch (ProblemException $e) {
           return response()->json($e->getProblem(), $e->getStatusCode());
       } catch (\Exception $e) {
           return response()->json(
               Problem::create($e->getMessage())
                   ->setStatus($e->getCode() ?: 500)
                   ->setType('https://example.com/probs/unexpected-error')
           );
       }
   }
   

3. Custom Problem Types Extend ProblemFactory for domain-specific problems:

   // config/api_problem.php
   'factories' => [
       'authentication_error' => [
           'class' => \App\Problem\AuthProblemFactory::class,
           'status' => 401,
           'type' => 'https://example.com/probs/auth-error',
       ],
   ],
   

4. Linking Problems Add links to problems for API documentation or remediation:

   throw new ProblemException('Rate limit exceeded', 429, [
       'links' => [
           ['href' => '/docs/rate-limits', 'rel' => 'documentation'],
           ['href' => '/auth/refresh', 'rel' => 'retry-after'],
       ],
   ]);
   

Integration Tips

• Laravel Validation: Use ProblemException in HandleInvalidUserInput:

  public function invalid($request, $validator, $customMessages)
  {
      throw new ProblemException('Validation failed', 422, [
          'errors' => $validator->errors()->toArray(),
      ]);
  }
  

• API Documentation: Reference problem types in OpenAPI/Swagger:

  components:
    schemas:
      Problem:
        $ref: 'https://tools.ietf.org/html/rfc7807'
  

Gotchas and Tips

Pitfalls

1. Status Code Overrides

   • ProblemException defaults to 500 if no status is provided. Always specify:

     // ❌ Avoid
     throw new ProblemException('Error');
     
     // ✅ Correct
     throw new ProblemException('Error', 404);
     

2. Symfony-Specific Listeners

   • The bundle includes a ProblemResponseListener for Symfony. In Laravel, manually handle exceptions (see Implementation Patterns).

3. Nested Problems

   • Avoid deeply nested errors or details arrays. Keep payloads flat for readability:

     // ❌ Too nested
     { "errors": { "user": { "email": ["Invalid"] } } }
     
     // ✅ Flat
     { "errors": { "email": ["Invalid"] } }
     

4. Type URIs

   • Use absolute URIs (e.g., https://example.com/probs/...) for type fields to avoid collisions. Relative paths may break if APIs are versioned.

Debugging

• Missing Headers: Ensure Content-Type: application/problem+json is set in responses. Laravel’s response()->json() handles this automatically.
• Custom Factories: Verify factory classes are autoloaded and registered in config/api_problem.php.
• Logging: Use Problem::create()->withDebug() to include stack traces in development:

  Problem::create('Oops')
      ->setStatus(500)
      ->withDebug()
      ->throw();
  

Extension Points

1. Custom Problem Classes Extend Problem for domain-specific logic:

   class PaymentProblem extends Problem
   {
       public function setTransactionId(string $id): self
       {
           $this->set('transaction_id', $id);
           return $this;
       }
   }
   

2. Problem Transformers Convert problems to other formats (e.g., XML) via events:

   // Listen to `api_problem.response` (Symfony) or adapt for Laravel
   $problem->addExtension('custom_field', 'value');
   

3. Problem Middleware Add metadata to problems globally:

   // Laravel middleware
   public function handle($request, Closure $next)
   {
       $response = $next($request);
       if ($response->exception instanceof ProblemException) {
           $problem = $response->exception->getProblem();
           $problem->set('request_id', $request->header('X-Request-ID'));
           $response->setContent(json_encode($problem));
       }
       return $response;
   }
   

4. Testing Mock problems in tests:

   $problem = Problem::create('Test')
       ->setStatus(400)
       ->setType('https://example.com/probs/test');
   
   $this->expectException(ProblemException::class);
   $this->expectExceptionMessage($problem->getDetail());