Solicitud HTTP

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

La petición HTTP está representada por el objeto Nette\Http\Request. Si trabajas con Nette, este objeto es creado automáticamente por el framework y puedes hacértelo pasar usando inyección de dependencia. En los presentadores, basta con llamar al método $this->getHttpRequest(). Si trabajas fuera del Framework Nette, puedes crear el objeto usando RequestFactory.

Una gran ventaja de Nette es que, al crear el objeto, sanea automáticamente todos los parámetros de entrada GET, POST, COOKIE, así como la URL de caracteres de control y secuencias UTF-8 no válidas. A continuación, puede trabajar de forma segura con estos datos. Los datos saneados se utilizan posteriormente 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

Advertencia: Los navegadores no envían fragmentos 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

La clase Nette\Http\RequestFactory se utiliza para crear una instancia de Nette\Http\Request, que representa la petición HTTP actual. (Si trabajas con Nette, el objeto de petición HTTP es creado automáticamente por el framework).

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

El método fromGlobals() crea un objeto de petición basado en las variables globales actuales de PHP ($_GET, $_POST, $_COOKIE, $_FILES y $_SERVER). Al crear el objeto, limpia automáticamente todos los parámetros de entrada GET, POST, COOKIE así como la URL de caracteres de control y secuencias UTF-8 inválidas, lo que garantiza la seguridad al trabajar con estos datos posteriormente.

RequestFactory puede configurarse antes de llamar a fromGlobals():

  • mediante el método $factory->setBinary() se puede desactivar la limpieza automática de los parámetros de entrada de caracteres de control y secuencias UTF-8 no válidas.
  • mediante el método $factory->setProxy(...) se especifica la dirección IP del servidor proxy, necesaria para la correcta detección de la dirección IP del usuario.

RequestFactory permite definir filtros que transforman automáticamente partes de la petición URL. Estos filtros eliminan de las URL caracteres no deseados que pueden haber sido insertados, por ejemplo, por una incorrecta implementación de los sistemas de comentarios en diversos sitios web:

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

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

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

La primera clave 'path' o 'url' determina a qué parte de la URL se aplicará el filtro. La segunda clave es una expresión regular que se buscará, y el valor es el reemplazo que se utilizará en lugar del texto encontrado.

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.

  1. Documentación
  2. Nette HTTP
  3. Solicitud HTTP
versión: 4.0