Symfony Http Responder Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation

   composer require oskarstark/symfony-http-responder
   

   (Note: Since this is a Symfony package, ensure Laravel’s symfony/http-foundation is installed.)

2. First Use Case: JSON Response

   use OskarStark\SymfonyResponder\JsonResponder;
   
   public function show(User $user)
   {
       return (new JsonResponder())->respond([
           'data' => $user->toArray(),
       ]);
   }
   

3. First Use Case: View Rendering

   use OskarStark\SymfonyResponder\ViewResponder;
   
   public function index()
   {
       return (new ViewResponder('users.index'))->with([
           'users' => User::all(),
       ]);
   }
   

4. First Use Case: File Download

   use OskarStark\SymfonyResponder\FileResponder;
   
   public function download()
   {
       return (new FileResponder(storage_path('app/report.pdf')))
           ->setContentDisposition('attachment; filename="report.pdf"');
   }
   

5. Where to Look First

   • Documentation: Check the Symfony HttpFoundation docs for core concepts.
   • Source: Browse src/Responder for available responders.
   • Laravel Integration: Use app()->make() or dependency injection for responders.

Implementation Patterns

1. Dependency Injection (Recommended)

Register responders in AppServiceProvider:

public function register()
{
    $this->app->bind(JsonResponder::class, function () {
        return new JsonResponder();
    });
}

Then inject into controllers:

public function __construct(private JsonResponder $jsonResponder) {}

2. Chaining Methods for Clarity

return (new JsonResponder())
    ->setData(['status' => 'success'])
    ->setStatusCode(200)
    ->respond();

3. Middleware Integration

Use responders in middleware to standardize responses:

public function handle($request, Closure $next)
{
    $response = $next($request);
    if ($response instanceof JsonResponder) {
        $response->setHeader('X-Custom', 'Header');
    }
    return $response;
}

4. Dynamic Response Switching

public function handleRequest()
{
    if ($this->isApiRequest()) {
        return (new JsonResponder())->respond($data);
    }
    return (new ViewResponder('view.name'))->with($data);
}

5. Laravel-Specific Extensions

Extend responders to integrate with Laravel’s Response facade:

use Illuminate\Support\Facades\Response;

class LaravelJsonResponder extends JsonResponder
{
    public function respond($data)
    {
        return Response::json($data, $this->statusCode);
    }
}

6. Error Handling

Wrap responders in try-catch blocks:

try {
    return (new JsonResponder())->respond($this->service->fetchData());
} catch (\Exception $e) {
    return (new JsonResponder())
        ->setData(['error' => $e->getMessage()])
        ->setStatusCode(500)
        ->respond();
}

Gotchas and Tips

1. Symfony vs. Laravel Response Objects

• Gotcha: This package returns Symfony Response objects, not Laravel’s. To convert:

  use Illuminate\Support\Facades\Response;
  $symfonyResponse = (new JsonResponder())->respond($data);
  return Response::make($symfonyResponse->getContent(), $symfonyResponse->getStatusCode(), $symfonyResponse->headers->all());
  

• Tip: Use LaravelJsonResponder (as shown above) to avoid manual conversion.

2. Status Code Overrides

• Gotcha: Forgetting to set a status code defaults to 200. Always explicitly set it for non-success responses:

  (new JsonResponder())->setStatusCode(404)->respond(['error' => 'Not found']);
  

3. View Responder Quirks

• Gotcha: The ViewResponder uses Symfony’s Templating component, which may not auto-detect Laravel’s view paths. Specify the full path:

  (new ViewResponder('resources/views/users.index'))->with($data);
  

• Tip: Extend ViewResponder to resolve Laravel views:

  class LaravelViewResponder extends ViewResponder
  {
      public function __construct(string $view)
      {
          parent::__construct(view()->getPath().'/'.$view);
      }
  }
  

4. File Responder Caching

• Gotcha: Files are streamed directly. For large files, ensure proper memory handling:

  (new FileResponder($filePath))
      ->setCache([
          'public' => true,
          'max_age' => 3600,
          's_maxage' => 3600,
      ]);
  

• Tip: Use Laravel’s Storage facade to generate temporary URLs for private files.

5. JSON Encoding Issues

• Gotcha: Complex objects (e.g., DateTime, resources) may not serialize correctly. Use json_encode with JSON_UNESCAPED_UNICODE or cast to arrays:

  (new JsonResponder())->respond([
      'date' => $user->created_at->toIso8601String(),
  ]);
  

6. Debugging Headers

• Tip: Dump headers for debugging:

  $response = (new JsonResponder())->respond($data);
  dd($response->headers->all());
  

7. Extending for API Versions

• Tip: Create versioned responders:

  class V2JsonResponder extends JsonResponder
  {
      public function respond($data)
      {
          $data['api_version'] = '2.0';
          return parent::respond($data);
      }
  }
  

8. Performance Considerations

• Tip: Reuse responder instances (e.g., via DI container) to avoid reinitializing dependencies.
• Gotcha: Avoid instantiating responders inside loops; create them once per request.

9. Testing

• Tip: Mock responders in tests:

  $responder = $this->createMock(JsonResponder::class);
  $responder->method('respond')->willReturn(new SymfonyResponse());
  

• Gotcha: Ensure tests account for Symfony Response vs. Laravel Response differences.