Http Foundation Laravel Package

## Getting Started

### Minimal Steps
1. **Installation**:
   ```bash
   composer require symfony/http-foundation:^8.1

Note: Laravel 10+ includes Symfony HTTP Foundation v8.1+ by default (via illuminate/http). For older Laravel versions, update manually or rely on Laravel’s built-in Request/Response wrappers.

2. First Use Case (Laravel 10+): Access the request object in a controller (now leveraging v8.1 features):

   use Symfony\Component\HttpFoundation\Request;
   
   public function handle(Request $request)
   {
       $method = $request->getMethod(); // 'GET', 'POST', etc.
       $query = $request->query->all(); // Query params
       $headers = $request->headers->get('X-Custom-Header', ''); // Case-insensitive access
   }
   

3. Key Classes to Explore (v8.1+):

   • Request: Enhanced header/cookie handling (see #64269 fixes).
   • Response: Improved send() behavior (now throws exceptions for invalid content).
   • UploadedFile: Stricter validation (e.g., getErrorMessage() now returns false for invalid files).
   • HeaderBag: Case-insensitive header access with stricter parsing.

4. Where to Look First:

   • Symfony 8.1 Upgrade Guide
   • Laravel’s Illuminate\Http\Request (extends Symfony’s Request).
   • Symfony 8.1 Changelog.

Implementation Patterns

Core Workflows

1. Request Handling (v8.1 Improvements)

• Header Access:

  // Case-insensitive, returns first value (throws if missing)
  $token = $request->headers->get('Authorization');
  // Safe fallback:
  $token = $request->headers->get('Authorization', '');
  

• Cookie Validation:

  $cookie = $request->cookies->get('user_token');
  if ($cookie === null) {
      // Cookie not set (not expired or invalid)
  }
  

• Method Override:

  if ($request->isMethod('POST') || $request->isMethod('PUT')) {
      // ...
  }
  

2. Response Construction

• JSON Responses (v8.1 Strictness):

  $response = new Response(json_encode(['data' => 'value']), 200, [
      'Content-Type' => 'application/json',
  ]);
  // Throws \InvalidArgumentException if content is not string/array
  

• File Downloads (UploadedFile v8.1):

  $file = $request->files->get('file');
  if ($file && $file->isValid()) {
      $response = new BinaryFileResponse($file->getPathname());
      $response->setContentDisposition(
          HeaderUtils::makeDisposition(
              HeaderUtils::DISPOSITION_ATTACHMENT,
              $file->getClientOriginalName()
          )
      );
      return $response;
  }
  

• Redirects with Headers:

  $redirect = new RedirectResponse('/dashboard');
  $redirect->headers->set('Cache-Control', 'no-store');
  return $redirect;
  

3. File Uploads (v8.1 Fixes)

• Error Handling:

  $file = $request->files->get('avatar');
  if (!$file->isValid()) {
      throw new \RuntimeException($file->getErrorMessage() ?: 'Invalid upload');
  }
  // v8.1: getErrorMessage() returns false for no error (not null)
  

• Temporary File Management:

  $file->moveTo($storagePath . '/' . $file->getClientOriginalName());
  // v8.1: UploadedFile now implements Stringable (can use in templates)
  

4. Middleware Integration

• Custom Middleware (v8.1 Type Safety):

  use Symfony\Component\HttpFoundation\Request;
  use Symfony\Component\HttpFoundation\Response;
  use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
  
  public function handle(Request $request, Closure $next): Response
  {
      if (!$request->headers->has('X-API-Key')) {
          throw new AccessDeniedHttpException('API key required');
      }
      return $next($request);
  }
  

• Laravel Middleware Registration:

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

5. Testing (v8.1 Compatibility)

• Mock Requests:

  $request = Request::create(
      '/test',
      'GET',
      [],
      [],
      [],
      ['HTTP_X_API_KEY' => 'secret']
  );
  $response = $this->app->handle($request);
  $this->assertEquals(200, $response->getStatusCode());
  

• File Upload Tests:

  $file = UploadedFile::create(
      __DIR__.'/test.pdf',
      'test.pdf',
      'application/pdf',
      null,
      true // Test mode (no actual upload)
  );
  $request = Request::create('/upload', 'POST', [], [], [], ['file' => $file]);
  

Integration Tips

Laravel-Specific Patterns

1. Leverage Symfony v8.1 in Laravel:

   • Access Symfony’s Request directly in service containers:

     public function __construct(private Request $request) {}
     

   • Use UploadedFile for validation (Laravel’s Illuminate\Http\UploadedFile extends Symfony’s version):

     $file = $request->file('avatar');
     $file->validate(); // Uses Symfony's validation under the hood
     

2. New v8.1 Features in Laravel:

   • HeaderUtils Improvements:

     use Symfony\Component\HttpFoundation\HeaderUtils;
     $disposition = HeaderUtils::makeDisposition(
         HeaderUtils::DISPOSITION_INLINE,
         'report.pdf'
     );
     

   • Response Factory:

     $response = Response::json(['success' => true]);
     // Internally uses Symfony's Response with proper headers
     

3. Standalone Usage (Non-Laravel):

   • Initialize with global overrides:

     $_SERVER['REQUEST_METHOD'] = 'POST';
     $request = Request::createFromGlobals();
     $response = new Response('OK');
     $response->send(); // Throws on invalid content (v8.1 strictness)
     

Breaking Changes (v8.1)

• UploadedFile::getErrorMessage(): Returns false for no error (previously null). Update checks:

  if ($file->getError() !== UploadedFile::UPLOAD_ERR_OK) {
      // Handle error
  }
  

• Response::send(): Now throws \LogicException if content is invalid (e.g., non-string JSON).
• Header Case Sensitivity: Headers are stored as lowercase but accessed case-insensitively. Use get() with fallback:

  $header = $request->headers->get('Content-Type', 'text/plain');
  

Gotchas and Tips

Pitfalls

1. Request Creation in Tests:

   • Request::create() does not populate $_SERVER/$_GET by default. Use Request::createFromGlobals() for real data or mock all globals:

     $_SERVER['REQUEST_METHOD'] = 'GET';
     $_GET['param'] = 'value';
     $request = Request::create('/test');
     

   • v8.1 Fix: Use RequestTestCase in Symfony’s test suite for helpers.

2. Session Handling:

   • Symfony’s session must be started explicitly (unlike Laravel):

     $session = $request->getSession();
     $session->start(); // Required in v8.1 for new sessions
     $session->set('key', 'value');
     

   • Laravel Note: Laravel’s session auto-starts, but custom middleware may need explicit calls.

3. File Upload Validation:

   • v8.1 Strictness: UploadedFile::isValid() now checks:
     • File exists.
     • File is readable.
     • No PHP errors during upload.
   • Gotcha: Temporary files are deleted after request unless moved:

     $file->moveTo($storagePath); // Critical in v8.1
     

4. Header Parsing Quirks:

   • **v8.