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

Copy
1<?php
2
3/**
4 * touch() 関数の基本的な使用例。
5 * ファイルが存在しない場合は新規作成し、存在する場合はアクセス時刻と変更時刻を現在の時刻に更新します。
6 */
7
8// 操作対象のファイル名を定義します。
9// このスクリプトと同じディレクトリにファイルが作成されます。
10$filename = 'my_example_file.txt';
11
12echo "ファイル '{$filename}' の操作を開始します。" . PHP_EOL;
13
14// touch() 関数を呼び出し、ファイルの作成または更新を試みます。
15// 成功した場合は true、失敗した場合は false を返します。
16if (touch($filename)) {
17    echo "成功: ファイル '{$filename}' が正常に作成または更新されました。" . PHP_EOL;
18    
19    // オプション: ファイルが実際に存在するか確認します。
20    if (file_exists($filename)) {
21        echo "確認: ファイル '{$filename}' は現在ディスク上に存在します。" . PHP_EOL;
22    }
23    
24    // 注意: このサンプルコードによって作成されたファイルを削除するには、
25    // 以下の `unlink()` 関数の行のコメントアウトを外し、再度スクリプトを実行してください。
26    /*
27    if (unlink($filename)) {
28        echo "クリーンアップ: ファイル '{$filename}' が削除されました。" . PHP_EOL;
29    } else {
30        echo "警告: ファイル '{$filename}' の削除に失敗しました。" . PHP_EOL;
31    }
32    */
33
34} else {
35    echo "エラー: ファイル '{$filename}' の作成または更新に失敗しました。" . PHP_EOL;
36    echo "原因として、書き込み権限がないか、指定されたパスが無効な可能性があります。" . PHP_EOL;
37}
38
39echo "処理を終了します。" . PHP_EOL;
40
41?>

PHPのtouch関数は、ファイルが存在しない場合は新しく作成し、すでに存在する場合はそのファイルの最終変更時刻と最終アクセス時刻を更新するために使用される関数です。

最初の引数$filenameには、操作したいファイルのパスを文字列で指定します。この引数は必須です。オプションの引数として、$mtimeで最終変更時刻を、$atimeで最終アクセス時刻をUNIXタイムスタンプ形式で指定できます。これらのオプションを省略した場合、現在時刻が設定されます。

この関数は、処理が成功した場合はtrueを、ファイルが存在しないか書き込み権限がないなど、何らかの理由で失敗した場合はfalseをブール値として返します。

提供されたサンプルコードでは、my_example_file.txtというファイルを指定してtouch関数を呼び出しています。これにより、ファイルが存在しない場合は新規に作成され、すでに存在する場合はタイムスタンプが現在の時刻に更新されます。if文でtouch関数の戻り値をチェックすることで、ファイル操作が成功したか失敗したかを判別し、その結果に応じたメッセージを出力しています。これにより、プログラムはファイル操作の成否を正確に把握し、次の処理へ進むことができます。ファイルシステムの操作において非常に基本的な、かつ重要な関数の一つです。

Copy
1<?php
2
3/**
4 * 指定されたファイルのタイムスタンプを更新します。
5 * ファイルが存在しない場合は新しく作成されます。
6 *
7 * この関数は、`touch`関数を使用してファイルの最終アクセス時刻 (atime) と最終変更時刻 (mtime) を更新します。
8 * 主にファイルの「更新日」などの情報を変更したい場合や、ファイルが存在しない場合に空のファイルを作成したい場合に使用されます。
9 *
10 * @param string $filename 更新または作成するファイルのパス。
11 * @param ?int $mtime オプション。ファイルの変更時刻として設定するUnixタイムスタンプ。
12 *                     nullの場合、現在のシステム時刻が使用されます。
13 * @param ?int $atime オプション。ファイルのアクセス時刻として設定するUnixタイムスタンプ。
14 *                     nullの場合、現在のシステム時刻が使用されます。
15 * @return bool タイムスタンプの更新またはファイルの作成が成功した場合true、それ以外はfalse。
16 */
17function updateFileTimestamp(string $filename, ?int $mtime = null, ?int $atime = null): bool
18{
19    // PHPの組み込み関数 `touch()` を使用して、ファイルのタイムスタンプを更新します。
20    // この関数は、ファイルが存在しない場合は指定された名前で新しい空のファイルを作成します。
21    // ファイルが存在する場合は、そのファイルの最終変更時刻と最終アクセス時刻を更新します。
22    // 成功した場合は true、失敗した場合は false を返します。
23    $success = touch($filename, $mtime, $atime);
24
25    if ($success) {
26        echo "ファイル '{$filename}' のタイムスタンプを更新しました (または新規作成しました)。\n";
27        // タイムスタンプが実際に変更されたか確認するには、`filemtime()` や `fileatime()` 関数を使用できます。
28        // 例: echo "現在の変更時刻: " . date('Y-m-d H:i:s', filemtime($filename)) . "\n";
29    } else {
30        echo "ファイル '{$filename}' のタイムスタンプ更新または作成に失敗しました。\n";
31        // 失敗の原因としては、ファイルパスが不正、ディレクトリへの書き込み権限がない、などの可能性があります。
32    }
33
34    return $success;
35}
36
37// --- サンプルコードの実行 ---
38
39// 1. テスト用のファイル名を定義します。
40$testFilename = 'project_status_report.txt';
41
42echo "--- ファイルが存在しない場合のテスト ---\n";
43// まずファイルが存在しない状態で関数を呼び出し、新規作成とタイムスタンプ設定を試みます。
44// $mtimeと$atimeをnull（省略）にすることで、現在のシステム時刻が設定されます。
45updateFileTimestamp($testFilename);
46
47// タイムスタンプの差が分かりやすいように、処理の間に少し待機します。
48sleep(1);
49
50echo "\n--- ファイルが存在する場合のテスト (タイムスタンプ更新) ---\n";
51// 次に、既存のファイルに対して関数を呼び出し、タイムスタンプを更新します。
52// 再び$mtimeと$atimeを省略することで、現在のシステム時刻にタイムスタンプが更新されます。
53updateFileTimestamp($testFilename);
54
55// オプション: 特定の未来の時刻にタイムスタンプを設定する例
56// 例えば、現在時刻から24時間後の時刻を設定してみます。
57$futureTimestamp = time() + (24 * 60 * 60); // Unixタイムスタンプは秒単位
58echo "\n--- 特定の未来の時刻にタイムスタンプを設定するテスト ---\n";
59if (updateFileTimestamp($testFilename, $futureTimestamp)) {
60    echo "設定された変更時刻: " . date('Y-m-d H:i:s', filemtime($testFilename)) . "\n";
61}
62
63// テスト終了後、作成されたファイルを削除してクリーンアップします。
64if (file_exists($testFilename)) {
65    unlink($testFilename); // `unlink()` はファイルを削除する関数です。
66    echo "\nテストファイル '{$testFilename}' を削除しました。\n";
67}

PHPのtouch関数は、指定されたファイルの最終変更時刻（mtime）と最終アクセス時刻（atime）を更新するために使用します。もし指定したファイルが存在しない場合は、新しく空のファイルを作成する機能も持っています。

この関数は、第一引数に更新または作成したいファイルのパスを文字列で指定します。これは必須の引数です。第二引数 $mtime と第三引数 $atime はオプションで、それぞれファイルの変更時刻とアクセス時刻をUnixタイムスタンプという形式で指定します。これらの引数を省略するかnullとすると、現在のシステム時刻が設定されます。関数の実行が成功した場合はtrueを、失敗した場合はfalseを戻り値として返します。

サンプルコードでは、まず存在しないファイルに対してtouch関数を呼び出し、新しいファイルが作成されることと、そのタイムスタンプが現在の時刻に設定されることを示しています。次に、作成済みのファイルに対して再度関数を呼び出し、タイムスタンプが現在の時刻に更新される様子を確認できます。さらに、特定の未来の時刻を引数に指定することで、ファイル作成時や更新時に任意の時刻をタイムスタンプとして設定できる例も紹介しており、ファイルの更新日管理や空のファイル作成に役立ちます。

Copy
1<?php
2
3/**
4 * PHPのtouch()関数の基本的な使用方法と、ファイル作成に失敗する一般的なケースを示します。
5 *
6 * システムエンジニアを目指す初心者向けに、成功例と失敗例、および失敗の理由を解説します。
7 */
8function demonstrateTouchFailure(): void
9{
10    // テスト用のディレクトリを作成します。現在のスクリプトがあるディレクトリ内に作成します。
11    $testDir = __DIR__ . '/touch_test_files';
12    if (!is_dir($testDir)) {
13        // mkdir の第三引数 `true` は、必要に応じて親ディレクトリも作成することを意味します。
14        // 第四引数 `0755` はディレクトリのパーミッション（読み書き実行権限）です。
15        if (!mkdir($testDir, 0755, true)) {
16            echo "エラー: テストディレクトリ '{$testDir}' の作成に失敗しました。権限を確認してください。\n";
17            return;
18        }
19        echo "情報: テストディレクトリ '{$testDir}' を作成しました。\n";
20    }
21
22    // --- 成功するケース ---
23    // 存在するディレクトリ内にファイルを「touch」します。
24    // ファイルが存在しない場合は新規作成され、存在する場合は最終アクセス・更新日時が更新されます。
25    $successFilename = $testDir . '/success_file.txt';
26    echo "\n--- 成功ケース: 存在するディレクトリにファイルを操作 ---\n";
27    echo "試行ファイル名: '{$successFilename}'\n";
28    if (touch($successFilename)) {
29        echo "結果: 成功。ファイル '{$successFilename}' が作成されたか、タイムスタンプが更新されました。\n";
30    } else {
31        // ここに到達することは稀ですが、ディスクフルや権限問題で失敗する可能性はあります。
32        echo "結果: 失敗。予期せぬエラーが発生しました。\n";
33    }
34
35    // --- 失敗するケース ---
36    // touch() 関数が失敗する一般的なケースの一つは、
37    // ファイルを作成しようとするパスの「親ディレクトリ」が存在しない場合です。
38    // touch() は `mkdir -p` のように、存在しない親ディレクトリを自動的に作成しません。
39    $nonExistentParentDir = $testDir . '/non_existent_subdir';
40    $failFilename = $nonExistentParentDir . '/fail_file.txt';
41    echo "\n--- 失敗ケース: 存在しない親ディレクトリにファイルを作成しようとする ---\n";
42    echo "試行ファイル名: '{$failFilename}'\n";
43    if (touch($failFilename)) {
44        // このコードブロックに到達した場合、何らかの予期せぬ成功（例: ディレクトリ名がファイル名と誤認識されたなど）
45        // または、サンプルコードの意図とは異なる環境設定が発生しています。
46        echo "結果: 成功。しかし、これは通常発生しないはずです。パスを確認してください。\n";
47    } else {
48        echo "結果: 失敗。親ディレクトリ '{$nonExistentParentDir}' が存在しないため、ファイルを作成できませんでした。\n";
49        echo "ヒント: ファイルを作成する前に、`mkdir('{$nonExistentParentDir}', 0755, true);` のように親ディレクトリを先に作成する必要があります。\n";
50    }
51
52    // --- 後処理（テストで作成したファイルやディレクトリをクリーンアップ） ---
53    echo "\n--- 後処理 ---\n";
54    // 成功ケースで作成されたファイルを削除
55    if (file_exists($successFilename)) {
56        unlink($successFilename);
57        echo "情報: ファイル '{$successFilename}' を削除しました。\n";
58    }
59
60    // テストディレクトリが空であれば削除
61    // scandir は `.` (カレントディレクトリ) と `..` (親ディレクトリ) を常に含みます。
62    // そのため、実ファイルがなければ要素数は2になります。
63    if (is_dir($testDir) && count(array_diff(scandir($testDir), ['.', '..'])) === 0) {
64        rmdir($testDir);
65        echo "情報: テストディレクトリ '{$testDir}' を削除しました。\n";
66    } else if (is_dir($testDir)) {
67        echo "警告: テストディレクトリ '{$testDir}' にファイルが残っているため、削除できませんでした。\n";
68    }
69}
70
71// 関数を実行してデモンストレーションを開始します。
72demonstrateTouchFailure();
73
74?>

PHPのtouch関数は、ファイルが存在しない場合は指定された名前で空のファイルを新規作成し、ファイルが既に存在する場合はそのファイルの最終更新日時と最終アクセス日時を更新する機能を提供します。

第一引数$filenameには、操作対象となるファイルパスを文字列で指定します。オプションの第二引数$mtimeと第三引数$atimeは、それぞれファイルの最終更新日時と最終アクセス日時をUNIXタイムスタンプで指定するために使用します。これらを省略した場合は、現在の時刻が設定されます。関数の戻り値はbool型で、操作が成功すればtrue、失敗すればfalseを返します。

サンプルコードでは、まず成功例として、存在するディレクトリ内にtouchでファイルを新規作成する様子を示しています。このケースではファイルが正常に作成され、trueが返されます。

次に失敗例として、存在しない親ディレクトリの中にファイルをtouchで作成しようとするケースを提示しています。touch関数は、ファイルを作成しようとするパスの途中に存在する親ディレクトリがなければ、そのディレクトリを自動的に作成しません。そのため、この操作は失敗し、falseが返されます。このような場合、touchを実行する前にmkdir関数などで親ディレクトリを事前に作成しておく必要があります。

その他にも、ファイルやディレクトリへの書き込み権限がない場合や、ディスク容量が不足している場合などにもtouch関数は失敗する可能性があります。

Copy
1<?php
2
3/**
4 * PHPのtouch関数を使用してファイルを操作し、
5 * その成功・失敗がファイルシステム権限にどのように関連するかを示すサンプルコードです。
6 *
7 * touch関数は以下の目的で使用されます:
8 * 1. 指定されたファイルが存在しない場合、新しい空のファイルを作成する。
9 * 2. 指定されたファイルが存在する場合、そのファイルのアクセス時刻と更新時刻（タイムスタンプ）を
10 *    現在の時刻（または指定された時刻）に更新する。
11 *
12 * ファイルの作成や更新には、対象のディレクトリやファイルに対する適切な書き込み権限が
13 * PHPプロセスに付与されている必要があります。
14 */
15
16// 1. ファイルを新規作成する基本的な例
17$filename = 'simple_touch_file.txt';
18echo "--- ファイル新規作成の試み ---\n";
19
20// 既存のファイルを削除して、常に新しい状態から始める
21if (file_exists($filename)) {
22    unlink($filename);
23    echo "既存のファイル '{$filename}' を削除しました。\n";
24}
25
26// touch関数でファイルを新規作成
27if (touch($filename)) {
28    echo "成功: ファイル '{$filename}' が作成されました。\n";
29    echo "  更新時刻: " . date('Y-m-d H:i:s', filemtime($filename)) . "\n";
30    // 新規作成されたファイルの初期権限は、PHPスクリプトを実行しているユーザーのumask設定に依存します。
31    // 例えば、umaskが0022の場合、ファイル権限は0644（所有者読み書き、グループ/その他読み取り）になります。
32    echo "  初期権限: " . substr(sprintf('%o', fileperms($filename)), -4) . " (umask設定に依存)\n";
33} else {
34    echo "失敗: ファイル '{$filename}' の作成に失敗しました。\n";
35    echo "  考えられる原因: PHPプロセスが現在のディレクトリに書き込み権限を持っていない可能性があります。\n";
36}
37
38echo "\n--- 権限不足または存在しないパスによる失敗例 ---\n";
39// 存在しないディレクトリ内のファイル作成を試みます。
40// これは、ディレクトリの作成権限がない場合と同様にtouchを失敗させます。
41$invalidPath = './non_existent_directory/unwritable_target.txt';
42
43// touch関数が失敗した際にPHPが出す警告メッセージを捕捉し、より分かりやすい説明を追加するためのエラーハンドラ
44set_error_handler(function ($errno, $errstr) use ($invalidPath) {
45    // touch関数に関連する警告 (E_WARNING) のみを処理
46    if (strpos($errstr, $invalidPath) !== false && ($errno === E_WARNING)) {
47        echo "捕捉されたPHP警告: '{$errstr}'\n";
48        echo "  この警告は、指定されたディレクトリ 'non_existent_directory' が存在しないか、\n";
49        echo "  またはPHPプロセスがそのディレクトリ（または親ディレクトリ）に書き込み権限を持っていないことを示唆しています。\n";
50        return true; // これによりPHPのデフォルトエラーハンドラは実行されない
51    }
52    return false; // その他のエラーはPHPのデフォルトハンドラに任せる
53});
54
55echo "存在しないディレクトリにファイルを生成しようとしています: '{$invalidPath}'\n";
56if (touch($invalidPath)) {
57    echo "警告: ファイル '{$invalidPath}' が意図せず作成されました。環境を確認してください。\n";
58} else {
59    echo "期待通り: ファイル '{$invalidPath}' の作成に失敗しました。\n";
60    echo "  上記の警告メッセージを参照し、ディレクトリの存在と、PHPプロセスの権限を確認してください。\n";
61}
62
63// エラーハンドラを元の状態に戻す
64restore_error_handler();
65
66// 後処理: サンプルで作成したファイルを削除
67if (file_exists($filename)) {
68    unlink($filename);
69    echo "\n後処理: 作成したファイル '{$filename}' を削除しました。\n";
70}
71
72// 失敗例でファイルが意図せず作成された場合（通常は発生しない）の削除
73if (file_exists($invalidPath)) {
74    unlink($invalidPath);
75}

PHPのtouch関数は、ファイルシステム上でファイルの「タイムスタンプ」を操作するための重要な機能です。この関数には主に二つの役割があります。一つは、指定されたファイルが存在しない場合に、新しい空のファイルを新規作成することです。もう一つは、指定されたファイルが既に存在する場合に、そのファイルの最終更新時刻（mtime）と最終アクセス時刻（atime）を、現在の時刻、または引数で指定された時刻に更新することです。

touch関数は、string $filenameで操作対象のファイルパスを必須で指定します。オプションで?int $mtimeと?int $atime引数を使用すると、更新時刻とアクセス時刻をUNIXタイムスタンプ形式で個別に設定できます。処理が成功した場合はブール値のtrueを、失敗した場合はfalseを戻り値として返します。

この関数によるファイルの作成やタイムスタンプの更新は、PHPプロセスが対象のディレクトリやファイルに対して適切な「書き込み権限」を持っていることが必須です。サンプルコードでは、ファイルを正常に作成できる基本的なケースと、権限が不足している、または指定されたディレクトリが存在しないためにファイル作成が失敗するケースを提示しています。失敗時にはtouch関数がfalseを返し、PHPが警告メッセージを出力することがあり、これらの情報はファイルシステム権限の問題を示唆しています。ファイル操作における権限の管理は、システムエンジニアにとって不可欠な知識となります。