Demande HTTP

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

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 cadre et vous pouvez vous le faire passer en utilisant l'injection de dépendance. Dans les présentateurs, il suffit d'appeler la méthode $this->getHttpRequest(). Si vous travaillez en dehors du cadre Nette, vous pouvez créer l'objet à l'aide de RequestFactory.

L'un des principaux avantages 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 les URL des caractères de contrôle et des séquences UTF-8 non valides. Vous pouvez alors travailler en toute sécurité avec ces données. Les données assainies 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

Attention : Les navigateurs n'envoient pas de fragment au serveur, de sorte que $url->getFragment() renvoie 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

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

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

La méthode fromGlobals() crée un objet de requête basé sur les 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 non valides, ce qui garantit la sécurité lors de l'utilisation ultérieure de ces données.

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

  • la méthode $factory->setBinary() permet de désactiver le nettoyage automatique des paramètres d'entrée des caractères de contrôle et des séquences UTF-8 non valides.
  • la méthode $factory->setProxy(...) permet de spécifier l'adresse IP du serveur proxy, nécessaire à la détection correcte de l'adresse IP de l'utilisateur.

RequestFactory vous permet de définir des filtres qui transforment automatiquement certaines parties de la demande d'URL. Ces filtres suppriment les caractères indésirables des URL qui peuvent avoir été insérés, par exemple, en raison d'une mauvaise mise en œuvre des systèmes de commentaires sur différents sites web :

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

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

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

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

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