Http Laravel Package

Getting Started

Start by installing slim/http via Composer:

composer require slim/http

The package provides PSR-7 decorator factories (DecoratedResponseFactory, DecoratedServerRequestFactory, DecoratedUriFactory) — meaning it wraps an existing PSR-7 implementation (e.g., Nyholm/psr7, Laminas Diactoros). First, choose a PSR-7 implementation:

composer require nyholm/psr7
# or
composer require laminas/laminas-diactoros

Then, instantiate the decorated factory with the underlying factories:

use Nyholm\Psr7\Factory\Psr17Factory;
use Slim\Http\Factory\DecoratedResponseFactory;

$psr17Factory = new Psr17Factory();
$decoratedResponseFactory = new DecoratedResponseFactory($psr17Factory, $psr17Factory);
$response = $decoratedResponseFactory->createResponse(200)->withJson(['ok' => true]);

Your first real use case: returning JSON responses with withJson() and file downloads with withFileDownload() — no manual header wrangling.

Implementation Patterns

• Response embellishment in controllers
  Use DecoratedResponseFactory to build rich responses:

  $response = $responseFactory->createResponse(201)
      ->withJson(['id' => $user->id], 201)
      ->withHeader('X-Resource', 'users');
  

• Smart redirects & status helpers
  Replace manual redirect logic:

  return $response->withRedirect('/dashboard', 302);
  // Or status checks:
  if ($response->isNotFound()) { /* ... */ }
  

• Request parsing & validation helpers
  Use DecoratedServerRequestFactory to avoid repeated boilerplate:

  $mediaType = $request->getMediaType(); // 'application/json'
  $jsonPayload = $request->getParsedBody(); // auto-parsed JSON/XML
  $userId = $request->getParsedBodyParam('user_id');
  $token = $request->getCookieParam('token');
  

• Custom content-type parsing
  Register parsers for non-standard formats:

  $request = $request->registerMediaTypeParser('application/vnd.api+json', function ($body) {
      return json_decode($body, true);
  });
  

• URL helper for frontend routes
  Use Uri::getBaseUrl() to generate absolute URLs:

  $baseUrl = $uri->getBaseUrl(); // e.g., 'https://app.example.com'
  

• Method & request introspection
  Replace $_SERVER['REQUEST_METHOD'] checks:

  if ($request->isPost() && $request->isXhr()) {
      // Handle AJAX POST
  }
  

Gotchas and Tips

• Deprecation note: The package is not part of Slim 4 core. Confirm compatibility — it’s actively maintained (last release 2024-06-24) but low use outside Slim ecosystem. Double-check for duplication with newer frameworks (e.g., Nyholm/psr7 already has withJson() in some versions).

• Factory chaining required: The factory must be constructed with two PSR-7 factories (Response + Stream), even if one implementation (like Nyholm) implements both. Don’t forget:

  new DecoratedResponseFactory($responseFactory, $streamFactory);
  

• Parsed body auto-detection may be incomplete: getParsedBody() auto-parses JSON/XML only. For forms (application/x-www-form-urlencoded), ensure underlying PSR-7 implementation already populates $_POST; otherwise, parse manually or register a parser.

• write() is additive, not replacements: $response->write($chunk) appends to body — not a setBody(). To overwrite, use withBody($stream).

• MIME type detection is heuristic-based: withFile() defaults to detecting Content-Type via extension. Disable if insecure (false) or hardcode if trust is guaranteed.

• No native caching for headers: Each with*() call returns a new immutable object — avoid deep chaining in hot paths; clone once, mutate if perf-sensitive.

• Extension tip: Decorators preserve underlying PSR-7 interface, so they work seamlessly with middleware expecting strict PSR-7 (e.g., Slim middleware, Nyholm Bridge). No breaking changes.