PHP アップロードのサイズと MIME タイプのフィルタリング
photo.png という名前のアップロードでも、中身はプレーンテキストかもしれません。ブラウザーが送信するコンテンツタイプも、内容を保証するものではありません。受信したバイト列を調べ、指定した種類とサイズ範囲のファイルだけを受け入れ、ウェブルートの外に保存する PHP エンドポイントを作成します。受け入れルールには Respect\Validation を使い、HTML フィールドのサニタイズには、それとは別の処理として HTML Purifier を使います。
アップロードルールの選択
このローカル環境の例では、空でない JPEG、PNG、GIF のアップロードを
5 MiB(5 * 1024 * 1024 = 5242880 バイト)まで受け入れます。PHP の Fileinfo 拡張機能が、一時ファイルから
MIME タイプを検出します。ハンドラーはそのファイルのバイト数を測定し、元のファイル名と multipart のコンテンツタイプは無視して、独自に拡張子を選択します。HTTP 201 を返すのは、ファイルを保存した後だけです。
これらは受け入れ可否の検証です。画像のデコード、埋め込みコンテンツの除去、マルウェアの検出は行いません。破損した画像や余分なデータを含むファイルでも、MIME ルールに一致する場合があります。アプリケーションで必要なデコードやセキュリティスキャンが成功するまで、受け入れたバイト列は非公開にしてください。
PHP のアップロードサイズガイドでは、有効な php.ini の探し方とリクエスト制限の診断方法を説明しています。ここでは受け入れ判定を確認できるよう、PHP の制限をアプリケーションの上限よりも意図的に高く設定します。
ローカルプロジェクトのセットアップ
64 ビット Linux 上の Bash、Fileinfo、DOM、mbstring を有効にした PHP 8.5、Composer 2.11.1、cURL を使用します。PHP 8.5.12 以降のメンテナンス対象パッチ、または PHP の 2026年10月21日のセキュリティ勧告にある修正と同等の修正を含むベンダーパッケージを使用してください。アプリケーションレベルのアップロード検証は、これらのランタイム修正の代わりにはなりません。
PHP の別の10月23日のセッションに関する勧告は、アプリケーションが session.serialize_handler を
php_binary または php_serialize に設定し、session_start() より前に ini_set() で
php に切り替え、セッションのアップロード進捗機能を有効なままにしている場合に適用されます。この設定では、修正が利用可能になるまで、リクエストの解析前に session.upload_progress.enabled を無効にしてください。この例ではセッションのシリアライズ方式は変更しません。
以下の例は PHP 8.5.12、Composer 2.11.1、Respect\Validation 3.1.2、HTML Purifier 4.19.1 でテストしています。Respect のバージョン 3 移行ノートでは、Validator、max()、または真偽値の validate() 結果を使う古い例に、更新が必要な理由を説明しています。
新規プロジェクトを作成できるディレクトリから、このブロックを実行してください。php-filter-demo ディレクトリがすでにある場合は実行を拒否します。サブシェルを使うため、インストールに失敗した場合も、ターミナルの作業ディレクトリは元の場所のままです。コマンドでは新しいマニフェストとローカルの依存関係パスを明示的に選択するため、親階層の Composer プロジェクトや、継承したパスの上書き設定の参照先にインストールされることはありません。
(
set -eu
mkdir php-filter-demo
cd php-filter-demo
printf '%s\n' '{"require": {}}' > composer.json
COMPOSER=./composer.json COMPOSER_VENDOR_DIR=vendor COMPOSER_BIN_DIR=vendor/bin \
composer require --no-interaction --no-plugins --no-scripts \
respect/validation:^3.1 ezyang/htmlpurifier:^4.19
mkdir public private cache
chmod 700 private cache
)
セットアップが成功してから先に進んでください。以降のコマンドも、同じ親ディレクトリから実行します。PHP ファイルは以下に示すパスに保存してください。公開ディレクトリは
php-filter-demo/public とし、依存関係、キャッシュされた HTML 定義、アップロードはすべてその外に置きます。
アップロードハンドラーの保存
このプログラム全体を php-filter-demo/public/upload.php として保存してください。PHP は multipart リクエストを受信すると $_FILES に値を設定します。コマンドラインスクリプトで作った配列では、is_uploaded_file()の条件を満たしません。
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/vendor/autoload.php';
use Respect\Validation\ValidatorBuilder as v;
const MAX_BYTES = 5 * 1024 * 1024;
header('Content-Type: application/json');
function rejectUpload(int $status, string $code, string $message): never {
http_response_code($status);
echo json_encode(['accepted' => false, 'code' => $code, 'message' => $message], JSON_THROW_ON_ERROR);
exit;
}
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
header('Allow: POST');
rejectUpload(405, 'method', 'Send one file in a multipart POST request.');
}
$postLimit = ini_parse_quantity(ini_get('post_max_size'));
$contentLength = $_SERVER['CONTENT_LENGTH'] ?? null;
if ($postLimit > 0 && $contentLength !== null && (int) $contentLength > $postLimit) {
rejectUpload(413, 'request_size', 'The complete request exceeds PHP post_max_size.');
}
$file = $_FILES['upload'] ?? null;
if (array_keys($_FILES) !== ['upload'] || !is_array($file)
|| !is_int($file['error'] ?? null) || !is_string($file['tmp_name'] ?? null)) {
rejectUpload(400, 'missing_upload', 'Send one file in the upload field, without array brackets.');
}
if ($file['error'] !== UPLOAD_ERR_OK) {
[$status, $code, $message] = match ($file['error']) {
UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE => [413, 'upload_size', 'PHP rejected the file size.'],
UPLOAD_ERR_NO_FILE => [400, 'missing_upload', 'Choose a file to upload.'],
UPLOAD_ERR_PARTIAL => [400, 'partial_upload', 'The file arrived incomplete. Retry the upload.'],
default => [500, 'upload_unavailable', 'The upload service is unavailable.'],
};
rejectUpload($status, $code, $message);
}
if (!is_uploaded_file($file['tmp_name'])) {
rejectUpload(400, 'invalid_upload', 'The file is not a valid HTTP upload.');
}
$directory = null;
$destination = null;
try {
$size = filesize($file['tmp_name']);
if ($size === false) {
throw new RuntimeException('Cannot measure upload');
}
if ($size === 0) {
rejectUpload(400, 'empty_upload', 'The file is empty.');
}
if (!v::intType()->between(1, MAX_BYTES)->isValid($size)) {
rejectUpload(413, 'file_size', 'The file exceeds the 5 MiB application limit.');
}
$extensions = ['image/jpeg' => 'jpg', 'image/png' => 'png', 'image/gif' => 'gif'];
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
if (!v::in(array_keys($extensions))->isValid($mime)) {
rejectUpload(415, 'file_type', 'The detected type must be JPEG, PNG, or GIF.');
}
$hash = hash_file('sha256', $file['tmp_name']);
if ($hash === false) {
throw new RuntimeException('Cannot hash upload');
}
$id = bin2hex(random_bytes(16));
$candidate = dirname(__DIR__) . '/private/' . $id;
// Reserve a fresh directory so an existing upload cannot be replaced.
if (!@mkdir($candidate, 0700)) {
throw new RuntimeException('Cannot reserve storage');
}
$directory = $candidate;
$destination = $directory . '/file.' . $extensions[$mime];
if (!@move_uploaded_file($file['tmp_name'], $destination) || !@chmod($destination, 0600)) {
throw new RuntimeException('Cannot store upload');
}
http_response_code(201);
echo json_encode([
'accepted' => true,
'id' => $id,
'mime' => $mime,
'bytes' => $size,
'sha256' => $hash,
], JSON_THROW_ON_ERROR);
} catch (Throwable $error) {
if ($destination !== null) {
@unlink($destination);
}
if ($directory !== null) {
@rmdir($directory);
}
error_log('Upload storage failed: ' . get_class($error));
rejectUpload(500, 'upload_unavailable', 'The upload service is unavailable.');
}
between() ルールでは、ちょうど 5 MiB のファイルも受け入れます。MIME 許可リストは multipart ヘッダーではなく、Fileinfo の結果を使います。PHP のアップロードエラーコードは、アプリケーションの検証とは別に文書化されています。
受け入れたリクエストには、バイト列が同一でも毎回新しい ID を割り当てます。その ID の確保に失敗すると、ハンドラーは 500 を返し、既存のディレクトリは変更しません。これは、move_uploaded_file() が既存の保存先を上書きするために重要です。保存に成功したファイルは private/<id>/file.<extension> 配下に残ります。ファイルのモードは 0600、格納先ディレクトリのモードは
0700 です。元のファイル名を保存パスに使うことはありません。
サーバーの起動と実ファイルの送信
使用可能なローカルポートを選んでください。8787 が使用中なら、サーバーのコマンドと両方のリクエストで変更します。PHP の開発サーバーを起動してください。
php -d file_uploads=1 -d upload_max_filesize=6M -d post_max_size=7M \
-d display_errors=0 -d log_errors=1 \
-S 127.0.0.1:8787 -t php-filter-demo/public
このターミナルは実行したままにします。別のターミナルで、同じ親ディレクトリを開いてください。以下を php-filter-demo/make-sample.php として保存します。これは小さな PNG を作成し、sample.png がすでにある場合は置き換えを拒否します。
<?php
declare(strict_types=1);
$png = base64_decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAACklEQVQI12NoAAAAggCB3UNq9AAAAABJRU5ErkJggg==', true);
$output = @fopen(__DIR__ . '/sample.png', 'xb');
if ($output === false) {
fwrite(STDERR, "Cannot create sample.png; use the existing sample or choose a fresh project.\n");
exit(1);
}
if (fwrite($output, $png) !== strlen($png) || !fclose($output)) {
fwrite(STDERR, "Cannot finish sample.png.\n");
exit(1);
}
ファイルを作成してアップロードします。
php php-filter-demo/make-sample.php &&
curl -sS -i -F 'upload=@php-filter-demo/sample.png' http://127.0.0.1:8787/upload.php
HTTP 201 と、accepted: true、mime: "image/png"、bytes: 67、ランダムな id、sha256 を含む JSON が返るはずです。返された ID を次のコマンドにコピーし、ID を置き換えてください。
cmp php-filter-demo/sample.png php-filter-demo/private/ID/file.png
出力がなく終了ステータスがゼロなら、保存したバイト列は一致しています。サーバーが公開するのは public/ だけなので、非公開ファイルにダウンロード URL はありません。再度アップロードするには、cURL コマンドだけを実行してください。受け入れるたびに、別の非公開ファイルが作成されます。
次に、画像に見せかけたテキストを送信します。cURL の ;type=image/png は偽の MIME ヘッダーを、;filename=photo.png は偽のファイル名を指定します。どちらも検出されるタイプを決定するものではありません。
printf '%s\n' 'This is text, not an image.' > php-filter-demo/disguised.png &&
curl -sS -i -F 'upload=@php-filter-demo/disguised.png;type=image/png;filename=photo.png' \
http://127.0.0.1:8787/upload.php
HTTP 415 と accepted: false、code: "file_type" が返り、アップロードが新たに保存されないはずです。このコマンドを再実行すると、デモの
disguised.png が置き換わります。診断用リクエストでは、拒否時のレスポンス本文を読めるよう、cURL の --fail を省略しています。cURL の転送が成功しても、サーバーがファイルを受け入れたとは限りません。
| レスポンス | 意味 |
|---|---|
| 201 | ファイルが受け入れルールを満たし、保存済み |
| 400 | アップロードが欠落、不正、部分的、または空 |
| 413 | PHP のファイル/リクエスト上限、またはアプリケーションの 5 MiB 上限により拒否。code を確認 |
| 415 | 検出した MIME タイプが許可リストの対象外 |
| 500 | アップロードまたは非公開ストレージが利用不可。受け入れは報告されていない |
リクエストサイズの診断には、これらの cURL リクエストが送信する
Content-Length を使います。PHP は
$_FILES の内容を、post_max_size を超えた場合に空にすることがあります。長さのヘッダーがなければ、このハンドラーはその状況をファイルの欠落と区別できません。デプロイ先のウェブサーバーでリクエスト全体の制限を適用してください。終了したら Ctrl+C で開発サーバーを停止します。受け入れたファイルは、削除するまでデモの private/ ディレクトリに残ります。
HTML Purifier による安全な HTML コンテンツ処理
HTML のサニタイズは HTML 文字列を変換する処理です。アップロードした PNG が MIME ルールに一致するかどうかの判定には関与しません。HTML Purifierは、送信されたマークアップを解析し、要素と属性の許可リストを適用します。
HTML Purifier の使用方法
この独立した例を php-filter-demo/sanitize.php として保存してください。許可リストは段落、太字の強調、斜体の強調、改行を保持します。属性、リンク、画像は一切許可しません。Cache.SerializerPath は、ライブラリが生成する定義をプロジェクトの非公開キャッシュに保存します。
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.Allowed', 'p,strong,em,br');
$config->set('Cache.SerializerPath', __DIR__ . '/cache');
$purifier = new HTMLPurifier($config);
$dirtyHtml = '<script>alert("bad")</script><p onclick="bad()" style="color:red">Hello <strong>PHP</strong><img src="x" onerror="bad()"></p>';
echo $purifier->purify($dirtyHtml), PHP_EOL;
親ディレクトリから実行します。
php php-filter-demo/sanitize.php
期待される出力:
<p>Hello <strong>PHP</strong></p>
要素や属性は、リッチテキストフィールドで必要な場合だけ追加してください。このポリシーは HTML.Allowed ディレクティブで制御します。結果は HTML 本文のフラグメントとして使います。これは JavaScript 文字列、CSS 値、HTML 属性向けのエスケープではありません。プレーンテキストのフィールドには、表示時に htmlspecialchars() などを使い、コンテキストに応じた出力エスケープを行ってください。どちらの種類のフィールドを保存する場合も、SQL のプリペアドステートメントを使用します。サニタイズをしても、SQL への文字列展開が安全になるわけではありません。
各ライブラリの使い分け
ハンドラーの例のように、受け入れルールやフォームデータのルールを組み合わせたい場合は、Respect\Validation を使います。フィールドが意図的に HTML を受け入れる場合は HTML Purifier を使います。すでに Symfony Validator を使っているアプリケーションでは、File 制約でファイルサイズと拡張子/MIME を検証できます。この例のために別の検証フレームワークをインストールするのではなく、既存の検証フローで Symfony の制約を使い続けてください。
このローカルエンドポイントには、認証、ユーザーごとの割り当て制限、マルウェアスキャナーがありません。5 MiB の上限は受け入れる各ファイルの制限であり、総ストレージ容量やデコード後の画像のメモリ使用量を制限するものではありません。公開前に、アップロードを許可する対象と、非公開のバイト列を利用可能にする前に承認が必要なデコーダーやスキャナーを決めてください。
Transloadit のファイルフィルタリング
処理パイプラインでは、🤖 /file/filter Robotが、メタデータに基づいて Stepで後続処理するファイルを選択します。これらは Assembly内の処理です。この選択は、ローカル PHP ハンドラーによる保存の判定とは別です。例を示します。
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"filter_images": {
"use": ":original",
"robot": "/file/filter",
"condition_type": "and",
"accepts": [
["${file.mime}", "regex", "image"],
["${file.meta.width}", ">=", 100]
],
"declines": [["${file.size}", ">", 10485760]]
}
}
}
両方の受け入れ条件に一致する必要があり、10 MiB を超えるファイルは拒否されます。このメタデータルールは、画像が無害であることを証明するものではありません。Robot は JavaScript の条件も受け付けます。たとえば、500,000 バイト未満の横長ファイルには、代わりに次の accepts 値を使えます。
{
"accepts": "${file.meta.width > file.meta.height && file.size < 500000}"
}
Robot のドキュメントでは、条件の優先順位と JavaScript 評価の追加料金を説明しています。PHP アプリケーションをこの処理ワークフローに接続する必要がある場合は、PHP SDKを使用してください。
