PHP の session.upload_progress でファイルアップロードの進捗を追跡
PHP は、ブラウザーがファイルを送信している間も、受信済みの量を報告できます。アップロードと進捗取得のリクエストは並行して実行する必要があり、進捗の取得結果でアップロードの最終結果を上書きしてはいけません。このローカル実行用のサンプルでは、最大 10 MiB の JPEG、PNG、PDF を受け付け、低速転送中の進捗を表示し、PHP によるファイルの保存完了を確認します。
サーバー設定の要件
Linux コンテナーを使う Docker と、最新のブラウザーを使用します。以下の設定では PHP 8.4.27、PHP-FPM、Nginx 1.28.3 を使用し、Linux 上の Chromium 152 でテストしています。PHP 8.4 は引き続きサポート対象です。既存のサーバーに適用する場合は、2026年10月21日のセキュリティ修正、またはベンダーが確認済みのバックポートを含む、保守中の PHP リリースを使用してください。パッチ未適用の古い環境は適していません。
PHP の別の勧告である10月23日のセッションに関する勧告は、これらのパッチ適用済みリリースにも該当します。問題が発生するのは、アップロードの進捗取得が有効で、設定で php_binary または
php_serialize が選択され、さらにアプリケーションコードが
session.serialize_handler を php に切り替える際に、ini_set() を session_start() より前に使う場合です。このサンプルでは、実行時にデフォルトの php シリアライザーを変更しません。PHP は、アップロードの進捗取得を有効にした状態でこの使い方を明示的に認めています。アプリケーションが実行時にシリアライザーを変更する場合は、勧告の緩和策に従い、修正版がリリースされるまでアップロードの進捗取得を無効にしてください。その場合、この進捗表示デモは記載どおりには動作しません。
php-upload-progress という新しいディレクトリと、その中に public サブディレクトリを作成してください。以下の四つの設定ファイルは php-upload-progress に保存します。後のセクションで紹介する三つのアプリケーションファイルは
public に保存します。
次の内容を Dockerfile として保存してください。
FROM php:8.4.27-fpm-alpine3.23
RUN apk add --no-cache nginx=1.28.3-r7 \
&& mkdir -p /var/lib/php-upload-demo /var/lib/php-upload-sessions \
&& chown www-data:www-data /var/lib/php-upload-demo /var/lib/php-upload-sessions \
&& chmod 0700 /var/lib/php-upload-demo /var/lib/php-upload-sessions
COPY php.ini /usr/local/etc/php/conf.d/zz-upload.ini
COPY fpm.conf /usr/local/etc/php-fpm.d/zz-upload.conf
COPY nginx.conf /etc/nginx/nginx.conf
COPY public/ /app/public/
CMD ["sh", "-c", "php-fpm -D && exec nginx -g 'daemon off;'"]
次の内容を php.ini として保存してください。PHP は upload.php の実行前にアップロードを解析するため、これらの設定はハンドラー内の ini_set() 呼び出しではなく、設定ファイルに記述します。進捗キーは upload_progress_ と、フォームの PHP_SESSION_UPLOAD_PROGRESS フィールドの値を組み合わせたものです。このライフサイクルは、PHP のセッションアップロード進捗マニュアルで説明されています。
session.save_handler = files
session.save_path = /var/lib/php-upload-sessions
session.name = PHPUPLOADDEMO
session.use_strict_mode = 1
session.use_only_cookies = 1
session.cookie_httponly = 1
session.cookie_samesite = Strict
session.upload_progress.enabled = On
session.upload_progress.cleanup = On
session.upload_progress.prefix = "upload_progress_"
session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
session.upload_progress.freq = "1%"
session.upload_progress.min_freq = 0.1
upload_max_filesize = 10M
post_max_size = 12M
max_input_time = 120
log_errors = On
display_errors = Off
次の内容を fpm.conf として保存してください。四つのワーカーを用意することで、別のワーカーがアップロードを受信している間も、進捗リクエストを処理できます。処理中の単一ワーカーでは、両方のリクエストを同時に処理できません。
[www]
pm = static
pm.max_children = 4
request_terminate_timeout = 120s
次の内容を nginx.conf として保存してください。
user www-data;
worker_processes 1;
error_log /dev/stderr warn;
events { worker_connections 128; }
http {
include /etc/nginx/mime.types;
access_log /dev/stdout;
server {
listen 8080;
root /app/public;
index index.html;
client_max_body_size 12m;
location / { try_files $uri $uri/ =404; }
location ~ \.php$ {
try_files $uri =404;
include /etc/nginx/fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass 127.0.0.1:9000;
fastcgi_request_buffering off;
fastcgi_read_timeout 120s;
}
}
}
重要な設定は
fastcgi_request_buffering off です。これにより、Nginx は受信したバイトを即座に PHP へ転送します。fastcgi_buffering はレスポンスを制御し、proxy_request_buffering は HTTP アップストリームに適用されます。どちらも PHP-FPM 向けのこの設定の代わりにはなりません。リクエスト上限を 12 MiB にすることで、ファイル上限の 10 MiB に加えて、マルチパートのオーバーヘッドを確保しています。このデモは Nginx に直接接続します。アップロードをバッファリングする別のプロキシを挟むと、途中の進捗が見えなくなります。
アップロードハンドラーの実装
次の内容を public/upload.php として保存してください。PHP のアップロードエラーを確認し、一時ファイルの MIME タイプを調べ、受け付けたデータをランダムな名前でウェブルートの外に保存します。元のファイル名をパスとして使用することはありません。ブラウザーが送信する MIME タイプを検証に使えない理由は、PHP のアップロードドキュメントで説明されています。
<?php
// public/upload.php
declare(strict_types=1);
function reply(int $status, array $body): never {
http_response_code($status);
header('Content-Type: application/json');
header('Cache-Control: no-store');
echo json_encode($body, JSON_THROW_ON_ERROR);
exit;
}
try {
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
header('Allow: POST');
reply(405, ['error' => 'Use POST to upload a file.']);
}
$file = $_FILES['file'] ?? null;
if (!is_array($file) || !isset($file['error'], $file['size'], $file['tmp_name']) ||
!is_int($file['error']) || !is_int($file['size']) || !is_string($file['tmp_name'])) {
reply(400, ['error' => 'Choose one file.']);
}
if ($file['error'] === UPLOAD_ERR_INI_SIZE || $file['size'] > 10 * 1024 * 1024) {
reply(413, ['error' => 'The file exceeds 10 MiB.']);
}
if ($file['error'] !== UPLOAD_ERR_OK || !is_uploaded_file($file['tmp_name'])) {
reply(400, ['error' => 'PHP did not receive a complete file.']);
}
$extensions = ['image/jpeg' => 'jpg', 'image/png' => 'png', 'application/pdf' => 'pdf'];
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
if (!isset($extensions[$mime])) {
reply(415, ['error' => 'Choose a JPEG, PNG, or PDF.']);
}
$directory = '/var/lib/php-upload-demo';
if (!is_dir($directory) || !is_writable($directory)) {
throw new RuntimeException('Private storage is unavailable');
}
$filename = bin2hex(random_bytes(16)) . '.' . $extensions[$mime];
$destination = $directory . '/' . $filename;
if (!move_uploaded_file($file['tmp_name'], $destination)) {
throw new RuntimeException('Could not store upload');
}
reply(201, ['success' => true, 'filename' => $filename, 'size' => $file['size']]);
} catch (Throwable $error) {
error_log('Upload failed: ' . get_class($error));
reply(500, ['error' => 'The upload service is unavailable.']);
}
成功レスポンスは、ファイルが非公開ストレージへ移動されたことを意味します。コンテンツを安全に公開できるという意味ではありません。繰り返し受け付けたアップロードには、それぞれ別のランダムなファイル名が付きます。このサンプルでは、ファイルの重複排除や中断した転送の再開は行いません。
進捗追跡の実装
次の内容を public/progress.php として保存してください。まず ID なしで呼び出すと、セッション Cookie が設定されます。以降の呼び出しでは、同じ Cookie を使ってアップロードのエントリーを読み取ります。読み取り後は、直ちにセッションを閉じてください。PHP のファイルベースのセッションは、開いている間データをロックするため、同じセッションを使う他のリクエストが遅れる場合があります。session_write_close() を参照してください。
<?php
// public/progress.php
declare(strict_types=1);
header('Content-Type: application/json');
$id = $_GET['id'] ?? '';
if (!is_string($id) || ($id !== '' && !preg_match('/\A[0-9a-f-]{36}\z/', $id))) {
http_response_code(400);
echo json_encode(['error' => 'Invalid progress ID.']);
exit;
}
if (!session_start()) {
http_response_code(503);
echo json_encode(['error' => 'Tracking is unavailable.']);
exit;
}
$current = $_SESSION['upload_progress_' . $id] ?? null;
session_write_close();
header('Cache-Control: no-store');
echo json_encode(['progress' => $current === null ? null : [
'loaded' => $current['bytes_processed'],
'total' => $current['content_length'],
]], JSON_THROW_ON_ERROR);
進捗は、オーバーヘッドを含むマルチパートリクエスト全体を対象に測定します。session.upload_progress.cleanup が有効な場合、PHP はリクエストボディの読み取り後にエントリーを削除します。そのため、エントリーがない状態は「未開始」と「受信済み」のどちらも意味し得ます。これだけでは成功か失敗かを判断できません。検証と保存が成功したかどうかを報告するのは upload.php だけです。
クライアント側の統合
次の内容を public/index.html として保存してください。非表示の進捗フィールドをファイルより前に配置し、PHP がファイルのバイトを受信する前にその ID を取得できるようにします。無効なコントロールはフォームデータから除外されるため、コントロールを無効にする前に FormData を構築してください。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>PHP upload progress</title>
</head>
<body>
<h1>Upload a JPEG, PNG, or PDF</h1>
<form id="upload-form">
<fieldset id="controls">
<legend>One file, up to 10 MiB</legend>
<input type="hidden" name="PHP_SESSION_UPLOAD_PROGRESS" id="progress-id" />
<label for="file">File</label>
<input id="file" type="file" name="file" accept="image/jpeg,image/png,application/pdf" required />
<button type="submit">Upload</button>
</fieldset>
</form>
<label for="progress">Request received by PHP</label>
<progress id="progress" value="0" max="100"></progress>
<p id="status" role="status">Choose a file.</p>
<script>
const form = document.getElementById('upload-form')
const controls = document.getElementById('controls')
const progressId = document.getElementById('progress-id')
const bar = document.getElementById('progress')
const status = document.getElementById('status')
let activeJob = null
async function poll(job) {
try {
const response = await fetch(`progress.php?id=${job.id}`, {
cache: 'no-store',
signal: job.controller.signal,
})
if (!response.ok) throw new Error('Progress request failed')
const { progress } = await response.json()
// An old response can arrive after completion or during the next upload.
if (activeJob !== job) return
if (progress && progress.total > 0) {
const percentage = Math.min(100, Math.floor(100 * progress.loaded / progress.total))
bar.value = percentage
status.textContent = percentage === 100
? 'Request received; waiting for server confirmation.'
: `Uploading: ${percentage}%`
}
} catch {
if (activeJob === job) {
status.textContent = 'Progress unavailable; waiting for the upload response.'
}
}
// Schedule after this request settles, so polls never overlap.
if (activeJob === job) job.timer = setTimeout(() => poll(job), 500)
}
form.addEventListener('submit', async (event) => {
event.preventDefault()
if (activeJob !== null) return
const job = { id: crypto.randomUUID(), controller: new AbortController(), timer: null }
progressId.value = job.id
const body = new FormData(form)
activeJob = job
controls.disabled = true
bar.value = 0
status.textContent = 'Starting upload…'
let message = 'Upload could not be confirmed. Check the server before retrying.'
let stored = false
try {
const session = await fetch('progress.php', { cache: 'no-store' })
if (!session.ok) throw new Error('Session initialization failed')
job.timer = setTimeout(() => poll(job), 500)
const response = await fetch('upload.php', { method: 'POST', body })
if (!response.ok) {
message = response.status === 413 ? 'The file exceeds the upload size limit.'
: response.status === 415 ? 'Choose a JPEG, PNG, or PDF.'
: response.status >= 500 ? 'The upload service is unavailable.'
: 'The upload was rejected. Choose a file and try again.'
throw new Error('Upload rejected')
}
const result = await response.json()
if (result.success !== true) throw new Error('Missing storage confirmation')
stored = true
message = `Upload complete! Stored as ${result.filename} (${result.size} bytes).`
} catch {
// A network failure can occur after storage; do not claim a safe automatic retry.
} finally {
activeJob = null
clearTimeout(job.timer)
job.controller.abort()
controls.disabled = false
status.textContent = message
if (stored) bar.value = 100
}
})
</script>
</body>
</html>
このページでは、一度に一つのアップロードを受け付けます。アップロードの処理中はファイルの選択と送信を無効にし、ハンドラーも繰り返し発生した送信イベントを無視します。各ジョブには専用の進捗 ID と中止コントローラーがあります。完了時には、フォームを再び有効にする前にそのジョブを無効化します。ポーリングがすでに response.json() まで到達していても、同一性チェックによって別のジョブの表示を書き換えることを防ぎます。fetch の中止により、不要な保留中のポーリング処理も停止します。
低速アップロードの実行
七つのファイルをすべて保存したら、php-upload-progress を含むディレクトリで、以下を貼り付けて実行してください。サブシェルを使うため、現在のディレクトリは変わりません。ディレクトリの移動やビルドに失敗すると、&& の連鎖は停止します。初回ビルド時は Docker にネットワークアクセスが必要です。8080 がすでに使用中の場合は、別のホストポートを選んでください。
(
cd php-upload-progress &&
docker build -t php-upload-progress . &&
docker run --rm --name php-upload-progress \
--publish 127.0.0.1:8080:8080 php-upload-progress
)
そのターミナルは実行したまま、http://127.0.0.1:8080/ を開いてください。ブラウザーの開発者ツールでアップロード帯域を約 256 KiB/s に制限し、約 4 MiB の JPEG、PNG、PDF のいずれかを選んで
Upload を押してください。途中のパーセント表示の後に Upload complete! が表示され、続いて生成されたファイル名とバイト数が表示されるはずです。高速なローカルアップロードはポーリングの間に終了し、直接完了表示になる場合があります。
低速転送中も進捗がゼロのままの場合は、Cookie が有効であること、初期化用の
progress.php リクエストが成功したこと、その Cookie が両方のリクエストに付いていることを確認してください。次にワーカー数とリクエストのバッファリングを確認します。413 レスポンスは PHP と Nginx のどちらからも返される場合があります。Nginx の上限である 12 MiB を超えるリクエストは、PHP ハンドラーに到達しません。HTML の accept 属性はファイル選択時のヒントにすぎないため、名前を変更したテキストファイルを選ぶと、タイプの検証で拒否されるはずです。
受け付けたファイルは、実行中のコンテナー内の /var/lib/php-upload-demo に保存されます。公開 URL はありません。終了したら Ctrl+C でフォアグラウンドのコンテナーを停止してください。その後、--rm によってアップロードとセッションデータが削除されます。保存済みのソースファイルや設定ファイルを変更した後は、イメージを再ビルドする必要があります。
セキュリティ上の注意点
これはループバック接続専用のデモであり、ログイン、CSRF トークン、クォータ、マルウェアスキャンは備えていません。MIME 検出は形式を制限しますが、ファイルが無害であることの証明にはなりません。アプリケーションによる検証と処理が完了するまでは、コンテンツを非公開にしてください。本番環境へのデプロイには、HTTPS、安全なセッション Cookie、アクセス制御、明示的な保持ポリシーも必要です。このコンテナーを変更せずにアップロードサービスとして公開しないでください。
ブラウザーの互換性
このページは fetch、FormData、AbortController、crypto.randomUUID() をポリフィルなしで使用します。randomUUID() には安全なコンテキストが必要です。このデモではループバックの HTTP 接続で動作しますが、リモートでの利用には HTTPS が必要です。Cookie は有効にする必要があります。ページを再読み込みしたり閉じたりすると、結果表示は破棄されます。この実装には一時停止や再開のボタンはありません。
