Requests and Responses

Derafu\Http\Request and Derafu\Http\Response wrap PSR-7 messages and add shortcuts for the things an application does all the time: reading input, negotiating the format and building common responses.

Request

Request implements PSR-7’s ServerRequestInterface, so everything from PSR-7 is available. It is created by RequestFactoryMiddleware, which means a handler or any middleware after it receives a Derafu\Http\Request.

Reading input

$id = $request->query('id', 0);              // From the query string.
$name = $request->post('name');              // From the parsed body (form).
$token = $request->header('X-Token', '');    // First value of a header.

if ($request->isJson()) {
    $data = $request->json();                // Decoded array, or null.
}

$all = $request->all();
$email = $request->input('email', '');
$some = $request->only(['name', 'email']);

Files

if ($request->hasFile('document')) {
    $file = $request->file('document');   // PSR-7 UploadedFileInterface.
}
$files = $request->files();

hasFile() is true only when the file was uploaded without error. file() returns null when there is no such file.

Application context

route(), session() and flash() throw a LogicException when the middleware that provides them did not run before. user() never throws.

Content negotiation

The request decides which format the client wants, and the response, errors included, follow it. getPreferredContentType() checks, in this order:

1. The extension in the URL: /report.json means JSON, /page.html means HTML.
2. Whether it is an API request, that is the path is /api or starts with /api/: JSON.
3. Whether it is an XHR request (X-Requested-With: XMLHttpRequest): JSON.
4. The Accept header, ordered by its q values. The first of application/json, text/html or text/plain that appears wins.
5. HTML, when there is no Accept header or none of those is in it.

getPreferredFormat() returns the same as a subtype string (json, html, …). isApiRequest() and isXmlHttpRequest() expose the individual checks.

Response

use Derafu\Http\Enum\HttpStatus;
use Derafu\Http\Response;

return (new Response())
    ->asJson(['id' => 42])
    ->withHttpStatus(HttpStatus::CREATED);

Returning data instead of a response

A handler does not have to build a Response. If it returns an array, a string or an object, ResponseNormalizerMiddleware turns it into one using the preferred content type of the request. See Middleware.

public function show(string $id): array
{
    // Sent as JSON to an API client.
    return ['id' => $id];
}

Build the Response yourself when you need control over the status or the headers.

Enums

ContentType

Derafu\Http\Enum\ContentType lists the media types the library knows. Besides its value (the media type string) it provides:

HttpStatus

Derafu\Http\Enum\HttpStatus has a case for each status code, for example HttpStatus::NOT_FOUND. It provides getReasonPhrase() and the checks isInformational(), isSuccessful(), isRedirection(), isClientError(), isServerError() and isError().