Solicitação HTTP
****************

.[perex]
Nette encapsula a solicitação HTTP em objetos com uma API compreensível enquanto fornece um filtro de higienização.

Um pedido HTTP é um objeto [api:Nette\Http\Request], que você recebe passando-o usando a [injeção de dependência |dependency-injection:passing-dependencies]. Nos apresentadores, basta ligar para `$httpRequest = $this->getHttpRequest()`.

O importante é que Nette, ao [criar |#RequestFactory] este objeto, limpa todos os parâmetros de entrada GET, POST e COOKIE, assim como URLs de caracteres de controle e seqüências UTF-8 inválidas. Assim, você pode continuar trabalhando com os dados com segurança. Os dados limpos são então utilizados em apresentadores e formulários.

→ [Instalação e requisitos |@home#Installation]


Nette\Http Solicitação .[#toc-nette-http-request]
=================================================

Este objeto é imutável. Não tem setters, tem apenas um chamado wither `withUrl()`, que não muda o objeto, mas retorna uma nova instância com um valor modificado.


withUrl(Nette\Http\UrlScript $url): Nette\Http\Request .[method]
----------------------------------------------------------------
Devolve um clone com uma URL diferente.


getUrl(): Nette\Http\UrlScript .[method]
----------------------------------------
Retorna o URL do pedido como [UrlScript |urls#UrlScript] do objeto.

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

Aviso: Os navegadores não enviam um fragmento ao servidor, portanto, o site `$url->getFragment()` retornará uma cadeia de caracteres vazia.


getQuery(?string $key=null): string|array|null .[method]
--------------------------------------------------------
Retorna os parâmetros de solicitação GET:

```php
$all = $httpRequest->getQuery(); // matriz de todos os parâmetros de URL
$id = $httpRequest->getQuery('id'); // retorna o parâmetro GET 'id' (ou nulo)
```


getPost(?string $key=null): string|array|null .[method]
-------------------------------------------------------
Retorna os parâmetros de solicitação de PÓS-PST:

```php
$all = $httpRequest->getPost(); // matriz de todos os parâmetros POST
$id = $httpRequest->getPost('id'); // devolve o parâmetro 'id' do POST (ou nulo)
```


getFile(string|string[] $key): Nette\Http\FileUpload|array|null .[method]
-------------------------------------------------------------------------
Devolve o [upload |#Uploaded Files] como objeto [api:Nette\Http\FileUpload]:

```php
$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // foi feito o upload de algum arquivo?
	$file->getUntrustedName(); // nome do arquivo enviado pelo usuário
	$file->getSanitizedName(); // o nome sem caracteres perigosos
}
```

Especifique um conjunto de chaves para acessar a estrutura da sub-árvore.

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

Como você não pode confiar nos dados do exterior e, portanto, não confia na forma da estrutura, este método é mais seguro do que `$request->getFiles()['my-form']['details']['avatar']`o que pode falhar.


getFiles(): array .[method]
---------------------------
Retorna árvore de [arquivos de upload |#Uploaded Files] em uma estrutura normalizada, com cada folha uma instância de [api:Nette\Http\FileUpload]:

```php
$files = $httpRequest->getFiles();
```


getCookie(string $key): string|array|null .[method]
---------------------------------------------------
Devolve um cookie ou `null` se ele não existir.

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


getCookies(): array .[method]
-----------------------------
Devolve todos os cookies:

```php
$cookies = $httpRequest->getCookies();
```


getMethod(): string .[method]
-----------------------------
Retorna o método HTTP com o qual a solicitação foi feita.

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


isMethod(string $method): bool .[method]
----------------------------------------
Verifica o método HTTP com o qual a solicitação foi feita. O parâmetro não diferencia maiúsculas e minúsculas de minúsculas.

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


getHeader(string $header): ?string .[method]
--------------------------------------------
Devolve um cabeçalho HTTP ou `null` se ele não existir. O parâmetro não diferencia maiúsculas e minúsculas de minúsculas:

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


getHeaders(): array .[method]
-----------------------------
Devolve todos os cabeçalhos HTTP como matriz associativa:

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


isSecured(): bool .[method]
---------------------------
A conexão é criptografada (HTTPS)? Talvez seja necessário [configurar um proxy |configuration#HTTP proxy] para uma funcionalidade adequada.


isSameSite(): bool .[method]
----------------------------
A solicitação vem do mesmo (sub) domínio e é iniciada clicando em um link? Nette utiliza o cookie `_nss` (anteriormente `nette-samesite`) para detectá-lo.


isAjax(): bool .[method]
------------------------
Trata-se de um pedido AJAX?


getRemoteAddress(): ?string .[method]
-------------------------------------
Devolve o endereço IP do usuário. Pode ser necessário [configurar um proxy |configuration#HTTP proxy] para uma funcionalidade adequada.


getRemoteHost(): ?string .[method deprecated]
---------------------------------------------
Retorna a tradução DNS do endereço IP do usuário. Pode ser necessário [configurar um proxy |configuration#HTTP proxy] para uma funcionalidade adequada.


getBasicCredentials(): ?string .[method]
----------------------------------------
Retorna as credenciais [básicas de autenticação HTTP |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication].

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


getRawBody(): ?string .[method]
-------------------------------
Devolve o corpo do pedido HTTP:

```php
$body = $httpRequest->getRawBody();
```


detectLanguage(array $langs): ?string .[method]
-----------------------------------------------
Detecta a linguagem. Como parâmetro `$lang`, passamos um conjunto de idiomas que o aplicativo suporta, e ele retorna o preferido pelo navegador. Não é mágico, o método utiliza apenas o cabeçalho `Accept-Language`. Se não for alcançado, ele retorna `null`.

```php
// Cabeçalho enviado pelo navegador: Aceitar-Língua: cs,en-us;q=0,8,en;q=0,5,sl;q=0,3

$langs = ['hu', 'pl', 'en']; // idiomas suportados na aplicação
echo $httpRequest->detectLanguage($langs); // pt
```


RequestFactory .[#toc-requestfactory]
=====================================

O objeto da solicitação HTTP atual é criado por [api:Nette\Http\RequestFactory]. Se você está escrevendo um pedido que não utiliza um recipiente DI, você cria um pedido da seguinte forma:

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

RequestFactory pode ser configurado antes de ligar para `fromGlobals()`. Podemos desativar toda a higienização dos parâmetros de entrada das seqüências UTF-8 inválidas usando `$factory->setBinary()`. E também configurar um servidor proxy, o que é importante para a detecção correta do endereço IP do usuário usando `$factory->setProxy(...)`.

É possível limpar URLs de caracteres que podem entrar neles devido a sistemas de comentários mal implementados em vários outros sites, utilizando filtros:

```php
// remover espaços do caminho
$requestFactory->urlFilters['path']['%20'] = '';

// remover ponto, vírgula ou parêntese direita do final da URL
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// limpar o caminho a partir de cortes duplicados (filtro padrão)
$requestFactory->urlFilters['path']['/{2,}'] = '/';
```


Arquivos carregados .[#toc-uploaded-files]
==========================================

Método `Nette\Http\Request::getFiles()` devolve uma árvore de arquivos de upload em uma estrutura normalizada, com cada folha uma instância de [api:Nette\Http\FileUpload]. Estes objetos encapsulam os dados enviados pelo `<input type=file>` elemento forma.

A estrutura reflete a nomenclatura dos elementos em HTML. No exemplo mais simples, este pode ser um único elemento de formulário nomeado apresentado como:

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

Neste caso, o `$request->getFiles()` retorna a matriz:

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

O objeto `FileUpload` é criado mesmo que o usuário não tenha carregado nenhum arquivo ou que o carregamento tenha falhado. O método `hasFile()` retorna verdadeiro se um arquivo tiver sido enviado:

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

No caso de uma entrada usando notação de array para o nome:

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

árvore devolvida acaba ficando com este aspecto:

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

Você também pode criar matrizes de arquivos:

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

Em tal caso, a estrutura parece ser a mesma:

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

A melhor maneira de acessar o índice 1 de uma matriz aninhada é a seguinte:

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

Como você não pode confiar nos dados do exterior e, portanto, não confia na forma da estrutura, este método é mais seguro do que `$request->getFiles()['my-form']['details']['avatars'][1]`o que pode falhar.


Visão geral de `FileUpload` Métodos .{toc: FileUpload}
------------------------------------------------------


hasFile(): bool .[method]
-------------------------
Retorna `true` se o usuário tiver feito o upload de um arquivo.


isOk(): bool .[method]
----------------------
Retorna `true` se o arquivo foi carregado com sucesso.


getError(): int .[method]
-------------------------
Devolve o código de erro associado com o arquivo carregado. É uma das constantes do [UPLOAD_ERR_XXX |http://php.net/manual/en/features.file-upload.errors.php]. Se o arquivo foi carregado com sucesso, ele retorna `UPLOAD_ERR_OK`.


move(string $dest) .[method]
----------------------------
Move um arquivo carregado para um novo local. Se o arquivo de destino já existir, ele será sobregravado.

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


getContents(): ?string .[method]
--------------------------------
Devolve o conteúdo do arquivo carregado. Se o upload não foi bem sucedido, ele retorna `null`.


getContentType(): ?string .[method]
-----------------------------------
Detecta o tipo de conteúdo MIME do arquivo carregado com base em sua assinatura. Se o upload não foi bem sucedido ou a detecção falhou, ele retorna `null`.

.[caution]
Requer extensão PHP `fileinfo`.


getUntrustedName(): string .[method]
------------------------------------
Devolve o nome original do arquivo, conforme apresentado pelo navegador.

.[caution]
Não confie no valor retornado por este método. Um cliente pode enviar um nome de arquivo malicioso com a intenção de corromper ou invadir sua aplicação.


getSanitizedName(): string .[method]
------------------------------------
Devolve o nome do arquivo higienizado. Contém apenas caracteres ASCII `[a-zA-Z0-9.-]`. Se o nome não contiver tais caracteres, ele retorna "desconhecido". Se o arquivo for JPEG, PNG, GIF, ou imagem WebP, ele retorna a extensão correta do arquivo.

.[caution]
Requer a extensão PHP `fileinfo`.


getSuggestedExtension(): ?string .[method]{data-version:3.2.4}
--------------------------------------------------------------
Retorna a extensão de arquivo apropriada (sem o ponto) correspondente ao tipo MIME detectado.

.[caution]
Requer a extensão PHP `fileinfo`.


getUntrustedFullPath(): string .[method]
----------------------------------------
Retorna o caminho completo original, conforme apresentado pelo navegador durante o upload do diretório. O caminho completo só está disponível no PHP 8.1 e superior. Nas versões anteriores, este método retorna o nome do arquivo não confiável.

.[caution]
Não confie no valor retornado por este método. Um cliente pode enviar um nome de arquivo malicioso com a intenção de corromper ou invadir sua aplicação.


getSize(): int .[method]
------------------------
Devolve o tamanho do arquivo carregado. Se o upload não foi bem sucedido, ele retorna `0`.


getTemporaryFile(): string .[method]
------------------------------------
Retorna o caminho da localização temporária do arquivo carregado. Se o upload não foi bem sucedido, ele retorna `''`.


isImage(): bool .[method]
-------------------------
Retorna `true` se o arquivo carregado for uma imagem JPEG, PNG, GIF, ou WebP. A detecção é baseada em sua assinatura. A integridade do arquivo inteiro não é verificada. Você pode descobrir se uma imagem não está corrompida, por exemplo, ao tentar [carregá-la |#toImage].

.[caution]
Requer extensão PHP `fileinfo`.


getImageSize(): ?array .[method]
--------------------------------
Devolve um par de `[width, height]` com as dimensões da imagem carregada. Se o upload não foi bem sucedido ou não é uma imagem válida, ele retorna `null`.


toImage(): Nette\Utils\Image .[method]
--------------------------------------
Carrega uma imagem como um objeto de [imagem |utils:images]. Se o upload não foi bem sucedido ou não é uma imagem válida, ele lança uma exceção `Nette\Utils\ImageException`.