Requête HTTP

Nette encapsule la requête HTTP dans des objets avec une API compréhensible et fournit en même temps un filtre d'assainissement.

La requête HTTP est représentée par l'objet Nette\Http\Request. Si vous travaillez avec Nette, cet objet est automatiquement créé par le framework et vous pouvez vous le faire passer via l'injection de dépendances. Dans les presenters, il suffit d'appeler la méthode $this->getHttpRequest(). Si vous travaillez en dehors du Nette Framework, vous pouvez créer l'objet à l'aide de RequestFactory.

Un grand avantage de Nette est que lors de la création de l'objet, il nettoie automatiquement tous les paramètres d'entrée GET, POST, COOKIE ainsi que l'URL des caractères de contrôle et des séquences UTF-8 invalides. Vous pouvez ensuite travailler en toute sécurité avec ces données. Les données nettoyées sont ensuite utilisées dans les presenters et les formulaires.

→ Installation et prérequis

Nette\Http\Request

Cet objet est immutable (immuable). Il n'a pas de setters, il n'a qu'un seul “wither” withUrl(), qui ne modifie pas l'objet, mais retourne une nouvelle instance avec la valeur modifiée.

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

Retourne un clone avec une URL différente.

getUrl(): Nette\Http\UrlScript

Retourne l'URL de la requête sous forme d'objet UrlScript.

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

Attention : les navigateurs n'envoient pas le fragment au serveur, donc $url->getFragment() retournera une chaîne vide.

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

Retourne les paramètres GET de la requête.

$all = $httpRequest->getQuery(); // retourne un tableau de tous les paramètres de l'URL
$id = $httpRequest->getQuery('id'); // retourne le paramètre GET 'id' (ou null)

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

Retourne les paramètres POST de la requête.

$all = $httpRequest->getPost(); // retourne un tableau de tous les paramètres de POST
$id = $httpRequest->getPost('id'); // retourne le paramètre POST 'id' (ou null)

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

Retourne l'upload sous forme d'objet Nette\Http\FileUpload :

$file = $httpRequest->getFile('avatar');
if ($file?->hasFile()) { // un fichier a-t-il été uploadé ?
	$file->getUntrustedName(); // nom du fichier envoyé par l'utilisateur
	$file->getSanitizedName(); // nom sans caractères dangereux
}

Pour accéder à une structure imbriquée, spécifiez un tableau de clés.

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

Comme on ne peut pas faire confiance aux données externes et donc pas non plus à la forme de la structure des fichiers, cette méthode est plus sûre que par exemple $request->getFiles()['my-form']['details']['avatar'], qui peut échouer.

getFiles(): array

Retourne l'arbre de tous les uploads dans une structure normalisée, dont les feuilles sont des objets Nette\Http\FileUpload :

$files = $httpRequest->getFiles();

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

Retourne un cookie ou null s'il n'existe pas.

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

getCookies(): array

Retourne tous les cookies.

$cookies = $httpRequest->getCookies();

getMethod(): string

Retourne la méthode HTTP avec laquelle la requête a été effectuée.

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

isMethod (string $method): bool

Teste la méthode HTTP avec laquelle la requête a été effectuée. Le paramètre est insensible à la casse.

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

getHeader (string $header): ?string

Retourne un en-tête HTTP ou null s'il n'existe pas. Le paramètre est insensible à la casse.

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

getHeaders(): array

Retourne tous les en-têtes HTTP sous forme de tableau associatif.

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

isSecured(): bool

La connexion est-elle chiffrée (HTTPS) ? Pour un fonctionnement correct, il peut être nécessaire de configurer le proxy.

isSameSite(): bool

La requête provient-elle du même (sous-)domaine et est-elle initiée par un clic sur un lien ? Nette utilise le cookie _nss (auparavant nette-samesite) pour la détection.

isAjax(): bool

S'agit-il d'une requête AJAX ?

getRemoteAddress(): ?string

Retourne l'adresse IP de l'utilisateur. Pour un fonctionnement correct, il peut être nécessaire de configurer le proxy.

getRemoteHost(): ?string

Retourne la résolution DNS de l'adresse IP de l'utilisateur. Pour un fonctionnement correct, il peut être nécessaire de configurer le proxy.

getBasicCredentials(): ?array

Retourne les informations d'identification pour l'authentification HTTP de base.

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

getRawBody(): ?string

Retourne le corps de la requête HTTP.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Détecte la langue. Comme paramètre $lang, nous passons un tableau des langues que l'application supporte, et elle retourne celle que le navigateur du visiteur préférerait voir. Ce n'est pas de la magie, on utilise simplement l'en-tête Accept-Language. S'il n'y a pas de correspondance, retourne null.

// le navigateur envoie par ex. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // langues supportées par l'application
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

La classe Nette\Http\RequestFactory sert à créer une instance de Nette\Http\Request, qui représente la requête HTTP actuelle. (Si vous travaillez avec Nette, l'objet de requête HTTP est automatiquement créé par le framework.)

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

La méthode fromGlobals() crée l'objet de requête sur la base des variables globales PHP actuelles ($_GET, $_POST, $_COOKIE, $_FILES et $_SERVER). Lors de la création de l'objet, elle nettoie automatiquement tous les paramètres d'entrée GET, POST, COOKIE ainsi que l'URL des caractères de contrôle et des séquences UTF-8 invalides, ce qui garantit la sécurité lors du travail ultérieur avec ces données.

RequestFactory peut être configuré avant d'appeler fromGlobals() :

  • avec la méthode $factory->setBinary() , vous désactivez le nettoyage automatique des paramètres d'entrée des caractères de contrôle et des séquences UTF-8 invalides.
  • avec la méthode $factory->setProxy(...), vous indiquez l'adresse IP du serveur proxy, ce qui est nécessaire pour une détection correcte de l'adresse IP de l'utilisateur.

RequestFactory permet de définir des filtres qui transforment automatiquement des parties de l'URL de la requête. Ces filtres suppriment les caractères indésirables de l'URL, qui peuvent y être insérés par exemple par une implémentation incorrecte des systèmes de commentaires sur différents sites web :

// suppression des espaces du chemin
$requestFactory->urlFilters['path']['%20'] = '';

// suppression du point, de la virgule ou de la parenthèse droite de la fin de l'URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// nettoyage du chemin des doubles barres obliques (filtre par défaut)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

La première clé 'path' ou 'url' détermine à quelle partie de l'URL le filtre s'applique. La deuxième clé est une expression régulière à rechercher, et la valeur est le remplacement qui sera utilisé à la place du texte trouvé.

Fichiers uploadés

La méthode Nette\Http\Request::getFiles() retourne un tableau de tous les uploads dans une structure normalisée, dont les feuilles sont des objets Nette\Http\FileUpload. Ceux-ci encapsulent les données envoyées par l'élément de formulaire <input type=file>.

La structure reflète la dénomination des éléments en HTML. Dans le cas le plus simple, il peut s'agir d'un seul élément de formulaire nommé envoyé comme :

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

Dans ce cas, $request->getFiles() retourne un tableau :

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

L'objet FileUpload est créé même si l'utilisateur n'a envoyé aucun fichier ou si l'envoi a échoué. La méthode hasFile() retourne si un fichier a été envoyé :

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

Dans le cas d'un nom d'élément utilisant la notation pour les tableaux :

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

l'arbre retourné ressemble à ceci :

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

Il est également possible de créer un tableau de fichiers :

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

Dans ce cas, la structure ressemble à ceci :

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

Accéder à l'index 1 du tableau imbriqué se fait de préférence comme ceci :

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

Comme on ne peut pas faire confiance aux données externes et donc pas non plus à la forme de la structure des fichiers, cette méthode est plus sûre que par exemple $request->getFiles()['my-form']['details']['avatars'][1], qui peut échouer.

Aperçu des méthodes FileUpload

hasFile(): bool

Retourne true si l'utilisateur a uploadé un fichier.

isOk(): bool

Retourne true si le fichier a été uploadé avec succès.

getError(): int

Retourne le code d'erreur lors de l'upload du fichier. Il s'agit de l'une des constantes UPLOAD_ERR_XXX. Si l'upload s'est déroulé correctement, retourne UPLOAD_ERR_OK.

move (string $dest)

Déplace le fichier uploadé vers un nouvel emplacement. Si le fichier de destination existe déjà, il sera écrasé.

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

getContents(): ?string

Retourne le contenu du fichier uploadé. Si l'upload n'a pas réussi, retourne null.

getContentType(): ?string

Détecte le type de contenu MIME du fichier uploadé sur la base de sa signature. Si l'upload n'a pas réussi ou si la détection a échoué, retourne null.

Nécessite l'extension PHP fileinfo.

getUntrustedName(): string

Retourne le nom original du fichier, tel qu'envoyé par le navigateur.

Ne faites pas confiance à la valeur retournée par cette méthode. Le client aurait pu envoyer un nom de fichier malveillant dans l'intention d'endommager ou de pirater votre application.

getSanitizedName(): string

Retourne le nom de fichier assaini. Il ne contient que des caractères ASCII [a-zA-Z0-9.-]. Si le nom ne contient pas de tels caractères, retourne 'unknown'. Si le fichier est une image au format JPEG, PNG, GIF, WebP ou AVIF, retourne également la bonne extension.

Nécessite l'extension PHP fileinfo.

getSuggestedExtension(): ?string

Retourne l'extension de fichier appropriée (sans le point) correspondant au type MIME détecté.

Nécessite l'extension PHP fileinfo.

getUntrustedFullPath(): string

Retourne le chemin d'accès original du fichier, tel qu'envoyé par le navigateur lors de l'upload d'un dossier. Le chemin complet n'est disponible qu'en PHP 8.1 et supérieur. Dans les versions précédentes, cette méthode retourne le nom de fichier original.

Ne faites pas confiance à la valeur retournée par cette méthode. Le client aurait pu envoyer un nom de fichier malveillant dans l'intention d'endommager ou de pirater votre application.

getSize(): int

Retourne la taille du fichier uploadé. Si l'upload n'a pas réussi, retourne 0.

getTemporaryFile(): string

Retourne le chemin d'accès à l'emplacement temporaire du fichier uploadé. Si l'upload n'a pas réussi, retourne ''.

isImage(): bool

Retourne true si le fichier uploadé est une image au format JPEG, PNG, GIF, WebP ou AVIF. La détection est basée sur sa signature et ne vérifie pas l'intégrité de l'ensemble du fichier. On peut vérifier si une image n'est pas endommagée, par exemple, en essayant de la charger.

Nécessite l'extension PHP fileinfo.

getImageSize(): ?array

Retourne une paire [largeur, hauteur] avec les dimensions de l'image uploadée. Si l'upload n'a pas réussi ou s'il ne s'agit pas d'une image valide, retourne null.

toImage(): Nette\Utils\Image

Charge l'image comme un objet Image. Si l'upload n'a pas réussi ou s'il ne s'agit pas d'une image valide, lève une exception Nette\Utils\ImageException.

  1. Documentation
  2. Nette HTTP
  3. Requête HTTP
version: 4.0