Demande HTTP

Nette encapsule la requête HTTP dans des objets avec une API compréhensible tout en fournissant un filtre de désinfection.

Une requête HTTP est un objet Nette\Http\Request, que vous obtenez en le passant en utilisant l'injection de dépendances. Dans les présentateurs, il suffit d'appeler $httpRequest = $this->getHttpRequest().

Ce qui est important, c'est que Nette, en créant cet objet, efface tous les paramètres d'entrée GET, POST et COOKIE ainsi que les URL des caractères de contrôle et des séquences UTF-8 invalides. Vous pouvez donc continuer à travailler avec les données en toute sécurité. Les données nettoyées sont ensuite utilisées dans les présentateurs et les formulaires.

→ Installation et exigences

Nette\Http\Request

Cet objet est immuable. Il n'a pas de setters, il n'a qu'un seul appelé wither withUrl(), qui ne change pas l'objet, mais renvoie une nouvelle instance avec une valeur modifiée.

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

Renvoie un clone avec une URL différente.

getUrl(): Nette\Http\UrlScript

Renvoie l'URL de la demande sous forme d'objet UrlScript.

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

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

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

Renvoie les paramètres de la requête GET :

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

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

Renvoie les paramètres de la demande POST :

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

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

Renvoie le téléchargement en tant qu'objet Nette\Http\FileUpload:

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

Spécifier un tableau de clés pour accéder à la structure du sous-arbre.

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

Étant donné que vous ne pouvez pas faire confiance aux données de l'extérieur et que vous ne vous fiez donc pas à la forme de la structure, cette méthode est plus sûre que la méthode $request->getFiles()['my-form']['details']['avatar']qui peut échouer.

getFiles(): array

Renvoie l'arbre des fichiers de téléchargement dans une structure normalisée, avec chaque feuille une instance de Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

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

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

getCookies(): array

Renvoie tous les cookies :

$cookies = $httpRequest->getCookies();

getMethod(): string

Renvoie la méthode HTTP avec laquelle la demande a été effectuée.

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

isMethod(string $method): bool

Vérifie la méthode HTTP avec laquelle la demande a été faite. Le paramètre n'est pas sensible à la casse.

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

getHeader(string $header): ?string

Renvoie 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

Renvoie tous les en-têtes HTTP sous forme de tableau associatif :

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

isSecured(): bool

La connexion est-elle cryptée (HTTPS) ? Vous devrez peut-être configurer un proxy pour une bonne fonctionnalité.

isSameSite(): bool

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

isAjax(): bool

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

getRemoteAddress(): ?string

Renvoie l'adresse IP de l'utilisateur. Il se peut que vous deviez configurer un proxy pour une bonne fonctionnalité.

getRemoteHost(): ?string

Renvoie la traduction DNS de l'adresse IP de l'utilisateur. Il se peut que vous deviez configurer un proxy pour une bonne fonctionnalité.

getBasicCredentials(): ?string

Renvoie les informations d'authentification HTTP de base.

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

getRawBody(): ?string

Renvoie le corps de la requête HTTP :

$body = $httpRequest->getRawBody();

detectLanguage(array $langs): ?string

Détection de la langue. En tant que paramètre $lang, nous passons un tableau des langues que l'application prend en charge, et la méthode renvoie la langue préférée du navigateur. Ce n'est pas de la magie, la méthode utilise simplement l'en-tête Accept-Language. Si aucune correspondance n'est trouvée, elle renvoie null.

// En-tête envoyé par le navigateur: 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

L'objet de la requête HTTP courante est créé par Nette\Http\RequestFactory. Si vous écrivez une application qui n'utilise pas de conteneur DI, vous créez une requête comme suit :

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

RequestFactory peut être configuré avant d'appeler fromGlobals(). Nous pouvons désactiver toute la désinfection des paramètres d'entrée à partir de séquences UTF-8 invalides en utilisant $factory->setBinary(). Et aussi configurer un serveur proxy, ce qui est important pour la détection correcte de l'adresse IP de l'utilisateur en utilisant $factory->setProxy(...).

Il est possible de nettoyer les URL des caractères qui peuvent s'y introduire en raison de systèmes de commentaires mal implémentés sur divers autres sites Web en utilisant des filtres :

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

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

// nettoyer le chemin des barres obliques dupliquées (filtre par défaut)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Fichiers téléchargés

La méthode Nette\Http\Request::getFiles() renvoie un arbre de fichiers téléchargés dans une structure normalisée, chaque feuille étant une instance de Nette\Http\FileUpload. Ces objets encapsulent les données soumises par l'élément de formulaire <input type=file> élément de formulaire.

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

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

Dans ce cas, le site $request->getFiles() renvoie un tableau :

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

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

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

Dans le cas d'une entrée utilisant la notation tableau pour le nom :

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

l'arbre retourné finit par ressembler à ceci :

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

Vous pouvez également créer des tableaux de fichiers :

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

Dans ce cas, la structure ressemble à :

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

La meilleure façon d'accéder à l'indice 1 d'un tableau imbriqué est la suivante :

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

Parce que vous ne pouvez pas faire confiance aux données de l'extérieur et donc ne pas vous fier à la forme de la structure, cette méthode est plus sûre que $request->getFiles()['my-form']['details']['avatars'][1]qui peut échouer.

Aperçu des méthodes de FileUpload

hasFile(): bool

Renvoie true si l'utilisateur a téléchargé un fichier.

isOk(): bool

Renvoie true si le fichier a été téléchargé avec succès.

getError(): int

Renvoie le code d'erreur associé au fichier téléchargé. Il s'agit de l'une des constantes UPLOAD_ERR_XXX. Si le fichier a été téléchargé avec succès, il renvoie UPLOAD_ERR_OK.

move(string $dest)

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

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

getContents(): ?string

Renvoie le contenu du fichier téléchargé. Si le téléchargement n'a pas réussi, il renvoie null.

getContentType(): ?string

Détecte le type de contenu MIME du fichier téléchargé en se basant sur sa signature. Si le téléchargement n'a pas réussi ou si la détection a échoué, il renvoie null.

Nécessite l'extension PHP fileinfo.

getUntrustedName(): string

Renvoie le nom du fichier original tel que soumis par le navigateur.

Ne vous fiez pas à la valeur renvoyée par cette méthode. Un client pourrait envoyer un nom de fichier malveillant dans le but de corrompre ou de pirater votre application.

getSanitizedName(): string

Renvoie le nom de fichier aseptisé. Il ne contient que des caractères ASCII [a-zA-Z0-9.-]. Si le nom ne contient pas de tels caractères, il renvoie “inconnu”. Si le fichier est une image JPEG, PNG, GIF ou WebP, il renvoie l'extension de fichier correcte.

Requiert l'extension PHP fileinfo.

getSuggestedExtension(): ?string

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

Requiert l'extension PHP fileinfo.

getUntrustedFullPath(): string

Renvoie le chemin complet d'origine tel qu'il a été soumis par le navigateur lors du téléchargement du répertoire. Le chemin complet n'est disponible qu'à partir de la version 8.1 de PHP. Dans les versions précédentes, cette méthode renvoie le nom du fichier non fiable.

Ne faites pas confiance à la valeur renvoyée par cette méthode. Un client pourrait envoyer un nom de fichier malveillant dans le but de corrompre ou de pirater votre application.

getSize(): int

Renvoie la taille du fichier téléchargé. Si le téléchargement n'a pas réussi, il renvoie 0.

getTemporaryFile(): string

Renvoie le chemin de l'emplacement temporaire du fichier téléchargé. Si le téléchargement n'a pas réussi, il renvoie ''.

isImage(): bool

Renvoie true si le fichier téléchargé est une image JPEG, PNG, GIF ou WebP. La détection est basée sur sa signature. L'intégrité de l'ensemble du fichier n'est pas vérifiée. Vous pouvez savoir si une image n'est pas corrompue, par exemple en essayant de la charger.

Nécessite l'extension PHP fileinfo.

getImageSize(): ?array

Retourne une paire de [width, height] avec les dimensions de l'image téléchargée. Si le téléchargement n'a pas réussi ou si l'image n'est pas valide, il renvoie null.

toImage(): Nette\Utils\Image

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

  1. Documentation
  2. Nette HTTP
  3. Demande HTTP
version: 4.0