Responder Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bugloos/responder-bundle
   

   Ensure your project meets the requirements (PHP 8.0+, Symfony 4.4+).

2. Bundle Registration: Add to config/bundles.php:

   Bugloos\ResponderBundle\BugloosResponderBundle::class => ['all' => true],
   

3. First Use Case: Replace default Symfony responses in controllers with standardized responders. Example:

   use Bugloos\ResponderBundle\Responder\JsonResponder;
   
   class ApiController extends AbstractController
   {
       public function show(User $user, JsonResponder $responder)
       {
           return $responder->respond([
               'data' => $user->toArray(),
               'meta' => ['status' => 'success']
           ]);
       }
   }
   

4. Key Files:

   • src/Responder/ for core responder classes.
   • config/packages/bugloos_responder.yaml for bundle configuration.

Implementation Patterns

Core Workflows

1. Controller Integration:

   • Inject responders as services (e.g., JsonResponder, HtmlResponder).
   • Use responders to standardize response formats (e.g., API JSON, HTML views).
   • Example:

     return $responder->respond($data, Response::HTTP_CREATED, ['Location' => '/users/1']);
     

2. Custom Response Formatting:

   • Extend base responders (e.g., JsonResponder) to add domain-specific logic:

     class ApiJsonResponder extends JsonResponder
     {
         protected function customizeResponse(array $data, int $status): array
         {
             return array_merge($data, ['timestamp' => now()->toIso8601String()]);
         }
     }
     

3. Error Handling:

   • Use responders for consistent error responses:

     try {
         $user = User::findOrFail($id);
     } catch (NotFoundHttpException $e) {
         return $responder->error('User not found', Response::HTTP_NOT_FOUND);
     }
     

4. View Integration:

   • For HTML responses, leverage HtmlResponder with Twig:

     return $htmlResponder->render('user/show', ['user' => $user]);
     

5. Middleware Integration:

   • Use responders in middleware to wrap responses globally (e.g., add API version headers).

Integration Tips

• Symfony Flex: Works seamlessly with Symfony’s autowiring.
• API Platform: Pair with api-platform/core for automatic responder integration.
• Testing: Mock responders in PHPUnit tests to isolate response logic.

Gotchas and Tips

Pitfalls

1. Configuration Overrides:

   • Bundle settings in bugloos_responder.yaml may conflict with custom responder logic. Always check:

     bugloos_responder:
         default_status: 200  # Overrides global default
     

2. Response Headers:

   • Responders may not handle custom headers by default. Add them explicitly:

     return $responder->respond($data, Response::HTTP_OK, ['X-Custom-Header' => 'value']);
     

3. Caching:

   • Avoid caching responses with dynamic data (e.g., timestamps) unless explicitly handled in responders.

4. Symfony 5.4+:

   • Some features may require Symfony 5.4+ (e.g., new HTTP client integrations). Check the upgrading guide.

Debugging

• Response Inspection: Use Symfony’s ResponseListener to log responses:

  $this->container->get('debug.stopwatch')->lap('responder');
  

• Common Issues:
  • 500 Errors: Ensure responders are properly injected (e.g., typo in service ID).
  • Empty Responses: Verify respond() is called with valid data.

Extension Points

1. Custom Responders:

   • Create responders for new formats (e.g., XmlResponder):

     class XmlResponder extends AbstractResponder
     {
         public function respond($data, int $status = 200, array $headers = []): Response
         {
             $xml = new \SimpleXMLElement('<response/>');
             // ... transform $data to XML
             return new Response($xml->asXML(), $status, $headers);
         }
     }
     

   • Register as a service:

     services:
         Bugloos\ResponderBundle\Responder\XmlResponder:
             tags: ['controller.service_arguments']
     

2. Event Listeners:

   • Hook into responder.response events to modify responses globally:

     public function onResponderResponse(ResponderEvent $event)
     {
         $event->setResponse($event->getResponse()->withHeader('X-Processed', 'true'));
     }
     

3. Configuration:

   • Override default responder classes in config/packages/bugloos_responder.yaml:

     bugloos_responder:
         responders:
             json: App\Responder\ApiJsonResponder