Solicitação HTTP

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

A solicitação HTTP é representada pelo objeto Nette\Http\Request. Se você trabalha com o Nette, esse objeto é criado automaticamente pela estrutura e pode ser passado a você por meio de injeção de dependência. Nos apresentadores, você só precisa chamar o método $this->getHttpRequest(). Se você trabalha fora da Nette Framework, pode criar o objeto usando RequestFactory.

Uma das principais vantagens do Nette é que, ao criar o objeto, ele higieniza automaticamente todos os parâmetros de entrada GET, POST, COOKIE, bem como o URL de caracteres de controle e sequências UTF-8 inválidas. Assim, você pode trabalhar com segurança com esses dados. Os dados higienizados são usados posteriormente em apresentadores e formulários.

→ Instalação e requisitos

Nette\Http Solicitação

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

Devolve um clone com uma URL diferente.

getUrl(): Nette\Http\UrlScript

Retorna o URL do pedido como UrlScript do objeto.

$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

Retorna os parâmetros de solicitação GET:

$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

Retorna os parâmetros de solicitação de PÓS-PST:

$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

Devolve o upload como objeto Nette\Http\FileUpload:

$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.

//<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

Retorna árvore de arquivos de upload em uma estrutura normalizada, com cada folha uma instância de Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Devolve um cookie ou null se ele não existir.

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

getCookies(): array

Devolve todos os cookies:

$cookies = $httpRequest->getCookies();

getMethod(): string

Retorna o método HTTP com o qual a solicitação foi feita.

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

isMethod (string $method): bool

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.

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

getHeader (string $header): ?string

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:

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

getHeaders(): array

Devolve todos os cabeçalhos HTTP como matriz associativa:

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

isSecured(): bool

A conexão é criptografada (HTTPS)? Talvez seja necessário configurar um proxy para uma funcionalidade adequada.

isSameSite(): bool

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

Trata-se de um pedido AJAX?

getRemoteAddress(): ?string

Devolve o endereço IP do usuário. Pode ser necessário configurar um proxy para uma funcionalidade adequada.

getRemoteHost(): ?string

Retorna a tradução DNS do endereço IP do usuário. Pode ser necessário configurar um proxy para uma funcionalidade adequada.

getBasicCredentials(): ?string

Retorna as credenciais básicas de autenticação HTTP.

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

getRawBody(): ?string

Devolve o corpo do pedido HTTP:

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

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.

// 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

A classe Nette\Http\RequestFactory é usada para criar uma instância de Nette\Http\Request, que representa a solicitação HTTP atual. (Se você trabalha com o Nette, o objeto de solicitação HTTP é criado automaticamente pela estrutura).

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

O método fromGlobals() cria um objeto de solicitação com base nas variáveis globais atuais do PHP ($_GET, $_POST, $_COOKIE, $_FILES e $_SERVER). Ao criar o objeto, ele limpa automaticamente todos os parâmetros de entrada GET, POST, COOKIE, bem como o URL de caracteres de controle e sequências UTF-8 inválidas, o que garante a segurança ao trabalhar com esses dados posteriormente.

O RequestFactory pode ser configurado antes de chamar fromGlobals():

usando o método $factory->setBinary(), você pode desativar a limpeza automática dos parâmetros de entrada dos caracteres de controle e das sequências UTF-8 inválidas.
usando o método $factory->setProxy(...), você especifica o endereço IP do servidor proxy, que é necessário para a detecção correta do endereço IP do usuário.

O RequestFactory permite que você defina filtros que transformam automaticamente partes da solicitação de URL. Esses filtros removem caracteres indesejados de URLs que podem ter sido inseridos, por exemplo, pela implementação incorreta de sistemas de comentários em vários sites:

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

// remoção de um ponto, vírgula ou parêntese à direita do final do URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// limpar o caminho de barras duplas (filtro padrão)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

A primeira chave 'path' ou 'url' determina a qual parte do URL o filtro será aplicado. A segunda chave é uma expressão regular a ser pesquisada e o valor é a substituição a ser usada no lugar do texto encontrado.

Arquivos carregados

Método Nette\Http\Request::getFiles() devolve uma árvore de arquivos de upload em uma estrutura normalizada, com cada folha uma instância de 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:

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

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

[
	'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:

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

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

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

árvore devolvida acaba ficando com este aspecto:

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

Você também pode criar matrizes de arquivos:

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

Em tal caso, a estrutura parece ser a mesma:

[
	'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:

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

Visão geral de `FileUpload` Métodos

hasFile(): bool

Retorna true se o usuário tiver feito o upload de um arquivo.

isOk(): bool

Retorna true se o arquivo foi carregado com sucesso.

getError(): int

Devolve o código de erro associado com o arquivo carregado. É uma das constantes do UPLOAD_ERR_XXX. Se o arquivo foi carregado com sucesso, ele retorna UPLOAD_ERR_OK.

move (string $dest)

Move um arquivo carregado para um novo local. Se o arquivo de destino já existir, ele será sobregravado.

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

getContents(): ?string

Devolve o conteúdo do arquivo carregado. Se o upload não foi bem sucedido, ele retorna null.

getContentType(): ?string

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.

Requer extensão PHP fileinfo.

getUntrustedName(): string

Devolve o nome original do arquivo, conforme apresentado pelo navegador.

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

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.

Requer a extensão PHP fileinfo.

getSuggestedExtension(): ?string

Retorna a extensão de arquivo apropriada (sem o ponto) correspondente ao tipo MIME detectado.

Requer a extensão PHP fileinfo.

getUntrustedFullPath(): string

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.

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

Devolve o tamanho do arquivo carregado. Se o upload não foi bem sucedido, ele retorna 0.

getTemporaryFile(): string

Retorna o caminho da localização temporária do arquivo carregado. Se o upload não foi bem sucedido, ele retorna ''.

isImage(): bool

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.

Requer extensão PHP fileinfo.

getImageSize(): ?array

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

Carrega uma imagem como um objeto de imagem. Se o upload não foi bem sucedido ou não é uma imagem válida, ele lança uma exceção Nette\Utils\ImageException.

Solicitação HTTP

Nette\Http Solicitação

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

getUrl(): Nette\Http\UrlScript

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

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

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

getFiles(): array

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

getCookies(): array

getMethod(): string

isMethod (string $method): bool

getHeader (string $header): ?string

getHeaders(): array

isSecured(): bool

isSameSite(): bool

isAjax(): bool

getRemoteAddress(): ?string

getRemoteHost(): ?string

getBasicCredentials(): ?string

getRawBody(): ?string

detectLanguage (array $langs): ?string

RequestFactory

Arquivos carregados

Visão geral de FileUpload Métodos

hasFile(): bool

isOk(): bool

getError(): int

move (string $dest)

getContents(): ?string

getContentType(): ?string

getUntrustedName(): string

getSanitizedName(): string

getSuggestedExtension(): ?string

getUntrustedFullPath(): string

getSize(): int

getTemporaryFile(): string

isImage(): bool

getImageSize(): ?array

toImage(): Nette\Utils\Image

Visão geral de `FileUpload` Métodos