Solicitud HTTP

Nette encapsula la petición HTTP en objetos con una API comprensible a la vez que proporciona un filtro de desinfección.

Una petición HTTP es un objeto Nette\Http\Request, que se obtiene pasándolo mediante inyección de dependencia. En los presentadores basta con llamar a $httpRequest = $this->getHttpRequest().

Lo importante es que Nette al crear este objeto, limpia todos los parámetros de entrada GET, POST y COOKIE así como las URLs de caracteres de control y secuencias UTF-8 inválidas. Así puede seguir trabajando con los datos de forma segura. Los datos limpiados se utilizan entonces en presentadores y formularios.

→ Instalación y requisitos

Nette\Http\Request

Este objeto es inmutable. No tiene setters, sólo tiene uno llamado wither withUrl(), que no cambia el objeto, pero devuelve una nueva instancia con un valor modificado.

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

Devuelve un clon con una URL diferente.

getUrl(): Nette\Http\UrlScript

Devuelve la URL de la petición como objeto UrlScript.

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

Los navegadores no envían un fragmento al servidor, por lo que $url->getFragment() devolverá una cadena vacía.

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

Devuelve los parámetros de la petición GET:

$all = $httpRequest->getQuery(); // array de todos los parámetros URL
$id = $httpRequest->getQuery('id'); // devuelve el parámetro GET 'id' (o null)

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

Devuelve los parámetros de la solicitud POST:

$all = $httpRequest->getPost(); // array de todos los parámetros POST
$id = $httpRequest->getPost('id'); // devuelve el parámetro POST 'id' (o null)

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

Devuelve la carga como objeto Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($archivo->tieneArchivo()) { // ¿se ha subido algún archivo?
	$file->getUntrustedName(); // nombre del fichero enviado por el usuario
	$file->getSanitizedName(); // el nombre sin caracteres peligrosos
}

Especifica un array de claves para acceder a la estructura del subárbol.

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

Debido a que no se puede confiar en los datos desde el exterior y por lo tanto no depende de la forma de la estructura, este método es más seguro que $request->getFiles()['my-form']['details']['avatar']que puede fallar.

getFiles(): array

Devuelve un árbol de archivos de carga en una estructura normalizada, con cada hoja como una instancia de Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Devuelve una cookie o null si no existe.

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

getCookies(): array

Devuelve todas las cookies:

$cookies = $httpRequest->getCookies();

getMethod(): string

Devuelve el método HTTP con el que se realizó la petición.

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

isMethod(string $method): bool

Comprueba el método HTTP con el que se realizó la solicitud. El parámetro no distingue entre mayúsculas y minúsculas.

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

getHeader(string $header): ?string

Devuelve una cabecera HTTP o null si no existe. El parámetro no distingue entre mayúsculas y minúsculas:

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

getHeaders(): array

Devuelve todas las cabeceras HTTP como matriz asociativa:

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

isSecured(): bool

¿Está cifrada la conexión (HTTPS)? Es posible que tenga que configurar un proxy para que funcione correctamente.

isSameSite(): bool

¿La solicitud procede del mismo (sub)dominio y se inicia al hacer clic en un enlace? Nette utiliza la cookie _nss (antes nette-samesite) para detectarlo.

isAjax(): bool

¿Es una petición AJAX?

getRemoteAddress(): ?string

Devuelve la dirección IP del usuario. Es posible que tenga que configurar un proxy para que funcione correctamente.

getRemoteHost(): ?string

Devuelve la traducción DNS de la dirección IP del usuario. Es posible que tenga que configurar un proxy para que funcione correctamente.

getBasicCredentials(): ?string

Devuelve las credenciales básicas de autenticación HTTP.

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

getRawBody(): ?string

Devuelve el cuerpo de la petición HTTP:

$body = $httpRequest->getRawBody();

detectLanguage(array $langs): ?string

Detecta el idioma. Como parámetro $lang, pasamos un array de idiomas que soporta la aplicación, y devuelve el preferido por navegador. No es magia, el método sólo utiliza la cabecera Accept-Language. Si no hay coincidencias, devuelve null.

// Cabecera enviada por el navegador: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // idiomas soportados en la aplicación
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

El objeto de la petición HTTP actual es creado por Nette\Http\RequestFactory. Si está escribiendo una aplicación que no utiliza un contenedor DI, cree una petición de la siguiente manera:

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

RequestFactory puede configurarse antes de llamar a fromGlobals(). Podemos deshabilitar toda la sanitización de parámetros de entrada de secuencias UTF-8 inválidas usando $factory->setBinary(). Y también configurar un servidor proxy, que es importante para la correcta detección de la dirección IP del usuario utilizando $factory->setProxy(...).

Es posible limpiar las URL de caracteres que puedan introducirse en ellas debido a sistemas de comentarios mal implementados en otros sitios web mediante el uso de filtros:

// eliminar espacios de la ruta
$requestFactory->urlFilters['ruta']['%20'] = '';

// eliminar punto, coma o paréntesis derecho del final de la URL
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// limpiar la ruta de barras duplicadas (filtro por defecto)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Archivos subidos

El método Nette\Http\Request::getFiles() devuelve un árbol de archivos cargados en una estructura normalizada, en la que cada hoja es una instancia de Nette\Http\FileUpload. Estos objetos encapsulan los datos enviados por el elemento de formulario <input type=file> elemento formulario.

La estructura refleja la nomenclatura de los elementos en HTML. En el ejemplo más simple, esto podría ser un único elemento de formulario con nombre enviado como:

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

En este caso, $request->getFiles() devuelve una matriz:

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

El objeto FileUpload se crea aunque el usuario no haya subido ningún archivo o la subida haya fallado. El método hasFile() devuelve true si se ha enviado un archivo:

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

En el caso de una entrada que utilice la notación array para el nombre:

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

el árbol devuelto acaba teniendo este aspecto:

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

También puede crear matrices de archivos:

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

En tal caso la estructura se parece:

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

La mejor forma de acceder al índice 1 de una matriz anidada es la siguiente:

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

Debido a que no se puede confiar en los datos desde el exterior y por lo tanto no se confía en la forma de la estructura, este método es más seguro que $request->getFiles()['my-form']['details']['avatars'][1]que puede fallar.

Visión general de los métodos FileUpload

hasFile(): bool

Devuelve true si el usuario ha subido un archivo.

isOk(): bool

Devuelve true si el archivo se ha cargado correctamente.

getError(): int

Devuelve el código de error asociado al archivo cargado. Es una de las constantes UPLOAD_ERR_XXX. Si el archivo se ha cargado correctamente, devuelve UPLOAD_ERR_OK.

move(string $dest)

Mueve un archivo cargado a una nueva ubicación. Si el archivo de destino ya existe, se sobrescribirá.

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

getContents(): ?string

Devuelve el contenido del archivo cargado. Si la carga no se ha realizado correctamente, devuelve null.

getContentType(): ?string

Detecta el tipo de contenido MIME del archivo cargado basándose en su firma. Si la carga no se ha realizado correctamente o la detección ha fallado, devuelve null.

Requiere la extensión PHP fileinfo.

getUntrustedName(): string

Devuelve el nombre original del archivo tal y como fue enviado por el navegador.

No confíe en el valor devuelto por este método. Un cliente podría enviar un nombre de archivo malicioso con la intención de corromper o hackear su aplicación.

getSanitizedName(): string

Devuelve el nombre de archivo desinfectado. Sólo contiene caracteres ASCII [a-zA-Z0-9.-]. Si el nombre no contiene tales caracteres, devuelve ‘desconocido’. Si el archivo es una imagen JPEG, PNG, GIF o WebP, devuelve la extensión de archivo correcta.

Requiere la extensión PHP fileinfo.

getSuggestedExtension(): ?string

Devuelve la extensión de archivo apropiada (sin el punto) correspondiente al tipo MIME detectado.

Requiere la extensión PHP fileinfo.

getUntrustedFullPath(): string

Devuelve la ruta completa original tal y como fue enviada por el navegador durante la carga del directorio. La ruta completa sólo está disponible en PHP 8.1 y superiores. En versiones anteriores, este método devuelve el nombre de archivo no confiable.

No confíe en el valor devuelto por este método. Un cliente podría enviar un nombre de archivo malicioso con la intención de corromper o hackear su aplicación.

getSize(): int

Devuelve el tamaño del archivo subido. Si la subida no tuvo éxito, devuelve 0.

getTemporaryFile(): string

Devuelve la ruta de la ubicación temporal del archivo subido. Si la carga no se ha realizado correctamente, devuelve ''.

isImage(): bool

Devuelve true si el archivo cargado es una imagen JPEG, PNG, GIF o WebP. La detección se basa en su firma. No se comprueba la integridad de todo el archivo. Puede averiguar si una imagen no está dañada, por ejemplo, intentando cargarla.

Requiere la extensión PHP fileinfo.

getImageSize(): ?array

Devuelve un par de [width, height] con las dimensiones de la imagen subida. Si la carga no se ha realizado correctamente o no es una imagen válida, devuelve null.

toImage(): Nette\Utils\Image

Carga una imagen como objeto Image. Si la carga no se ha realizado correctamente o no es una imagen válida, lanza una excepción Nette\Utils\ImageException.