Request #

The request object provides an interface for accessing and manipulating the current HTTP request being handled by your application, as well as retrieving input, cookies, and files that were submitted with the request.

Using the request object #

There are different ways you can access an instance of the Leaf request object. We've listed a couple of them below, every method below will return the active instance of Leaf request.

app()->post('/items/add', function () {
  echo request()->get('username');
});

Leaf\Http\Request::get('name');

// or

use Leaf\Http\Request;

Request::get('name');

Request on the Leaf Instance #

If you are using request in a leaf app, leaf automatically binds the request class to the leaf instance, so you can always access the leaf request object without having to include any classes or namespaces.

app()->post('/user/change-username', function () {
  echo app()->request()->get('username');
});

$app = new Leaf\App;

$app->post('/user/change-username', function () use($app) {
  echo $app->request()->get('username');
});

Basic Request Information #

The request instance has several methods that allow you to inspect the HTTP request made to your application. Some useful methods include:

get #

get() is a general purpose method which retrieves a particular item from the request body. In simpler terms, it works like $_POST['key'] but works for all request types. It takes in one parameter: the key of the parameter you wish to get.

$app->post('/name/add', function () use($app) {
  $name = $app->request()->get('name');
});

// get: linkToApp?id=1
$id = $app->request()->get('id');

app()->post('/name/add', function () {
  $name = request()->get('name');
});

// get: linkToApp?id=1
$id = request()->get('id');

In v2.4, get can also be used on files passed into the request.

$picture = $app->request()->get('image');

$picture = request()->get('image');

Multiple select #

In v2.4, you can retrieve a couple of fields you want, and not just one. You can also use this as a filter to return only the data you want in your app instead of using body which dumps all request data.

$loginData = $app->request()->get(['username', 'password']);
// ... do something with username
echo $loginData['username'];

$loginData = request()->get(['username', 'password']);
// ... do something with username
echo $loginData['username'];

This allows you to set data you need dynamically.

list($username, $password) = array_values($app->request()->get(['username', 'password']));
// ... do something with username
echo $username;

list($username, $password) = array_values(request()->get(['username', 'password']));
// ... do something with username
echo $username;

Security Fixes #

get() has also received a bunch of security fixes which prevent malicious scripts from being passed into your application. In v2.4, you can choose not to sanitize data coming into your application by passing in false as the second parameter.

// data is sanitized
$username = $app->request()->get('username');
// data is sanitized
$title = $app->request()->get('title', true);
// data is not sanitized
$blog = $app->request()->get('blogBody', false);

// data is sanitized
$username = request()->get('username');
// data is sanitized
$title = request()->get('title', true);
// data is not sanitized
$blog = request()->get('blogBody', false);

try #

try() works just like get above, except that it conditionally returns items in the request. Let's look at an example:

// get request: linkToApp?name=mychi
$data = $app->request()->try(['name', 'email']);

// $data -> ['name' => 'mychi'];

// get request: linkToApp?name=mychi
$data = request()->try(['name', 'email']);

// $data -> ['name' => 'mychi'];

Unlike get and body, if the parameter to find in the request is not found, it will automatically be removed from the data returned. You can also remove empty strings from the request by passing true as a third parameter.

The available parameters are:

• array - The parameters to return
• bool - Sanitize output? Default true
• bool - Remove empty strings from return data? Default false

getOrDefault() #

This is exactly like get above, however, it allows you to specify a default value in case the item is not found in the request. It also does NOT support multiple select.

$app->request()->getOrDefault('description', 'No Description');

request()->getOrDefault('description', 'No Description');

In case description was not passed into the request above, Leaf will return No Description instead of an null field.

body #

body() is another general purpose method which retrieves the key => value pairs of the entire request body. In simpler terms, it works like $_POST but works for all request types. In v2.4, body can also retrieve files passed into the request.

$app->post('/name/add', function () use($app) {
  $body = $app->request()->body();
});

app()->post('/name/add', function () {
  $body = request()->body();
});

Security Fixes #

body has also received a bunch of security fixes which prevent maliscious scripts from being passed into your application. It accepts a boolean option which determines if the data coming into your application is sanitized or not. This means that you can turn off the sanitization in case you trust the source of data. By default, this option is enabled.

// data is sanitized
$body = $app->request()->body();

// data is sanitized
$body = $app->request()->body(true);

// data is not sanitized
$body = $app->request()->body(false);

// data is sanitized
$body = request()->body();

// data is sanitized
$body = request()->body(true);

// data is not sanitized
$body = request()->body(false);

files #

You may access uploaded files that are included with the request using the files method. This returns the raw file to you:

$image = $app->request()->files("profile_pic");

$image = request()->files('profile_pic');

You can also get multiple files

list($profile, $avatar) = array_values($app->request()->files(['profile', 'avatar']));

list($profile, $avatar) = array_values(request()->files(['profile', 'avatar']));

rawData #

This method allows you to access the raw PHP input stream only. This works with requests like JSON and xml-http requests. It takes in a string or array of the data you want to retrieve and the default if that data isn't found.

$app->request()->rawData('description', 'No Description');

request()->rawData('description', 'No Description');

urlData #

This method allows you to access GET request data only. It takes in a string or array of the data you want to retrieve and the default if that data isn't found.

$app->request()->urlData('item', 'default');

request()->urlData('item', 'default');

postData #

This method allows you to access the post request data only. It takes in a string or array of the data you want to retrieve and the default if that data isn't found.

$app->request()->postData('description', 'No Description');

request()->postData('description', 'No Description');

Validating Request Data ^new #

Leaf Request now comes with a built-in validator which allows you to validate request data directly on the request object. You don't need to install or configure anything. To get started, all you need to do is call validate() on the request object.

<?php

$app = new Leaf\App;

...

$app->post('/register', function() use($app) {
  $success = $app->request()->validate([
    'name' => 'text',
    'email' => 'email',
    'password' => 'min:8',
  ]);

  if (!$success) {
    $errors = $app->request()->errors();
  }
});

<?php

app()->post('/register', function() {
  $success = request()->validate([
    'name' => 'text',
    'email' => 'email',
    'password' => 'min:8',
  ]);

  if (!$success) {
    $errors = request()->errors();
  }
});

Saving files from the request #

When a user sends a file over to your application, for instance updating a profile picture, you can save the file to a directory on your server. Leaf provides a simple way to do this using the upload() method. It takes in 3 parameters:

• The name of the file in the request
• The directory to save the file to
• Options to save the file with

$uploadInfo = request()->upload('profile_pic', './uploads');

This requires the Leaf FS module. If you are not using Leaf MVC, you will have to install it manually:

leaf install fs

# or

composer require leafs/fs

If you want to save the file using a different name, you can pass in the name as the third parameter:

$uploadInfo = request()->upload('profile_pic', './uploads', [
  'name' => 'new_name',
  'rename' => true
]);

Request Headers and Cookies #

The request instance also contains methods which allow you retrieve headers and cookies from the incoming request.

Headers #

A Leaf application will automatically parse all HTTP request headers. You can access the request headers using the request object's headers method.

// Get request headers as associative array
$headers = $app->request()->headers();

// Get the ACCEPT_CHARSET header
$charset = $app->request()->headers('ACCEPT_CHARSET');

// Get some specific headers as an array
$headers = $app->request()->headers(['ACCEPT_CHARSET', 'X-Header-Name']);

// Get request headers as associative array
$headers = request()->headers();

// Get the ACCEPT_CHARSET header
$charset = request()->headers('ACCEPT_CHARSET');

// Get some specific headers as an array
$headers = request()->headers(['ACCEPT_CHARSET', 'X-Header-Name']);

Note that Leaf will automatically sanitize the headers that come into your application. This means that you don't have to worry about malicious scripts being passed into your application. If you however want to disable this feature, you can pass in a boolean option to the second field of the headers method. By default, this option is enabled.

$charset = $app->request()->headers('ACCEPT_CHARSET', false);

$charset = request()->headers('ACCEPT_CHARSET', false);

Also, the hasHeader method may be used to determine if the request contains a given header:

if ($app->request()->hasHeader('X-Header-Name')) {
    //
}

if (request()->hasHeader('X-Header-Name')) {
    //
}

The HTTP specification states that HTTP header names may be uppercase, lowercase, or mixed-case. Leaf is smart enough to parse and return header values whether you request a header value using upper, lower, or mixed case header name, with either underscores or dashes. So use the naming convention with which you are most comfortable.

Cookies #

Leaf also provides a cookies method on the request object which allows you to get cookie data.

// get specific cookie
$app->request()->cookies('name');

// get all cookies
$app->request()->cookies();

// get specific cookie
request()->cookies('name');

// get all cookies
request()->cookies();

Request Method functions #

Every HTTP request has a method (e.g. GET or POST). You can obtain the current HTTP request method via the Leaf application's request object:

typeIs #

This method allows you to check what method type a request uses.

$isGetRequest = $app->request()->typeIs('GET');
$isPostRequest = $app->request()->typeIs('post');
$isDeleteRequest = $app->request()->typeIs('Delete');

if ($isGetRequest) $app->response()->exit('GET method not allowed');

$isGetRequest = request()->typeIs('GET');
$isPostRequest = request()->typeIs('post');
$isDeleteRequest = request()->typeIs('Delete');

if ($isGetRequest) response()->exit('GET method not allowed');

Here are some other functions you can use relating to the request method.

/**
 * What is the request method?
 * @return string (e.g. GET, POST, PUT, DELETE)
 */
$app->request()->getMethod();

/**
 * What is the request method?
 * @return string (e.g. GET, POST, PUT, DELETE)
 */
request()->getMethod();

XHR #

When using a Javascript framework like MooTools or jQuery to execute an XMLHttpRequest, the XMLHttpRequest will usually be sent with a X-Requested-With HTTP header. The Leaf application will detect the HTTP request’s X-Requested-With header and flag the request as such. If for some reason an XMLHttpRequest cannot be sent with the X-Requested-With HTTP header, you can force the Leaf application to assume an HTTP request is an XMLHttpRequest by setting a GET, POST, or PUT parameter in the HTTP request named “isajax” with a truthy value.

Use the request object’s isAjax() or isXhr() method to tell if the current request is an XHR/Ajax request:

$isXHR = $app->request()->isAjax();
$isXHR = $app->request()->isXhr();

$isXHR = request()->isAjax();
$isXHR = request()->isXhr();

isFormData #

This method allows you to check if the request body contains parsed form data, or if the request is a form data request.

$isXHR = $app->request()->isFormData();

$isXHR = request()->isFormData();

Request Path, Host & Client #

This section contains methods which allow you to retrieve information about the request path, host and client.

Host #

Fetch the request’s host (e.g. “leafphp.dev”):

request()->getHost();

$app->request()->getHost();

Host with Port #

Fetch the request’s host with port (e.g. “leafphp.dev:80”):

$app->request()->getHostWithPort();

request()->getHostWithPort();

Port #

Fetch the request’s port (e.g. 80):

$app->request()->getPort();

request()->getPort();

Scheme #

Fetch the request’s scheme (e.g. “http” or “https”):

$app->request()->getScheme();

request()->getScheme();

Path #

Fetch the request’s path (root URI + resource URI):

$app->request()->getPath();

request()->getPath();

URL #

Fetch the request’s URL (scheme + host [ + port if non-standard ]):

$app->request()->getUrl();

request()->getUrl();

IP Address #

Fetch the request’s IP address:

$app->request()->getIp();

request()->getIp();

Referer #

Fetch the request’s referrer:

$app->request()->getReferrer();

request()->getReferrer();

User Agent #

Fetch the request’s user agent string:

$app->request()->getUserAgent();

request()->getUserAgent();

Paths #

Every HTTP request received by a Leaf application will have a root URI and a resource URI.

Root URI #

The root URI is the physical URL path of the directory in which the Leaf application is instantiated and run. If a Leaf application is instantiated in index.php within the top-most directory of the virtual host’s document root, the root URI will be an empty string. If a Leaf application is instantiated and run in index.php within a physical subdirectory of the virtual host’s document root, the root URI will be the path to that subdirectory with a leading slash and without a trailing slash.

Resource URI #

The resource URI is the virtual URI path of an application resource. The resource URI will be matched to the Leaf application’s routes.

Assume the Leaf application is installed in a physical subdirectory /foo beneath your virtual host’s document root. Also assume the full HTTP request URL (what you’d see in the browser location bar) is /foo/books/1. The root URI is /foo (the path to the physical directory in which the Leaf application is instantiated) and the resource URI is /books/1 (the path to the application resource).

You can get the HTTP request’s root URI and resource URI with the request object’s getScriptName() and getPathInfo() methods:

$app = new \Leaf\App;

//Get root URI
$rootUri = $app->request()->getScriptName();

//Get resource URI
$resourceUri = $app->request()->getPathInfo();

//Get root URI
$rootUri = request()->getScriptName();

//Get resource URI
$resourceUri = request()->getPathInfo();

Content Type Methods #

The Leaf application’s request object provides several helper methods for inspecting the content type of the current HTTP request.

Content Type #

Fetch the request’s content type (e.g. “application/json;charset=utf-8”):

$app->request()->getContentType();

request()->getContentType();

Media Type #

Fetch the request’s media type (e.g. “application/json”):

$app->request()->getMediaType();

request()->getMediaType();

Media Type Params #

Fetch the request’s media type parameters (e.g. [charset => “utf-8”]):

$app->request()->getMediaTypeParams();

request()->getMediaTypeParams();

Content Charset #

Fetch the request’s content character set (e.g. “utf-8”):

$app->request()->getContentCharset();

request()->getContentCharset();

Content Length #

Fetch the request’s content length:

$app->request()->getContentLength();

request()->getContentLength();