【PHP8.x】fwrite()関数の使い方

Copy
1<?php
2
3/**
4 * PHPのfwrite関数を使ったファイル書き込みとエラーハンドリングのサンプルコード。
5 * システムエンジニアを目指す初心者向けに、fwriteで発生しうるエラーの原因を簡潔に示します。
6 * この関数は単体で実行可能で、内部で複数のファイル操作を試行し、結果とエラー原因の説明を出力します。
7 *
8 * @return void
9 */
10function demonstrateFwriteErrorCauses(): void
11{
12    // PHPのエラー表示設定 (スクリプト内で発生した警告やエラーをすぐ確認できるようにするため)
13    ini_set('display_errors', '1');
14    ini_set('display_startup_errors', '1');
15    error_reporting(E_ALL);
16
17    echo "--- PHP fwrite エラー原因 デモンストレーション --- \n\n";
18
19    // --- ケース1: 正常なファイル書き込み ---
20    // このケースでは、ファイルが正常に開かれ、データが書き込まれることを示します。
21    $successFilename = 'fwrite_success_example.txt';
22    $successData = "これは正常に書き込まれるべきデータです。\n";
23    echo "--- ケース1: 正常なファイル書き込み ---\n";
24
25    // 'w'モードでファイルを開く。ファイルが存在しない場合は作成し、存在する場合は内容をクリアする。
26    // @演算子でfopenが発行する可能性のある警告を抑制し、戻り値でエラーをハンドリングします。
27    $handle = @fopen($successFilename, 'w');
28
29    if ($handle === false) {
30        // 通常、このケースではfopenは成功するはずですが、万一失敗した場合のエラーメッセージ。
31        echo "【エラー発生】ファイル '{$successFilename}' を開けませんでした。このケースでは予期せぬエラーです。\n";
32        echo "  考えられる原因: 実行ユーザーの書き込み権限がない、またはディスクがいっぱいです。\n";
33    } else {
34        // fwriteは書き込んだバイト数を返すか、エラー時にfalseを返します。
35        $bytesWritten = fwrite($handle, $successData);
36
37        if ($bytesWritten === false) {
38            echo "【エラー発生】'{$successFilename}' への書き込みに失敗しました。\n";
39            echo "  考えられる原因: ディスク容量不足、ファイルシステムの問題、またはファイルハンドルが無効になった。\n";
40        } elseif ($bytesWritten < strlen($successData)) {
41            echo "【警告発生】'{$successFilename}' に一部のデータ ({$bytesWritten} / " . strlen($successData) . "バイト) しか書き込まれませんでした。\n";
42            echo "  考えられる原因: 書き込み中にディスク容量が不足したか、ストリームの制限に達した。\n";
43        } else {
44            echo "【成功】'{$successFilename}' に {$bytesWritten} バイトを書き込みました。\n";
45        }
46
47        fclose($handle); // 開いたファイルハンドルを閉じます。
48        echo "ファイル '{$successFilename}' を閉じました。\n";
49        unlink($successFilename); // デモンストレーション後、ファイルを削除してクリーンアップします。
50    }
51    echo "\n";
52
53    // --- ケース2: 存在しないディレクトリへの書き込み試行 (fopenエラー) ---
54    // ファイルを開く段階で失敗する例。親ディレクトリが存在しない場合にfopenが失敗します。
55    // 実行環境に合わせて、実際に存在しないパスを指定してください。
56    // 例: Linux/macOS では '/tmp/non_existent_dir_for_test/error_file.txt'
57    // 例: Windows では 'C:\\non_existent_dir_for_test\\error_file.txt'
58    $nonExistentPathFilename = '/tmp/non_existent_dir_for_test/error_file.txt';
59    echo "--- ケース2: 存在しないディレクトリへの書き込み試行 ---\n";
60    echo "  試行ファイル: '{$nonExistentPathFilename}'\n";
61
62    $handle = @fopen($nonExistentPathFilename, 'w'); // @で警告を抑制し、戻り値でエラーをハンドリング
63
64    if ($handle === false) {
65        echo "【エラー発生】ファイル '{$nonExistentPathFilename}' を開けませんでした。\n";
66        echo "  考えられる原因: 指定されたパスの親ディレクトリが存在しないか、そのディレクトリを作成する権限がありません。\n";
67        // error_get_last() でPHPが最後に記録したエラー情報を取得できます。
68        $lastError = error_get_last();
69        if ($lastError && isset($lastError['message'])) {
70            echo "  システムエラーメッセージ: " . $lastError['message'] . "\n";
71        }
72    } else {
73        // この分岐には到達しないはずですが、万一開けてしまった場合の処理。
74        fwrite($handle, "予期せぬ書き込み\n");
75        fclose($handle);
76        unlink($nonExistentPathFilename);
77        echo "  警告: '{$nonExistentPathFilename}' が予期せず開かれ、クリーンアップされました。\n";
78    }
79    echo "\n";
80
81    // --- ケース3: 読み込み専用モードで開かれたファイルへの書き込み試行 (fwriteエラー) ---
82    // ファイルは開けるが、書き込み権限がないためにfwriteが失敗する例です。
83    $readOnlyFilename = 'fwrite_read_only_error.txt';
84    // まず、通常の書き込みモードでファイルを作成し、内容を入れておきます。
85    file_put_contents($readOnlyFilename, "初期データ\n");
86    echo "--- ケース3: 読み込み専用ファイルへの書き込み試行 ---\n";
87    echo "  試行ファイル: '{$readOnlyFilename}'\n";
88
89    // 'r'モードでファイルを開く。読み込み専用のため、書き込みは許可されません。
90    $handle = @fopen($readOnlyFilename, 'r');
91
92    if ($handle === false) {
93        echo "【エラー発生】ファイル '{$readOnlyFilename}' を読み込み専用で開けませんでした。このケースでは予期せぬエラーです。\n";
94    } else {
95        echo "  ファイル '{$readOnlyFilename}' を読み込み専用モードで開きました。\n";
96        $dataToAttemptWrite = "このデータは読み込み専用ファイルには書き込まれないはずです。\n";
97        $bytesWritten = fwrite($handle, $dataToAttemptWrite); // 読み込み専用のため、ここでfwriteは失敗します。
98
99        if ($bytesWritten === false) {
100            echo "【エラー発生】読み込み専用ファイルへの書き込みに失敗しました。\n";
101            echo "  考えられる原因: ファイルが書き込み可能なモード ('w', 'a', 'r+', 'x+', 'c+', など) で開かれていません。\n";
102            $lastError = error_get_last();
103            if ($lastError && isset($lastError['message'])) {
104                 echo "  システムエラーメッセージ: " . $lastError['message'] . "\n";
105            }
106        } else {
107            echo "  【予期せぬ結果】読み込み専用ファイルに {$bytesWritten} バイトを書き込んでしまいました。\n";
108        }
109
110        fclose($handle); // ファイルハンドルを閉じます。
111        echo "  ファイル '{$readOnlyFilename}' を閉じました。\n";
112        unlink($readOnlyFilename); // デモンストレーション後、ファイルを削除してクリーンアップします。
113    }
114    echo "\n";
115
116    // --- ケース4: 権限エラー (概念説明) ---
117    // このエラーは、スクリプトを実行しているユーザーがファイルやディレクトリに対して
118    // 書き込み権限を持っていない場合に発生します。OSのファイルシステムレベルでの制御です。
119    echo "--- ケース4: 権限エラー (概念説明) ---\n";
120    echo "  原因: ファイルまたはディレクトリに対する書き込み権限がない場合に発生します。\n";
121    echo "        例: Linux/macOSで '/etc/hosts' のようなシステムファイルに一般ユーザーが書き込もうとする場合。\n";
122    echo "  対処法: ファイルやディレクトリのパーミッション (chmodなど) を確認・変更するか、\n";
123    echo "        適切な権限を持つユーザー (例: sudo) でスクリプトを実行してください。\n";
124    echo "        (このデモンストレーションコードで直接、環境依存なく再現することは難しいため、説明に留めます。)\n";
125    echo "\n";
126
127    echo "--- デモンストレーション終了 ---\n";
128}
129
130// デモンストレーション関数を実行します。
131demonstrateFwriteErrorCauses();

PHPのfwrite関数は、fopen関数などで開かれたファイルに指定されたデータを書き込む際に使用されます。この関数は、引数としてファイルハンドル（resource $stream）、書き込む文字列データ（string $data）、そしてオプションで書き込む最大バイト数（?int $length）を受け取ります。書き込みが成功した場合は実際に書き込まれたバイト数（int）を返し、何らかの理由で失敗した場合はfalseを返します。

このサンプルコードは、fwrite関数を使ったファイル書き込みの基本的な動作と、その際に発生しうる様々なエラーの主な原因を初心者向けにデモンストレーションしています。エラーの原因としては、まずファイルを書き込みモードで開く際に、指定されたパスの親ディレクトリが存在しない、またはスクリプトを実行しているユーザーにそのディレクトリへの書き込み権限がないために、ファイル自体を開けないケースがあります。次に、ファイルは開けたものの、読み込み専用モードで開かれたファイルに対しfwriteを実行しようとした場合、書き込みは失敗します。また、ディスク容量の不足やファイルシステムの問題、あるいはファイルハンドルが無効になった場合にも、fwriteが部分的な書き込みに終わったり、完全に失敗したりすることがあります。システムエンジニアとして、これらの戻り値を常に確認し、適切なエラーハンドリングを行うことが重要です。

Copy
1<?php
2
3/**
4 * 指定されたファイルに複数の行を書き込みます。
5 * 各行の末尾にはOSに応じた改行コードが追加されます。
6 */
7function writeLinesToFile(): void
8{
9    $filePath = 'example.txt'; // 書き込むファイル名
10
11    // ファイルを書き込みモードで開きます。
12    // 'w' モードは、ファイルが存在すれば内容を上書きし、存在しなければ新規作成します。
13    // 成功した場合はファイルリソース、失敗した場合は false を返します。
14    $fileHandle = fopen($filePath, 'w');
15
16    // ファイルが開けたか確認します。
17    if ($fileHandle === false) {
18        echo "エラー: ファイル '{$filePath}' を開けませんでした。" . PHP_EOL;
19        return;
20    }
21
22    $line1 = "これは最初の行です。";
23    $line2 = "これは二番目の行です。";
24    $line3 = "fwrite関数とPHP_EOLを使って改行しています。";
25
26    // 最初の行をファイルに書き込み、OSに応じた改行コードを追加します。
27    // PHP_EOL は現在のOSに適した改行コード (例: Windowsでは \r\n, Linuxでは \n) を提供します。
28    // fwriteは書き込んだバイト数を返します。失敗した場合は false です。
29    if (fwrite($fileHandle, $line1 . PHP_EOL) === false) {
30        echo "エラー: 最初の行の書き込みに失敗しました。" . PHP_EOL;
31        fclose($fileHandle); // エラー時はファイルを閉じる
32        return;
33    }
34
35    // 二番目の行をファイルに書き込み、改行コードを追加します。
36    if (fwrite($fileHandle, $line2 . PHP_EOL) === false) {
37        echo "エラー: 二番目の行の書き込みに失敗しました。" . PHP_EOL;
38        fclose($fileHandle);
39        return;
40    }
41
42    // 三番目の行をファイルに書き込み、改行コードを追加します。
43    if (fwrite($fileHandle, $line3 . PHP_EOL) === false) {
44        echo "エラー: 三番目の行の書き込みに失敗しました。" . PHP_EOL;
45        fclose($fileHandle);
46        return;
47    }
48
49    // ファイルへの操作が完了したら、ファイルを閉じます。
50    fclose($fileHandle);
51
52    echo "ファイル '{$filePath}' にデータが正常に書き込まれました。" . PHP_EOL;
53    echo "ファイルの内容を確認してください。" . PHP_EOL;
54}
55
56// 関数を実行します。
57writeLinesToFile();
58

PHPのfwrite関数は、ファイルにデータを書き込む際に使用されます。最初の引数$streamには、fopen関数などで開かれたファイルの「リソース」（ファイルへの操作権限を示す識別子）を指定します。次の引数$dataには、ファイルに書き込みたい文字列データを与えます。最後の引数$lengthは省略可能で、指定すると$dataの先頭から指定されたバイト数だけが書き込まれ、指定しない場合は$data全体が書き込まれます。関数が成功すると、実際に書き込まれたバイト数が整数値で返され、失敗した場合はfalseが返されるため、エラーチェックが重要です。

サンプルコードでは、fopenでexample.txtファイルを書き込みモードで開き、そのリソースを使ってfwriteで複数行の文字列を書き込んでいます。ここで注目すべきは、各行の文字列の末尾にPHP_EOLを結合している点です。PHP_EOLは、プログラムが動作しているオペレーティングシステムに適した改行コード（Windowsなら\r\n、Linuxなら\nなど）を自動的に挿入してくれる定数であり、環境に依存しない形でファイルに改行を追加できます。全ての書き込みが完了したら、fclose関数で開いたファイルを閉じることで、リソースの解放と書き込み内容の確定が行われます。fwriteはファイルの入出力処理において、データの書き込みと改行の管理に広く活用される基本的な関数です。

Copy
1<?php
2
3/**
4 * PHPのfwrite関数を使用してファイルにUTF-8文字列を書き込むサンプルコードです。
5 * fwriteは文字列のバイト列をそのままファイルに書き込むため、
6 * 文字コードを意識する場合は、書き込む文字列自体が適切なエンコーディングである必要があります。
7 */
8function writeUtf8ToFile(string $filename, string $content): void
9{
10    // ファイルを書き込みモード ('w') で開きます。
11    // 'w' モードは、ファイルが存在しない場合は作成し、存在する場合は内容を上書きします。
12    // 戻り値はファイルリソース、または失敗時にfalseです。
13    $fileHandle = fopen($filename, 'w');
14
15    if ($fileHandle === false) {
16        echo "エラー: ファイル '{$filename}' を開けませんでした。\n";
17        return;
18    }
19
20    // fwrite関数でファイルに文字列を書き込みます。
21    // 第1引数: ファイルリソース ($stream)
22    // 第2引数: 書き込む文字列 ($data)。この文字列のバイト列がそのまま書き込まれます。
23    // 第3引数 (オプション): 書き込む最大バイト数 ($length)。指定しない場合、文字列全体が書き込まれます。
24    // fwriteは書き込んだバイト数を返します。失敗時はfalseを返します。
25    $bytesWritten = fwrite($fileHandle, $content);
26
27    if ($bytesWritten === false) {
28        echo "エラー: ファイル '{$filename}' への書き込みに失敗しました。\n";
29    } else {
30        echo "ファイル '{$filename}' に {$bytesWritten} バイトを書き込みました。\n";
31        // PHPスクリプトがUTF-8で保存されている場合、リテラル文字列は通常UTF-8として扱われます。
32        // そのため、fwriteはUTF-8エンコードされたバイト列をファイルに書き込みます。
33        echo "書き込まれた内容は UTF-8 エンコーディングです。\n";
34    }
35
36    // ファイルリソースを閉じます。
37    // これを忘れると、リソースリークやファイルロックの原因となることがあります。
38    fclose($fileHandle);
39}
40
41// --- 実行例 ---
42
43// 出力するファイル名
44$outputFilename = 'output_utf8_example.txt';
45
46// 日本語を含むUTF-8文字列。
47// PHPのソースコードがUTF-8で保存されている場合、この文字列は内部的にUTF-8エンコーディングです。
48$textToWrite = "こんにちは、世界！ This is a test string with some UTF-8 characters like é, ü, ñ.";
49
50// 関数を呼び出してファイルに書き込みます。
51writeUtf8ToFile($outputFilename, $textToWrite);
52
53echo "ファイル '{$outputFilename}' が作成されました。内容を確認してください。\n";
54
55?>

PHPのfwrite関数は、開いているファイルに指定した文字列（バイト列）を書き込むために使用されます。

この関数を使うには、まずfopen関数などでファイルを開き、その結果として得られるファイルリソースをfwriteの最初の引数$streamに渡します。次に、ファイルに書き込みたい内容を文字列として第二引数$dataに指定します。fwriteは、この文字列のバイト列をそのままファイルに書き込みます。オプションの第三引数$lengthを指定すると、書き込むバイト数を制限できますが、通常は省略され、文字列全体が書き込まれます。

fwriteは、書き込みに成功した場合、実際にファイルに書き込まれたバイト数を整数で返します。書き込みに失敗した場合はfalseを返しますので、戻り値を確認してエラー処理を行うことが重要です。

文字コードに関してですが、fwrite関数自体は文字列の文字コード変換を行いません。そのため、ファイルに特定の文字コード（例えばUTF-8）で書き込みたい場合は、$data引数にその文字コードでエンコードされた文字列を渡す必要があります。サンプルコードのように、PHPスクリプトがUTF-8で保存されていれば、文字列リテラルはUTF-8として扱われるため、そのままfwriteに渡すことでUTF-8エンコードされた内容がファイルに書き込まれます。書き込み後は、必ずfclose関数でファイルリソースを閉じるようにしてください。

Copy
1<?php
2
3/**
4 * 指定されたファイルにデータを追記します。
5 * ファイルが存在しない場合は新規作成され、存在する場合は末尾にデータが追加されます。
6 *
7 * @param string $filename 追記対象のファイル名。
8 * @param string $data     ファイルに追記する文字列データ。
9 * @return bool 追記処理が成功した場合はtrue、失敗した場合はfalse。
10 */
11function appendToFile(string $filename, string $data): bool
12{
13    // ファイルを追記モード ('a') で開きます。
14    // 'a' モードは、ファイルが存在しない場合は作成し、存在する場合はファイルポインタを末尾に置きます。
15    // 読み書き両用で末尾に追加する場合は 'a+' を使用します。
16    $fileHandle = fopen($filename, 'a');
17
18    // ファイルが開けなかった場合のエラー処理
19    if ($fileHandle === false) {
20        echo "エラー: ファイル '{$filename}' を開けませんでした。パーミッションを確認してください。\n";
21        return false;
22    }
23
24    // fwrite() を使用してデータをファイルに書き込みます。
25    // PHP_EOL は現在のOSに応じた改行コードを追加し、データが新しい行に追記されるようにします。
26    // 成功した場合は書き込まれたバイト数、失敗した場合は false を返します。
27    $bytesWritten = fwrite($fileHandle, $data . PHP_EOL);
28
29    // 書き込みに失敗した場合のエラー処理
30    if ($bytesWritten === false) {
31        echo "エラー: ファイル '{$filename}' への書き込みに失敗しました。\n";
32        fclose($fileHandle); // ファイルが開かれている場合は閉じる
33        return false;
34    }
35
36    // ファイルを閉じます。
37    // ファイルを開いた後は、必ず閉じることが重要です。
38    fclose($fileHandle);
39
40    echo "ファイル '{$filename}' に {$bytesWritten} バイトを追記しました。\n";
41    return true;
42}
43
44// --- 以下はサンプルコードの実行部分です ---
45
46// 追記対象のファイル名を設定します。
47$targetFile = 'my_app_log.txt';
48
49// 追記するデータを用意します。
50$logEntry1 = '2023-10-27 10:00:00 - アプリケーションが起動しました。';
51$logEntry2 = '2023-10-27 10:05:30 - ユーザー "user123" がログインしました。';
52$logEntry3 = '2023-10-27 10:15:00 - データベースへの更新が完了しました。';
53
54echo "--- ファイルへの追記処理開始 ---\n\n";
55
56// 1回目のデータ追記を試みます。ファイルが存在しない場合は新規作成されます。
57if (appendToFile($targetFile, $logEntry1)) {
58    echo "最初のログエントリの追記に成功しました。\n\n";
59} else {
60    echo "最初のログエントリの追記に失敗しました。\n\n";
61}
62
63// 2回目のデータ追記を試みます。既存のファイルの末尾に追加されます。
64if (appendToFile($targetFile, $logEntry2)) {
65    echo "2番目のログエントリの追記に成功しました。\n\n";
66} else {
67    echo "2番目のログエントリの追記に失敗しました。\n\n";
68}
69
70// 3回目のデータ追記を試みます。
71if (appendToFile($targetFile, $logEntry3)) {
72    echo "3番目のログエントリの追記に成功しました。\n\n";
73} else {
74    echo "3番目のログエントリの追記に失敗しました。\n\n";
75}
76
77echo "--- ファイルへの追記処理終了 ---\n";
78
79// スクリプト実行後、`my_app_log.txt` ファイルが作成または更新され、
80// 上記のログエントリが新しい行として追加されていることを確認できます。
81
82?>

このサンプルコードは、PHPのfwrite関数を用いて、指定されたファイルにデータを追記する方法を示しています。fwrite関数は、開かれたファイル（ファイルリソース）に文字列データを書き込む際に使用され、主にログ記録やデータ保存といった場面で利用されます。

fwrite関数の第一引数にはfopen関数などで開いたファイルリソースを、第二引数にはファイルに書き込む文字列データを渡します。第三引数は書き込むバイト数を指定するものですが、省略された場合は文字列全体が書き込まれます。この関数は、書き込みに成功した場合は実際に書き込まれたバイト数を整数値で返し、失敗した場合はfalseを返します。

サンプルコードでは、appendToFileという独自の関数を定義し、ファイルへの追記処理をカプセル化しています。まず、fopen($filename, 'a')によってファイルを追記モードで開きます。'a'モードは、ファイルが存在しない場合は新規作成し、存在する場合はファイルポインタを末尾に移動させるため、常にデータの追記が行われます。ファイルが開けなかった場合はエラーメッセージを出力し、処理を終了します。

ファイルが正常に開かれた後、fwrite($fileHandle, $data . PHP_EOL)でデータを書き込みます。ここでPHP_EOLを付加することで、書き込まれるデータが自動的に改行され、新しい行に追記されるようになります。書き込みが失敗した場合もエラー処理を行い、最後にfclose($fileHandle)で開いたファイルを必ず閉じることで、リソースの解放とデータの破損防止を図っています。この一連の処理により、複数のログエントリがmy_app_log.txtファイルに順次追加されていく様子が確認できます。