Http Server Request Laravel Package

Getting Started

1. Install via Composer

   composer require httpsoft/http-server-request
   

2. Create a ServerRequest from superglobals (most common use case)

   use HttpSoft\ServerRequest\ServerRequestFactory;
   
   $request = (new ServerRequestFactory())->createServerRequestFromGlobals();
   

3. Use it in middleware
   Since it’s PSR-7 compliant, plug it directly into any PSR-15/PSR-15-compatible middleware stack (e.g., with Nyholm/psr7, Relay, or custom dispatcher):

   $request = (new ServerRequestFactory())->createServerRequestFromGlobals();
   $response = $middleware($request, $response);
   

💡 First-tip: Start with ServerRequestFactory::createServerRequestFromGlobals() — it handles all the superglobal parsing (including $_COOKIE, $_FILES, $_SERVER) with PSR-7 normalization.

Implementation Patterns

📦 Middleware Integration

Use the request as the standard interface for handling requests in middleware:

$app = function ($request) {
    $method = $request->getMethod();
    $path   = $request->getUri()->getPath();
    return new JsonResponse(['path' => $path, 'method' => $method]);
};

🔁 Custom Request Construction

Build requests programmatically (e.g., for testing or CLI-initiated HTTP flows):

$request = (new ServerRequestFactory())->createServerRequest(
    'POST',
    '/api/upload',
    [
        'Content-Type' => 'multipart/form-data; boundary=----WebKit',
        'Authorization' => 'Bearer xyz'
    ],
    $_COOKIE,
    $_GET,
    $_POST,
    $_FILES
);

📁 File Upload Handling

Access uploaded files with normalized PSR-7 structures:

$uploadedFiles = $request->getUploadedFiles();
$file = $uploadedFiles['avatar'] ?? null;
if ($file instanceof UploadedFileInterface && $file->getError() === UPLOAD_ERR_OK) {
    $file->moveTo('/var/www/uploads/' . $file->getClientFilename());
}

🧩 Parse JSON Body Automatically

Since the package supports body parsing:

if ($request->hasHeader('Content-Type') && strpos($request->getHeaderLine('Content-Type'), 'application/json') !== false) {
    $parsedBody = $request->getParsedBody(); // e.g., ['name' => 'Jane', 'age' => 30]
}

💡 Pattern tip: Combine with httpsoft/psr7 for full PSR-7/18 compatibility in non-framework apps.

Gotchas and Tips

🚫 Super/global Parsing Quirks

• $_COOKIE is parsed only if setCookieParse() isn’t overridden — default behavior follows PHP’s mb_parse_str()-style rules, but httpsoft/http-server-request parses cookies more robustly (e.g., handles nested arrays). Double-check complex cookie structures.
• $_FILES structure must match PHP’s array format — if mocking in tests, use this format:

  $_FILES = [
      'avatar' => [
          'name' => 'me.jpg',
          'type' => 'image/jpeg',
          'tmp_file' => '/tmp/php123',
          'error' => 0,
          'size' => 12345,
      ]
  ];
  

🛠 Debugging & Testing

• Use __toString() on requests to debug headers/body (debug-only — not for prod):

  error_log((string) $request);
  

• For unit tests, prefer manual construction over createServerRequestFromGlobals() to avoid side effects.

🔧 Extension Points

• You can subclass ServerRequestFactory to override parsing behavior (e.g., custom body parsers or header normalization).
• Support for PSR-17 (factories) is partial — prefer this package’s own factory, as it handles more edge cases.

⚠️ Potential Pitfall

• Parsed body is immutable: Calling withParsedBody() returns a new instance — always reassign:

  // ❌ Wrong: ignored
  $request->withParsedBody(['foo' => 'bar']);
  
  // ✅ Correct
  $request = $request->withParsedBody(['foo' => 'bar']);
  

💡 Pro tip: For apps not using a framework, combine this with httpsoft/psr17-factory to satisfy full PSR-17/18 expectations across the stack.