Solicitação HTTP

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 Nette\Http\Request, que você recebe passando-o usando a injeção de dependência. Nos apresentadores, basta ligar para $httpRequest = $this->getHttpRequest().

O importante é que Nette, ao criar 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

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

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

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

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

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