Request

An overview of the http request object

Overview

HTTP Request Object

An HTTP request object represents the current HTTP request received by your web server.

A PSR-7 request oject is passed on to all routes and middleware controllers/handlers/callbacks that you can use to inspect and manipulate the HTTP request method, headers, and body.

A BitFrame request object has methods implemented from the following interfaces:

As per PSR-7 standard directive \Psr\Http\Message\ServerRequestInterface extends \Psr\Http\Message\RequestInterface which extends \Psr\Http\Message\MessageInterface, therefore, a typical PSR-7 request object would have methods implemented from each of these interfaces.

Middlewares that are run via the same instance of \BitFrame\Application share the HTTP request that may or may not have been modified from its original state (for example, by the middlewares in the queue). This is by design, so modified HTTP requests can be re-used and shared among all middlewares. In case, you wish to run a fresh batch of middlewares with the original HTTP request, you could simply create a new instance of \BitFrame\Application, or if you wanted to work on the original HTTP request object (one that was received by your web server) you could do so by accessing it via the getOriginalRequest() method.

Accessing The Request:

The request object is injected into the \BitFrame\Application routes as the first argument to the route callback/handler/controller, for example:

use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Message\ResponseInterface as Response;

$app = new \BitFrame\Application;

$app->get('/', function(Request $request, Response $response, callable $next) {
    // do something
});

Similarly, the middleware callback/handler/controller also gets the request object as the first argument, for example:

use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Message\ResponseInterface as Response;

$app = new \BitFrame\Application;

$app->addMiddleware(function(Request $request, Response $response, callable $next) {
    // do something
});

In these examples, we're using anonymous functions as handlers. However, you may choose to use other ways to handle middlewares and to handle routes as shown in our guides.

You can also get the \Psr\Http\Message\ServerRequestInterface instance by calling the getRequest() method on \BitFrame\Application object like so:

$app = new \BitFrame\Application;

$request = $app->getRequest();

Since the request object can be manipulated by the routes/middlewares that access it, the \BitFrame\Application has a getOriginalRequest() method that you can use to retrieve the original HTTP request object that was received by your web server.

Helper Methods:

Request objects created via \BitFrame\Factory\HttpMessageFactory (which is what's done internally in BitFrame by default) or request objects that use \BitFrame\Message\RequestTrait provide the following proprietary (non-standard) helper methods:

The use of these helper methods is strictly optional as they are merely meant as shortcuts to things you can just as easily accomplish without using them. If you do not wish to use default libraries (as coded into the BitFrame factories), you should avoid using these methods as they're not a part of the PSR standard. As an alternative, you could look at each individual method's source to see how they go about doing things, and can use the code in there as a substitute to using the proprietary methods.

Using get_class() function on http request objects created via the \BitFrame\Factory\HttpMessageFactory would return an anonymous class because internally, we've used an anonymous class to extend functionality of request objects for the libraries we support by default. You could instead use instanceof to validate the class instance or alternatively, you could view our guide on customizing BitFrame which has details on various ways you could replace the default request factory/class.

Request Method

Every HTTP request has a method that describes the action to be performed. It is typically one of the following:

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • PATCH
  • OPTIONS

You can inspect the HTTP request's method by calling the getMethod() method on the request object.

The method names are case-sensitive and must be uppercase.

Request URI:

Every HTTP request has a URI that identifies the requested application resource. An HTTP request URI has several parts such as:

  • Scheme (e.g. http or https)
  • Host (e.g. example.com)
  • Port (e.g. 80 or 443)
  • Path (e.g. /doc/v1)
  • Query string (e.g. sort_by=price&dir=asc)

You can fetch the URI object by calling the getUri() method on the request object like so:

$uri = $request->getUri();

The URI object implements \Psr\Http\Message\UriInterface, providing some useful methods to inspect the HTTP request's URL.

Request Headers

Every HTTP request has headers. The request headers are metadata that describe the HTTP request.

To get a complete list of header-related methods, see the PSR-7 interfaces implemented by a PSR-7 http request object.

Get All Headers:

You can get all the request headers by using the getHeaders() method on the request object like so:

$headers = $request->getHeaders();
foreach ($headers as $name => $values) {
    echo $name . ": " . implode(", ", $values);
}
Get Single Header:

Similarly, to retrieve a single header value, you could use the getHeader() like so:

// $name of the header
$request->getHeader($name);

The return value for the getHeader() method is an array, since a single HTTP header may have more than one value. If the header does not exist, an empty array is returned.

You may also fetch a comma-separated string with all the values for a given header by calling the getHeaderLine() method on the request object like so:

// $name of the header
$request->getHeaderLine($name);
Check If Header Exists:

We could also check if a header exists by using the hasHeader() method like so:

// $name of the header
$request->hasHeader($name);

Request Body

Every HTTP request message has a body which can consist of any content. The getBody() method can be used to retrieve the HTTP request's body content which returns an instance of \Psr\Http\Message\StreamInterface, for example:

$body = $request->getBody();

See \Psr\Http\Message\StreamInterface to get a complete list of methods available.

You could also retrieve any parameters provided in the request body by using the getParsedBody() method, for example:

$parsedBody = $request->getParsedBody();

The getParsedBody() method may return any results of deserializing the request body content. As parsing returns structured content, the potential return types are going to be arrays or objects only. A null value indicates the absence of body content.

Comments

Let us know if you have something to say or add