HTTP リクエスト

Nette は HTTP リクエストを分かりやすい API を持つオブジェクトにカプセル化し、同時にサニタイズフィルタを提供します。

HTTP リクエストは Nette\Http\Request オブジェクトによって表されます。Nette を使用している場合、このオブジェクトはフレームワークによって自動的に作成され、依存性注入を使用して渡すことができます。Presenter では、単に $this->getHttpRequest() メソッドを呼び出すだけです。Nette Framework の外部で作業している場合は、RequestFactory を使用してオブジェクトを作成できます。

Nette の大きな利点は、オブジェクトを作成する際に、すべての入力パラメータ GET、POST、COOKIE、および URL から制御文字と無効な UTF-8 シーケンスを自動的にクリーンアップすることです。その後、これらのデータを安全にさらに処理できます。クリーンアップされたデータは、Presenter とフォームで使用されます。

→ インストールと要件

Nette\Http\Request

このオブジェクトはイミュータブル（不変）です。セッターはなく、withUrl() というウィザーが 1 つだけあり、これはオブジェクトを変更せず、変更された値を持つ新しいインスタンスを返します。

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

異なる URL を持つクローンを返します。

getUrl(): Nette\Http\UrlScript

リクエストの URL を UrlScript オブジェクトとして返します。

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

注意：ブラウザはサーバーにフラグメントを送信しないため、$url->getFragment() は空の文字列を返します。

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

GET リクエストのパラメータを返します。

$all = $httpRequest->getQuery(); // URL からのすべてのパラメータの配列を返します
$id = $httpRequest->getQuery('id'); // GET パラメータ 'id' を返します（または null）

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

POST リクエストのパラメータを返します。

$all = $httpRequest->getPost(); // POST からのすべてのパラメータの配列を返します
$id = $httpRequest->getPost('id'); // POST パラメータ 'id' を返します（または null）

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

アップロードを Nette\Http\FileUpload オブジェクトとして返します：

$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // 何かファイルがアップロードされましたか？
	$file->getUntrustedName(); // ユーザーによって送信されたファイル名
	$file->getSanitizedName(); // 危険な文字を含まない名前
}

ネストされた構造にアクセスするには、キーの配列を指定します。

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

外部からのデータを信頼できず、したがってファイル構造の形式に依存できないため、例えば $request->getFiles()['my-form']['details']['avatar'] のように失敗する可能性がある方法よりも、この方法の方が安全です。

getFiles(): array

正規化された構造ですべてのアップロードのツリーを返します。そのリーフは Nette\Http\FileUpload オブジェクトです：

$files = $httpRequest->getFiles();

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

クッキーを返すか、存在しない場合は null を返します。

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

getCookies(): array

すべてのクッキーを返します。

$cookies = $httpRequest->getCookies();

getMethod(): string

リクエストが行われた HTTP メソッドを返します。

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

isMethod (string $method): bool

リクエストが行われた HTTP メソッドをテストします。パラメータは大文字と小文字を区別しません。

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

getHeader (string $header): ?string

HTTP ヘッダーを返すか、存在しない場合は null を返します。パラメータは大文字と小文字を区別しません。

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

getHeaders(): array

すべての HTTP ヘッダーを連想配列として返します。

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

isSecured(): bool

接続は暗号化されていますか（HTTPS）？正しく機能させるためには、プロキシの設定が必要になる場合があります。

isSameSite(): bool

リクエストは同じ（サブ）ドメインから来ており、リンクのクリックによって開始されましたか？Nette は検出にクッキー _nss（以前は nette-samesite）を使用します。

isAjax(): bool

AJAX リクエストですか？

getRemoteAddress(): ?string

ユーザーの IP アドレスを返します。正しく機能させるためには、プロキシの設定が必要になる場合があります。

getRemoteHost(): ?string

ユーザーの IP アドレスの DNS 解決を返します。正しく機能させるためには、プロキシの設定が必要になる場合があります。

getBasicCredentials(): ?string

Basic HTTP authentication の認証情報を返します。

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

getRawBody(): ?string

HTTP リクエストの本文を返します。

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

言語を検出します。パラメータ $lang として、アプリケーションがサポートする言語の配列を渡し、訪問者のブラウザが最も好む言語を返します。これは魔法ではなく、単に Accept-Language ヘッダーを使用します。一致するものがない場合は null を返します。

// ブラウザは例えば Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3 を送信します

$langs = ['hu', 'pl', 'en']; // アプリケーションがサポートする言語
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Nette\Http\RequestFactory クラスは、現在の HTTP リクエストを表す Nette\Http\Request インスタンスを作成するために使用されます。（Nette を使用している場合、HTTP リクエストオブジェクトはフレームワークによって自動的に作成されます。）

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

fromGlobals() メソッドは、現在の PHP グローバル変数（$_GET、$_POST、$_COOKIE、$_FILES、$_SERVER）に基づいてリクエストオブジェクトを作成します。オブジェクトを作成する際に、すべての入力パラメータ GET、POST、COOKIE、および URL から制御文字と無効な UTF-8 シーケンスを自動的にクリーンアップし、これらのデータをさらに処理する際の安全性を確保します。

RequestFactory は fromGlobals() を呼び出す前に設定できます：

$factory->setBinary() メソッドで、入力パラメータから制御文字と無効な UTF-8 シーケンスの自動クリーニングを無効にします。
$factory->setProxy(...) メソッドで、プロキシサーバーの IP アドレスを指定します。これは、ユーザーの IP アドレスを正しく検出するために必要です。

RequestFactory を使用すると、リクエスト URL の一部を自動的に変換するフィルタを定義できます。これらのフィルタは、例えば、さまざまなウェブサイト上のコメントシステムの不適切な実装によって挿入される可能性のある、URL からの不要な文字を削除します：

// パスからスペースを削除
$requestFactory->urlFilters['path']['%20'] = '';

// URI の末尾からドット、カンマ、または右括弧を削除
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// パスから重複したスラッシュをクリーンアップ（デフォルトフィルタ）
$requestFactory->urlFilters['path']['/{2,}'] = '/';

最初のキー 'path' または 'url' は、フィルタが適用される URL の部分を指定します。2番目のキーは検索する正規表現であり、値は見つかったテキストの代わりに使用される置換です。

アップロードされたファイル

Nette\Http\Request::getFiles() メソッドは、正規化された構造ですべてのアップロードの配列を返します。そのリーフは Nette\Http\FileUpload オブジェクトです。これらは、フォーム要素 <input type=file> によって送信されたデータをカプセル化します。

構造は HTML の要素の命名を反映しています。最も単純なケースでは、次のように送信された単一の名前付きフォーム要素である可能性があります：

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

この場合、$request->getFiles() は配列を返します：

[
	'avatar' => /* FileUpload インスタンス */
]

FileUpload オブジェクトは、ユーザーがファイルを送信しなかった場合や送信が失敗した場合でも作成されます。ファイルが送信されたかどうかは hasFile() メソッドが返します：

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

配列表記を使用する要素名の場合：

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

返されるツリーは次のようになります：

[
	'my-form' => [
		'details' => [
			'avatar' => /* FileUpload インスタンス */
		],
	],
]

ファイルの配列を作成することもできます：

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

この場合、構造は次のようになります：

[
	'my-form' => [
		'details' => [
			'avatars' => [
				0 => /* FileUpload インスタンス */,
				1 => /* FileUpload インスタンス */,
				2 => /* FileUpload インスタンス */,
			],
		],
	],
]

ネストされた配列のインデックス 1 にアクセスする最良の方法は次のとおりです：

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

外部からのデータを信頼できず、したがってファイル構造の形式に依存できないため、例えば $request->getFiles()['my-form']['details']['avatars'][1] のように失敗する可能性がある方法よりも、この方法の方が安全です。

`FileUpload` メソッドの概要

hasFile(): bool

ユーザーがファイルをアップロードした場合に true を返します。

isOk(): bool

ファイルが正常にアップロードされた場合に true を返します。

getError(): int

ファイルアップロード時のエラーコードを返します。これは UPLOAD_ERR_XXX 定数の 1 つです。アップロードが正常に行われた場合、UPLOAD_ERR_OK を返します。

move (string $dest)

アップロードされたファイルを新しい場所に移動します。宛先ファイルが既に存在する場合、上書きされます。

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

getContents(): ?string

アップロードされたファイルの内容を返します。アップロードが成功しなかった場合、null を返します。

getContentType(): ?string

アップロードされたファイルの MIME コンテンツタイプを、その署名に基づいて検出します。アップロードが成功しなかった場合、または検出が失敗した場合、null を返します。

PHP 拡張機能 fileinfo が必要です。

getUntrustedName(): string

ブラウザが送信した元のファイル名を返します。

このメソッドによって返される値を信頼しないでください。クライアントは、アプリケーションを破損またはハッキングする意図で悪意のあるファイル名を送信した可能性があります。

getSanitizedName(): string

サニタイズされたファイル名を返します。ASCII 文字 [a-zA-Z0-9.-] のみを含みます。名前にそのような文字が含まれていない場合、'unknown' を返します。ファイルが JPEG、PNG、GIF、WebP、または AVIF 形式の画像である場合、正しい拡張子も返します。

PHP 拡張機能 fileinfo が必要です。

getSuggestedExtension(): ?string

検出された MIME タイプに対応する適切なファイル拡張子（ドットなし）を返します。

PHP 拡張機能 fileinfo が必要です。

getUntrustedFullPath(): string

フォルダのアップロード時にブラウザが送信した元のファイルパスを返します。完全なパスは PHP 8.1 以降でのみ利用可能です。以前のバージョンでは、このメソッドは元のファイル名を返します。

getSize(): int

アップロードされたファイルのサイズを返します。アップロードが成功しなかった場合、0 を返します。

getTemporaryFile(): string

アップロードされたファイルの一時的な場所へのパスを返します。アップロードが成功しなかった場合、'' を返します。

isImage(): bool

アップロードされたファイルが JPEG、PNG、GIF、WebP、または AVIF 形式の画像である場合に true を返します。検出はその署名に基づいて行われ、ファイル全体の整合性は検証されません。画像が破損していないかどうかは、例えば読み込みを試みることで確認できます。

PHP 拡張機能 fileinfo が必要です。

getImageSize(): ?array

アップロードされた画像の寸法を含むペア [幅, 高さ] を返します。アップロードが成功しなかった場合、または有効な画像でない場合、null を返します。

toImage(): Nette\Utils\Image

画像を Image オブジェクトとして読み込みます。アップロードが成功しなかった場合、または有効な画像でない場合、Nette\Utils\ImageException 例外をスローします。

HTTP リクエスト

Nette\Http\Request

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

アップロードされたファイル

FileUpload メソッドの概要

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

`FileUpload` メソッドの概要