HTTP Request

Nette encapsulates the HTTP request into objects with an understandable API while providing a sanitization filter.

HTTP request is represented by the Nette\Http\Request object. If you work with Nette, this object is automatically created by the framework and you can have it passed to you using dependency injection. In presenters, you just need to call the $this->getHttpRequest() method. If you work outside the Nette Framework, you can create the object using RequestFactory.

A major advantage of Nette is that when creating the object, it automatically sanitizes all input parameters GET, POST, COOKIE as well as URL from control characters and invalid UTF-8 sequences. You can then safely work with this data. The sanitized data is subsequently used in presenters and forms.

→ Installation and requirements

Nette\Http\Request

This object is immutable. It has no setters, it has only one so-called wither withUrl(), which does not change the object, but returns a new instance with a modified value.

withUrl (Nette\Http\UrlScript $url): Nette\Http\Request

Returns a clone with a different URL.

getUrl(): Nette\Http\UrlScript

Returns the URL of the request as object UrlScript.

$url = $httpRequest->getUrl();
echo $url; // https://nette.org/en/documentation?action=edit
echo $url->getHost(); // nette.org

Warning: Browsers do not send a fragment to the server, so $url->getFragment() will return an empty string.

getQuery (?string $key=null): string|array|null

Returns GET request parameters:

$all = $httpRequest->getQuery();    // array of all URL parameters
$id = $httpRequest->getQuery('id'); // returns GET parameter 'id' (or null)

getPost (?string $key=null): string|array|null

Returns POST request parameters:

$all = $httpRequest->getPost();     // array of all POST parameters
$id = $httpRequest->getPost('id');  // returns POST parameter 'id' (or null)

getFile (string|string[] $key): Nette\Http\FileUpload|array|null

Returns upload as object Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // was any file uploaded?
	$file->getUntrustedName(); // name of the file sent by user
	$file->getSanitizedName(); // the name without dangerous characters
}

Specify an array of keys to access the subtree structure.

//<input type="file" name="my-form[details][avatar]" multiple>
$file = $request->getFile(['my-form', 'details', 'avatar']);

Because you can't trust data from the outside and therefore don't rely on the form of the structure, this method is safer than $request->getFiles()['my-form']['details']['avatar'], which can fail.

getFiles(): array

Returns tree of upload files in a normalized structure, with each leaf an instance of Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

getCookie (string $key): string|array|null

Returns a cookie or null if it does not exist.

$sessId = $httpRequest->getCookie('sess_id');

getCookies(): array

Returns all cookies:

$cookies = $httpRequest->getCookies();

getMethod(): string

Returns the HTTP method with which the request was made.

echo $httpRequest->getMethod(); // GET, POST, HEAD, PUT

isMethod (string $method): bool

Checks the HTTP method with which the request was made. The parameter is case-insensitive.

if ($httpRequest->isMethod('GET')) // ...

getHeader (string $header): ?string

Returns an HTTP header or null if it does not exist. The parameter is case-insensitive:

$userAgent = $httpRequest->getHeader('User-Agent');

getHeaders(): array

Returns all HTTP headers as associative array:

$headers = $httpRequest->getHeaders();
echo $headers['Content-Type'];

isSecured(): bool

Is the connection encrypted (HTTPS)? You may need to set up a proxy for proper functionality.

isSameSite(): bool

Is the request coming from the same (sub) domain and is initiated by clicking on a link? Nette uses the _nss cookie (formerly nette-samesite) to detect it.

isAjax(): bool

Is it an AJAX request?

getRemoteAddress(): ?string

Returns the user's IP address. You may need to set up a proxy for proper functionality.

getRemoteHost(): ?string

Returns DNS translation of the user's IP address. You may need to set up a proxy for proper functionality.

getBasicCredentials(): ?string

Returns Basic HTTP authentication credentials.

[$user, $password] = $httpRequest->getBasicCredentials();

getRawBody(): ?string

Returns the body of the HTTP request:

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Detects language. As a parameter $lang, we pass an array of languages that the application supports, and it returns the one preferred by browser. It is not magic, the method just uses the Accept-Language header. If no match is reached, it returns null.

// Header sent by browser: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // languages supported in application
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

The Nette\Http\RequestFactory class is used to create an instance of Nette\Http\Request, which represents the current HTTP request. (If you work with Nette, the HTTP request object is automatically created by the framework.)

$factory = new Nette\Http\RequestFactory;
$httpRequest = $factory->fromGlobals();

The fromGlobals() method creates a request object based on the current PHP global variables ($_GET, $_POST, $_COOKIE, $_FILES and $_SERVER). When creating the object, it automatically cleanses all input parameters GET, POST, COOKIE as well as URL from control characters and invalid UTF-8 sequences, which ensures security when working with this data later.

RequestFactory can be configured before calling fromGlobals():

using the method $factory->setBinary() you can disable automatic cleansing of input parameters from control characters and invalid UTF-8 sequences.
using the method $factory->setProxy(...) you specify the IP address of the proxy server, which is necessary for correct detection of the user's IP address.

RequestFactory allows you to define filters that automatically transform parts of the URL request. These filters remove unwanted characters from URLs that may have been inserted, for example, by incorrect implementation of comment systems on various websites:

// removing spaces from the path
$requestFactory->urlFilters['path']['%20'] = '';

// removing a period, comma, or right parenthesis from the end of the URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// cleaning the path from double slashes (default filter)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

The first key 'path' or 'url' determines which part of the URL the filter will be applied to. The second key is a regular expression to be searched for, and the value is the replacement to be used instead of the found text.

Uploaded Files

Method Nette\Http\Request::getFiles() return a tree of upload files in a normalized structure, with each leaf an instance of Nette\Http\FileUpload. These objects encapsulate the data submitted by the <input type=file> form element.

The structure reflects the naming of elements in HTML. In the simplest example, this might be a single named form element submitted as:

<input type="file" name="avatar">

In this case, the $request->getFiles() returns array:

[
	'avatar' => /* FileUpload instance */
]

The FileUpload object is created even if the user did not upload any file or the upload failed. Method hasFile() returns true if a file has been sent:

$request->getFile('avatar')->hasFile();

In the case of an input using array notation for the name:

<input type="file" name="my-form[details][avatar]">

returned tree ends up looking like this:

[
	'my-form' => [
		'details' => [
			'avatar' => /* FileUpload instance */
		],
	],
]

You can also create arrays of files:

<input type="file" name="my-form[details][avatars][] multiple">

In such a case structure looks like:

[
	'my-form' => [
		'details' => [
			'avatars' => [
				0 => /* FileUpload instance */,
				1 => /* FileUpload instance */,
				2 => /* FileUpload instance */,
			],
		],
	],
]

The best way to access index 1 of a nested array is as follows:

$file = $request->getFile(['my-form', 'details', 'avatars', 1]);
if ($file instanceof FileUpload) {
	// ...
}

Because you can't trust data from the outside and therefore don't rely on the form of the structure, this method is safer than $request->getFiles()['my-form']['details']['avatars'][1], which can fail.

Overview of `FileUpload` Methods

hasFile(): bool

Returns true if the user has uploaded a file.

isOk(): bool

Returns true if the file was uploaded successfully.

getError(): int

Returns the error code associated with the uploaded file. It is be one of UPLOAD_ERR_XXX constants. If the file was uploaded successfully, it returns UPLOAD_ERR_OK.

move (string $dest)

Moves an uploaded file to a new location. If the destination file already exists, it will be overwritten.

$file->move('/path/to/files/name.ext');

getContents(): ?string

Returns the contents of the uploaded file. If the upload was not successful, it returns null.

getContentType(): ?string

Detects the MIME content type of the uploaded file based on its signature. If the upload was not successful or the detection failed, it returns null.

Requires PHP extension fileinfo.

getUntrustedName(): string

Returns the original file name as submitted by the browser.

Do not trust the value returned by this method. A client could send a malicious filename with the intention to corrupt or hack your application.

getSanitizedName(): string

Returns the sanitized file name. It contains only ASCII characters [a-zA-Z0-9.-]. If the name does not contain such characters, it returns ‘unknown’. If the file is JPEG, PNG, GIF, WebP or AVIF image, it returns the correct file extension.

Requires PHP extension fileinfo.

getSuggestedExtension(): ?string

Returns the appropriate file extension (without the period) corresponding to the detected MIME type.

Requires PHP extension fileinfo.

getUntrustedFullPath(): string

Returns the original full path as submitted by the browser during directory upload. The full path is only available in PHP 8.1 and above. In previous versions, this method returns the untrusted file name.

Do not trust the value returned by this method. A client could send a malicious filename with the intention to corrupt or hack your application.

getSize(): int

Returns the size of the uploaded file. If the upload was not successful, it returns 0.

getTemporaryFile(): string

Returns the path of the temporary location of the uploaded file. If the upload was not successful, it returns ''.

isImage(): bool

Returns true if the uploaded file is a JPEG, PNG, GIF, WebP or AVIF image. Detection is based on its signature. The integrity of the entire file is not checked. You can find out if an image is not corrupted for example by trying to load it.

Requires PHP extension fileinfo.

getImageSize(): ?array

Returns a pair of [width, height] with dimensions of the uploaded image. If the upload was not successful or is not a valid image, it returns null.

toImage(): Nette\Utils\Image

Loads an image as an Image object. If the upload was not successful or is not a valid image, it throws an Nette\Utils\ImageException exception.

HTTP Request

Nette\Http\Request

withUrl (Nette\Http\UrlScript $url): Nette\Http\Request

getUrl(): Nette\Http\UrlScript

getQuery (?string $key=null): string|array|null

getPost (?string $key=null): string|array|null

getFile (string|string[] $key): Nette\Http\FileUpload|array|null

getFiles(): array

getCookie (string $key): string|array|null

getCookies(): array

getMethod(): string

isMethod (string $method): bool

getHeader (string $header): ?string

getHeaders(): array

isSecured(): bool

isSameSite(): bool

isAjax(): bool

getRemoteAddress(): ?string

getRemoteHost(): ?string

getBasicCredentials(): ?string

getRawBody(): ?string

detectLanguage (array $langs): ?string

RequestFactory

Uploaded Files

Overview of FileUpload Methods

hasFile(): bool

isOk(): bool

getError(): int

move (string $dest)

getContents(): ?string

getContentType(): ?string

getUntrustedName(): string

getSanitizedName(): string

getSuggestedExtension(): ?string

getUntrustedFullPath(): string

getSize(): int

getTemporaryFile(): string

isImage(): bool

getImageSize(): ?array

toImage(): Nette\Utils\Image

Overview of `FileUpload` Methods