【PHP8.x】UPLOAD_ERR_PARTIAL定数の使い方

Copy
1<?php
2
3/**
4 * アップロードされたファイルを処理し、そのステータスまたはエラーメッセージを返します。
5 *
6 * システムエンジニアを目指す初心者の方へ:
7 * この関数は、Webフォームからファイルをアップロードする際に発生しうる様々なエラーを
8 * 検出する方法を示しています。`$_FILES`という特別なPHPの変数（スーパーグローバル）は、
9 * アップロードされたファイルに関する情報（ファイル名、種類、サイズ、一時的な保存パス、
10 * そしてアップロードの成功/失敗を示すエラーコード）を格納しています。
11 *
12 * 特に`$_FILES['input_name']['error']`には、以下のPHP定義済み定数で表されるエラーコードが含まれます。
13 * `UPLOAD_ERR_PARTIAL`は、ファイルが完全にアップロードされず、一部だけが転送された場合に発生します。
14 *
15 * @param string $fileInputName HTMLフォームのファイル入力フィールドの`name`属性。
16 * @return string アップロードのステータスまたはエラーを示すメッセージ。
17 */
18function handleFileUpload(string $fileInputName): string
19{
20    // $_FILES変数は、アップロードされたファイルの情報を持つスーパーグローバル配列です。
21    // まず、指定されたファイル入力フィールド名に対応するファイルが存在するかチェックします。
22    if (!isset($_FILES[$fileInputName])) {
23        return "エラー: ファイル入力フィールド '{$fileInputName}' が存在しません。HTMLフォームのname属性を確認してください。";
24    }
25
26    $file = $_FILES[$fileInputName];
27
28    // ファイルアップロード時に発生したエラーコードをチェックします。
29    switch ($file['error']) {
30        case UPLOAD_ERR_OK:
31            // エラーなし。ファイルは正常にアップロードされました。
32            // 実際のアプリケーションでは、ここで `move_uploaded_file()` 関数を使って
33            // 一時ディレクトリからファイルを永続的なストレージに移動します。
34            return "ファイル '{$file['name']}' (タイプ: {$file['type']}, サイズ: {$file['size']} バイト) が正常にアップロードされました。";
35
36        case UPLOAD_ERR_INI_SIZE:
37            // php.ini の `upload_max_filesize` ディレクティブで設定された最大サイズを超過しています。
38            // キーワードにある `upload_err_ini_size` はこのケースを指します。
39            return "エラー: アップロードされたファイルが大きすぎます (サーバー設定の制限 `upload_max_filesize` を超過)。";
40
41        case UPLOAD_ERR_FORM_SIZE:
42            // HTMLフォームで指定された隠しフィールド `MAX_FILE_SIZE` の値を超過しています。
43            return "エラー: アップロードされたファイルが大きすぎます (HTMLフォーム設定の制限)。";
44
45        case UPLOAD_ERR_PARTIAL:
46            // ファイルが部分的にしかアップロードされませんでした。
47            // ネットワークの問題、接続の切断、またはユーザーによるアップロードのキャンセルが原因である可能性があります。
48            return "エラー: ファイルが部分的にしかアップロードされませんでした。再度お試しください。";
49
50        case UPLOAD_ERR_NO_FILE:
51            // ファイルが選択されなかったか、または空のファイルを送信しようとしました。
52            return "エラー: ファイルが選択されていません。";
53
54        case UPLOAD_ERR_NO_TMP_DIR:
55            // ファイルを保存するための一時フォルダがサーバーに見つかりません。
56            // サーバー管理者に連絡して、php.ini の `upload_tmp_dir` 設定を確認してもらう必要があります。
57            return "エラー: サーバーの一時フォルダが見つかりません。";
58
59        case UPLOAD_ERR_CANT_WRITE:
60            // ディスクへのファイル書き込みに失敗しました。サーバーのパーミッション設定を確認してください。
61            return "エラー: サーバーへのファイル書き込みに失敗しました。";
62
63        case UPLOAD_ERR_EXTENSION:
64            // PHPの拡張機能がファイルのアップロードを停止しました。
65            // 通常、PHPの構成ミスや特定の拡張機能の不具合が原因です。
66            return "エラー: PHP拡張機能によりファイルアップロードが停止されました。";
67
68        default:
69            // 上記以外の不明なエラーが発生した場合。
70            return "不明なアップロードエラーが発生しました (エラーコード: {$file['error']})。";
71    }
72}
73
74// --- 単体で動作可能なコードの例（通常はHTMLフォームからのPOSTリクエストを想定） ---
75// この部分は、このPHPスクリプトをCLIで実行した際に、
76// `handleFileUpload`関数がどのように機能するかをデモンストレーションするためのものです。
77// 実際のWebサーバー環境では、HTMLフォームからファイルがPOSTメソッドで送信されると、
78// PHPが自動的に `$_FILES` スーパーグローバル変数を設定します。
79
80// UPLOAD_ERR_PARTIAL のシミュレーション
81$_FILES['document_file'] = [
82    'name' => 'my_report.pdf',
83    'type' => 'application/pdf',
84    'tmp_name' => '/tmp/php_simulated_partial_upload', // 実際の一時ファイルパスを模擬
85    'error' => UPLOAD_ERR_PARTIAL, // 今回のリファレンス情報に合致
86    'size' => 123456 // 部分的にアップロードされたサイズを模擬
87];
88echo handleFileUpload('document_file') . "\n";
89
90// UPLOAD_ERR_INI_SIZE のシミュレーション (キーワードにも関連)
91$_FILES['document_file'] = [
92    'name' => 'very_large_image.jpg',
93    'type' => 'image/jpeg',
94    'tmp_name' => '', // エラーのため一時ファイルは通常存在しません
95    'error' => UPLOAD_ERR_INI_SIZE, // PHP設定によるファイルサイズ超過
96    'size' => 0 // エラーのためサイズは0または不明
97];
98echo handleFileUpload('document_file') . "\n";
99
100// 正常なアップロードのシミュレーション
101$_FILES['document_file'] = [
102    'name' => 'small_doc.txt',
103    'type' => 'text/plain',
104    'tmp_name' => '/tmp/php_simulated_ok_upload',
105    'error' => UPLOAD_ERR_OK, // 正常なアップロード
106    'size' => 1024 // 正常なファイルサイズ
107];
108echo handleFileUpload('document_file') . "\n";
109
110// ファイルが選択されなかった場合のシミュレーション
111$_FILES['document_file'] = [
112    'name' => '',
113    'type' => '',
114    'tmp_name' => '',
115    'error' => UPLOAD_ERR_NO_FILE, // ファイル未選択
116    'size' => 0
117];
118echo handleFileUpload('document_file') . "\n";
119
120// HTMLフォームに存在しないファイル入力フィールド名を指定した場合
121// (これにより、handleFileUpload関数内で $_FILES['nonExistent'] が検出されます)
122unset($_FILES['document_file']); // 前のシミュレーションの影響をクリア
123echo handleFileUpload('nonExistentFileInput') . "\n";
124
125?>

このPHPサンプルコードは、Webフォームからのファイルアップロード処理で発生する可能性のあるエラーを検出し、適切に対応する方法をシステムエンジニアを目指す初心者向けに示しています。PHPでは、アップロードされたファイルに関する情報は$_FILESという特別なグローバル変数に格納され、ここにはファイル名、種類、サイズ、そしてアップロードの成功/失敗を示すエラーコードが含まれます。

特にUPLOAD_ERR_PARTIAL定数は、ネットワークの問題や接続の切断などにより、ファイルが完全にアップロードされず、一部だけが転送された場合に発生するエラーを示します。サンプルコードのhandleFileUpload関数は、HTMLフォームのファイル入力フィールド名を引数として受け取り、$_FILES変数からそのファイルのエラーコードをチェックします。そして、UPLOAD_ERR_PARTIALだけでなく、php.iniで設定された最大サイズ超過を示すUPLOAD_ERR_INI_SIZEや、ファイルが選択されていないUPLOAD_ERR_NO_FILEなど、様々なアップロードエラー定数に応じて、状況を説明する文字列メッセージを戻り値として返します。これにより、アップロードの状況を正確に判断し、ユーザーに適切な情報を提供できるようになります。

Copy
1<?php
2
3/**
4 * アップロードされたファイルを処理し、エラーメッセージまたは成功メッセージを返します。
5 * システムエンジニアを目指す初心者向けに、ファイルアップロード時の各種エラー（特にUPLOAD_ERR_PARTIAL）
6 * のハンドリング方法を示します。
7 *
8 * @return string 処理結果メッセージ
9 */
10function handleFileUpload(): string
11{
12    // POSTリクエストがあり、かつファイルが送信されたかを確認します。
13    if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['uploadedFile'])) {
14        $file = $_FILES['uploadedFile'];
15
16        // $_FILES['uploadedFile']['error'] にはファイルアップロード時のエラーコードが格納されます。
17        // UPLOAD_ERR_OK は、ファイルアップロードが成功したことを示す定数です。
18        if ($file['error'] === UPLOAD_ERR_OK) {
19            $tmpFilePath = $file['tmp_name']; // アップロードされたファイルの一時パス
20            $uploadDir = __DIR__ . '/uploads/'; // ファイルを保存するディレクトリ。スクリプトと同じ階層に'uploads'フォルダを作成します。
21            $fileName = basename($file['name']); // オリジナルのファイル名を取得し、パス成分を除去します。
22            $destinationPath = $uploadDir . $fileName; // 保存先のフルパス
23
24            // アップロードディレクトリが存在しない場合は作成します。
25            if (!is_dir($uploadDir)) {
26                // 0777はディレクトリのパーミッション、trueは再帰的にディレクトリを作成することを意味します。
27                mkdir($uploadDir, 0777, true);
28            }
29
30            // 一時的にアップロードされたファイルを指定の保存先に移動します。
31            // move_uploaded_file() はセキュリティ上、アップロードされたファイルのみを移動するために使われます。
32            if (move_uploaded_file($tmpFilePath, $destinationPath)) {
33                return "ファイル '{$fileName}' が正常にアップロードされました。<br>保存先: " . htmlspecialchars($destinationPath);
34            } else {
35                return "ファイルの移動に失敗しました。書き込み権限を確認してください。";
36            }
37        } else {
38            // エラーコードに応じて適切なメッセージを返します。
39            switch ($file['error']) {
40                case UPLOAD_ERR_INI_SIZE:
41                    // upload_max_filesize (php.ini) を超えた場合に発生します。
42                case UPLOAD_ERR_FORM_SIZE:
43                    // HTMLフォームのMAX_FILE_SIZEを超えた場合に発生します。
44                    return "アップロードされたファイルが大きすぎます。";
45                case UPLOAD_ERR_PARTIAL:
46                    // ファイルの一部しかアップロードされなかった場合に発生します。
47                    // ネットワークの問題や、ユーザーがアップロードを途中でキャンセルした場合に考えられます。
48                    return "ファイルの一部しかアップロードされませんでした。通信状況が不安定だったか、ユーザーが途中でキャンセルした可能性があります。";
49                case UPLOAD_ERR_NO_FILE:
50                    // キーワードに関連するエラー: ファイルが選択されなかったか、アップロードされなかった場合に発生します。
51                    return "ファイルが選択されていないか、アップロードされませんでした。";
52                case UPLOAD_ERR_NO_TMP_DIR:
53                    // 一時フォルダが存在しない場合に発生します。
54                    return "サーバー上の一時フォルダが見つかりません。";
55                case UPLOAD_ERR_CANT_WRITE:
56                    // ディスクへの書き込みに失敗した場合に発生します。
57                    return "ファイルの保存に失敗しました。サーバーのディスク容量または書き込み権限を確認してください。";
58                case UPLOAD_ERR_EXTENSION:
59                    // PHPの拡張機能によってアップロードが停止された場合に発生します。
60                    return "PHP拡張機能によりファイルのアップロードが停止されました。";
61                default:
62                    // その他の不明なエラー
63                    return "不明なファイルアップロードエラーが発生しました (エラーコード: {$file['error']})。";
64            }
65        }
66    }
67    return ""; // POSTリクエストがない場合や、ファイルが送信されていない場合は空文字列を返します。
68}
69
70// ファイルアップロード処理を実行し、結果メッセージを取得します。
71$uploadMessage = handleFileUpload();
72
73?>
74<!DOCTYPE html>
75<html lang="ja">
76<head>
77    <meta charset="UTF-8">
78    <meta name="viewport" content="width=device-width, initial-scale=1.0">
79    <title>PHP ファイルアップロードサンプル</title>
80</head>
81<body>
82    <h1>ファイルをアップロード</h1>
83
84    <?php if (!empty($uploadMessage)): ?>
85        <p><strong><?php echo htmlspecialchars($uploadMessage); ?></strong></p>
86    <?php endif; ?>
87
88    <form action="" method="post" enctype="multipart/form-data">
89        <label for="uploadedFile">アップロードするファイルを選択:</label><br>
90        <input type="file" name="uploadedFile" id="uploadedFile"><br><br>
91        <input type="submit" value="アップロード">
92    </form>
93</body>
94</html>

このPHPサンプルコードは、ファイルをアップロードする際に発生する様々なエラー、特にUPLOAD_ERR_PARTIALのような途中で中断されたアップロードのエラーを適切に処理する方法を示しています。

UPLOAD_ERR_PARTIALは、PHPが提供する組み込み定数の一つで、ファイルのアップロードが完了する前に中断され、一部のデータしか受け取れなかった場合に発生するエラーコードです。これは、ネットワークの不具合やユーザーがアップロード処理を途中でキャンセルした際などに起こり得ます。この定数自体は引数を取らず、戻り値もありません。

コード内のhandleFileUpload関数は、ファイルアップロードのロジックをカプセル化したものです。この関数は引数を取りませんが、処理結果のメッセージを文字列として返します。関数内部では、$_FILESスーパーグローバル変数を通じてアップロードされたファイルの情報を取得し、['error']キーに格納されているエラーコードをswitch文で判定します。

具体的には、UPLOAD_ERR_PARTIALの場合には「ファイルの一部しかアップロードされませんでした。」といったメッセージを返します。また、キーワードにも関連するUPLOAD_ERR_NO_FILEは、ユーザーがファイルを選択しなかった場合に発生するエラーで、「ファイルが選択されていないか、アップロードされませんでした。」と表示されます。UPLOAD_ERR_OKであればアップロードが成功したと判断し、move_uploaded_file関数でファイルを指定のディレクトリに移動します。このように、各エラーコードに対応したメッセージを返すことで、ユーザーに分かりやすいフィードバックを提供し、システムエンジニアとしてエラーハンドリングの重要性を学ぶことができます。