【PHP8.x】localtime関数の使い方

<?php

/**
 * PHPのlocaltime関数の使用例。
 *
 * このスクリプトは、システムエンジニアを目指す初心者がlocaltime関数を理解し、
 * ローカル時刻情報を様々な形式で取得する方法を学ぶためのサンプルコードです。
 *
 * localtime関数は、ローカル時間を構成する要素（秒、分、時、日など）を含む配列を返します。
 * 引数によって、現在時刻以外の特定のタイムスタンプや、連想配列形式での取得も可能です。
 */

// 1. 引数なしで localtime() を呼び出す (現在のローカル時間、数値インデックス配列)
// 返される配列のインデックスは、C言語のstruct tm構造体に対応しています。
// 例: tm_sec (インデックス0), tm_min (インデックス1), tm_hour (インデックス2) など。
echo "--- 現在のローカル時間 (数値インデックス配列) ---\n";
$numericTime = localtime();
print_r($numericTime);
echo "\n";

// 2. 特定のタイムスタンプを指定して localtime() を呼び出す (数値インデックス配列)
// ここではPHPのtime()関数で現在のUNIXタイムスタンプを取得し、それを引数として渡しています。
$specificTimestamp = time();
echo "--- 特定のタイムスタンプ ({$specificTimestamp}) のローカル時間 (数値インデックス配列) ---\n";
$numericTimeFromTimestamp = localtime($specificTimestamp);
print_r($numericTimeFromTimestamp);
echo "\n";

// 3. 特定のタイムスタンプを指定し、連想配列として localtime() を呼び出す
// 第二引数に true を設定することで、'tm_sec', 'tm_min' などのキーを持つ連想配列が返されます。
echo "--- 特定のタイムスタンプ ({$specificTimestamp}) のローカル時間 (連想配列) ---\n";
$associativeTimeFromTimestamp = localtime($specificTimestamp, true);
print_r($associativeTimeFromTimestamp);
echo "\n";

// 連想配列のキーとその意味の例:
//   'tm_sec'   - 秒 (0-59)
//   'tm_min'   - 分 (0-59)
//   'tm_hour'  - 時 (0-23)
//   'tm_mday'  - 月の日 (1-31)
//   'tm_mon'   - 月 (0-11, 0が1月)
//   'tm_year'  - 年 (現在の年から1900を引いた値)
//   'tm_wday'  - 曜日 (0-6, 0が日曜日)
//   'tm_yday'  - 年間通算日 (0-365, 0が1月1日)
//   'tm_isdst' - 夏時間かどうかのフラグ (正の値:夏時間, 0:標準時, 負の値:不明)

?>

PHP 8.4のlocaltime関数は、ローカル時間の詳細な構成要素を配列として取得する関数です。

第一引数$timestampは、時刻を指定するためのUNIXタイムスタンプを受け取ります。この引数を省略するかnullとすると、現在のローカル時刻が使われます。第二引数$is_associativeにtrueを設定すると、戻り値の配列が連想配列となり、'tm_sec'や'tm_min'といった分かりやすいキーで各時刻要素にアクセスできます。false（デフォルト）の場合は数値インデックスの配列が返されます。

戻り値は、秒、分、時、日、月、年、曜日などの情報を含む配列です。例えば、連想配列形式では'tm_sec'が秒を、'tm_min'が分を、'tm_hour'が時を示します。月は0から11（0が1月）、年は1900年からの経過年数で表現される点に注意が必要です。これにより、現在の時刻や任意のタイムスタンプから、様々な形式で時刻情報を取得し、アプリケーションで活用することが可能になります。

<?php

/**
 * localtime() 関数の使用例を示す関数
 *
 * この関数は、現在時刻と指定した時刻のローカル時刻情報を
 * 添字配列と連想配列の両方の形式で取得し、表示します。
 */
function showLocaltimeExamples(): void
{
    // 実行環境のタイムゾーンを設定します (日本の場合は 'Asia/Tokyo')
    // これにより、意図したタイムゾーンでの時刻が取得されます。
    date_default_timezone_set('Asia/Tokyo');

    // --- 1. 現在時刻の取得 ---

    echo "--- 現在時刻のローカル時刻情報 ---\n";

    // 引数を省略すると、現在のサーバー時刻が使用され、
    // 戻り値は添字配列 (インデックスが数値の配列) になります。
    $currentTimeIndexed = localtime();
    echo "[添字配列の場合]\n";
    print_r($currentTimeIndexed);
    /*
     * 配列の要素 (キー => 意味):
     * [0] => tm_sec  (秒: 0-59)
     * [1] => tm_min  (分: 0-59)
     * [2] => tm_hour (時: 0-23)
     * [3] => tm_mday (日: 1-31)
     * [4] => tm_mon  (月: 0-11 ※0が1月)
     * [5] => tm_year (年: 1900年からの経過年数)
     * [6] => tm_wday (曜日: 0-6 ※0が日曜日)
     * [7] => tm_yday (年初からの日数: 0-365)
     * [8] => tm_isdst(夏時間フラグ: 0, 1, or -1)
     */

    // 第2引数に true を指定すると、戻り値が連想配列 (キーが文字列の配列) になります。
    // こちらの方が各要素が何を表すか分かりやすくなります。
    $currentTimeAssociative = localtime(null, true);
    echo "\n[連想配列の場合]\n";
    print_r($currentTimeAssociative);


    // --- 2. 指定した日時の取得 ---

    echo "\n--- 指定した日時のローカル時刻情報 ---\n";

    // 特定の日時 (例: 2025年1月1日 12時30分45秒) のUNIXタイムスタンプを生成します。
    $timestamp = mktime(12, 30, 45, 1, 1, 2025);
    echo "対象タイムスタンプ: " . $timestamp . " (2025-01-01 12:30:45)\n";

    // 生成したタイムスタンプを第1引数に渡して、その日時の情報を取得します。
    $specificTime = localtime($timestamp, true);
    print_r($specificTime);


    // --- 3. 取得した情報から日付文字列を生成 ---

    // 連想配列の各要素を使って、人間が読みやすい形式の日付文字列を作成します。
    // 年は1900を、月は1を足す必要がある点に注意してください。
    $year  = 1900 + $specificTime['tm_year'];
    $month = 1 + $specificTime['tm_mon'];
    $day   = $specificTime['tm_mday'];
    $hour  = $specificTime['tm_hour'];
    $min   = $specificTime['tm_min'];
    $sec   = $specificTime['tm_sec'];

    $formattedDate = sprintf(
        '%d年%02d月%02d日 %02d時%02d分%02d秒',
        $year,
        $month,
        $day,
        $hour,
        $min,
        $sec
    );

    echo "\nフォーマットした日付文字列: " . $formattedDate . "\n";
}

// 作成した関数を実行します。
showLocaltimeExamples();

?>

localtime()関数は、サーバーで設定されているタイムゾーンに基づいたローカル時刻の情報を配列として取得するために使用します。

この関数には2つの引数を指定できます。第1引数にはUNIXタイムスタンプを整数で渡します。この引数を省略、またはnullを渡した場合は、現在のサーバー時刻が使用されます。第2引数にtrueを指定すると、戻り値の配列が連想配列になります。デフォルトはfalseで、この場合は添字配列が返されます。キーが'tm_hour'（時）のような文字列になる連想配列の方が、各要素が何を表しているか分かりやすいため便利です。

戻り値は、秒、分、時、日、月、年、曜日などの時刻要素を含む配列です。ただし、年は「1900年からの経過年数」、月は「0から始まる数値（0が1月）」で返される点に注意が必要です。日付として利用するには、年に1900を、月に1を足すなどの計算が必要になります。

サンプルコードでは、まずdate_default_timezone_set()でタイムゾーンを設定した後、現在時刻と指定した日時の情報を取得しています。そして、取得した連想配列の各要素を使い、sprintf()関数で人間が読みやすい形式の日付文字列を生成する方法を示しています。

<?php

/**
 * localtime関数の基本的な使い方をデモンストレーションします。
 *
 * この関数は、現在または指定されたタイムスタンプのローカル時刻情報を取得します。
 * 結果は配列で返され、引数 $is_associative によってインデックス配列または連想配列になります。
 *
 * 戻り値の配列要素は以下の意味を持ちます (連想配列の場合のキー):
 *   tm_sec   (秒, 0-59)
 *   tm_min   (分, 0-59)
 *   tm_hour  (時, 0-23)
 *   tm_mday  (月の日, 1-31)
 *   tm_mon   (月, 0-11. 0は1月, 11は12月)
 *   tm_year  (年, 1900年からの経過年数)
 *   tm_wday  (曜日, 0-6. 0は日曜日, 1は月曜日...)
 *   tm_yday  (通日, 0-365. 0は1月1日)
 *   tm_isdst (夏時間フラグ. 1=夏時間, 0=通常時間, -1=不明)
 */
function demonstrateLocaltimeUsage(): void
{
    echo "--- localtime() 関数の基本的な使い方 ---" . PHP_EOL . PHP_EOL;

    // 1. 引数なしで現在のローカル時刻をインデックス配列で取得
    //    $timestamp はデフォルトで null (現在の時刻) に、 $is_associative は false (インデックス配列) になります。
    echo "1. 現在時刻をインデックス配列で取得:" . PHP_EOL;
    $indexedTime = localtime();
    print_r($indexedTime);
    echo PHP_EOL;

    // 2. 現在のローカル時刻を連想配列で取得
    //    time() で現在のUNIXタイムスタンプを取得し、$is_associative を true に設定します。
    echo "2. 現在時刻を連想配列で取得:" . PHP_EOL;
    $associativeTime = localtime(time(), true);
    print_r($associativeTime);
    echo PHP_EOL;

    // 3. 特定のタイムスタンプのローカル時刻をインデックス配列で取得
    //    mktime() を使用して特定の年月日時のタイムスタンプを生成します。
    echo "3. 2023年1月1日 12時30分00秒 のローカル時刻をインデックス配列で取得:" . PHP_EOL;
    // mktime(hour, minute, second, month, day, year) の順で引数を指定
    $specificTimestamp = mktime(12, 30, 0, 1, 1, 2023);
    $specificIndexedTime = localtime($specificTimestamp);
    print_r($specificIndexedTime);
    echo PHP_EOL;

    // 4. 特定のタイムスタンプのローカル時刻を連想配列で取得
    //    $is_associative = true を組み合わせて使用します。
    echo "4. 2023年1月1日 12時30分00秒 のローカル時刻を連想配列で取得:" . PHP_EOL;
    $specificAssociativeTime = localtime($specificTimestamp, true);
    print_r($specificAssociativeTime);
    echo PHP_EOL;

    echo "--- 連想配列の要素へのアクセス例 (現在時刻) ---" . PHP_EOL;
    // 連想配列のキーを使って個々の時刻情報にアクセスできます。
    // tm_year は1900年からの経過年数なので、現在の年を取得するには +1900 します。
    // tm_mon は0から始まる月 (0=1月, 11=12月) なので、実際の月を取得するには +1 します。
    // tm_yday は0から始まる通日 (0=1月1日) なので、実際の日数を取得するには +1 します。
    echo "年: " . ($associativeTime['tm_year'] + 1900) . PHP_EOL;
    echo "月: " . ($associativeTime['tm_mon'] + 1) . PHP_EOL;
    echo "日: " . $associativeTime['tm_mday'] . PHP_EOL;
    echo "時: " . $associativeTime['tm_hour'] . PHP_EOL;
    echo "分: " . $associativeTime['tm_min'] . PHP_EOL;
    echo "秒: " . $associativeTime['tm_sec'] . PHP_EOL;
    echo "曜日: " . $associativeTime['tm_wday'] . " (0=日曜日, 1=月曜日, ..., 6=土曜日)" . PHP_EOL;
    echo "通日: " . ($associativeTime['tm_yday'] + 1) . "日目" . PHP_EOL;
    echo "夏時間フラグ: " . $associativeTime['tm_isdst'] . PHP_EOL;
    echo PHP_EOL;
}

// 関数を実行してデモンストレーションを開始します。
demonstrateLocaltimeUsage();

PHPのlocaltime関数は、現在または指定されたUNIXタイムスタンプに基づいて、ローカル時刻の詳細情報を配列として取得する機能を提供します。最初の引数$timestampを省略すると、現在の時刻が自動的に使用されます。time()関数などで取得した任意のタイムスタンプを渡すことで、特定の時点の時刻情報を取得することも可能です。

2番目の引数$is_associativeにtrueを設定すると、戻り値は「tm_sec（秒）」や「tm_hour（時）」のような、意味が分かりやすいキーを持つ連想配列になります。この引数を省略するかfalseを指定した場合、結果は数値インデックスの配列として返されます。

戻り値の配列には、秒、分、時、月の日、月、年、曜日、通日、夏時間フラグなど、非常に詳細な時刻情報が含まれています。特に、月（tm_mon）は0が1月、年（tm_year）は1900年からの経過年数、通日（tm_yday）は0が1月1日として表現される点に注意が必要です。これらの情報を用いることで、日付や時刻に関する様々な処理を正確かつ柔軟に実装できます。

<?php

/**
 * localtime()で取得したローカル時刻の情報を、人間が読みやすい文字列に変換します。
 *
 * この関数は、PHPの `localtime()` を使って現在のサーバー時刻を取得し、
 * それを "YYYY-MM-DD HH:MM:SS" 形式の文字列にフォーマットして返します。
 *
 * @return string フォーマットされた日付時刻文字列 (例: "2023-10-27 10:30:55")
 */
function getFormattedLocalTime(): string
{
    // 現在のタイムスタンプを取得します。
    $timestamp = time();

    // localtime() を使って、サーバーのローカル時刻情報を取得します。
    // 第2引数を true にすると、各要素に名前がついた連想配列で結果が返され、扱いやすくなります。
    $localTimeArray = localtime($timestamp, true);

    // localtime()が返す配列の値を、実際の年月に変換します。
    // 'tm_year' は 1900年からの経過年数なので、1900 を加算します。
    $year = $localTimeArray['tm_year'] + 1900;
    // 'tm_mon' は 0 (1月) から 11 (12月) の範囲なので、1 を加算します。
    $month = $localTimeArray['tm_mon'] + 1;

    // sprintf() を使って、各数値を指定のフォーマットの文字列に整形します。
    // %04d: 4桁の整数。足りない桁は0で埋める (年)。
    // %02d: 2桁の整数。足りない桁は0で埋める (月, 日, 時, 分, 秒)。
    return sprintf(
        "%04d-%02d-%02d %02d:%02d:%02d",
        $year,
        $month,
        $localTimeArray['tm_mday'], // 日
        $localTimeArray['tm_hour'], // 時
        $localTimeArray['tm_min'],  // 分
        $localTimeArray['tm_sec']   // 秒
    );
}

// 作成した関数を呼び出し、結果を出力します。
$dateTimeString = getFormattedLocalTime();
echo $dateTimeString . PHP_EOL;

?>

このサンプルコードは、PHPのlocaltime()関数を使い、サーバーのローカル時刻情報を取得して、人間が読みやすい日付時刻文字列に変換する方法を示しています。

localtime()関数は、引数で指定されたUnixタイムスタンプを基に、サーバーに設定されたタイムゾーンの時刻情報を配列で返します。第1引数にtime()で取得した現在のタイムスタンプを、第2引数にtrueを指定すると、戻り値が連想配列になります。これにより、'tm_hour'（時）や'tm_min'（分）のように、各要素へ名前でアクセスできるためコードが分かりやすくなります。

localtime()が返す配列の年には注意が必要です。'tm_year'キーの値は1900年からの経過年数を、'tm_mon'キーの値は0（1月）から11（12月）までの数値を表します。そのため、正しい年月日を得るには、サンプルコードのようにそれぞれ1900と1を加算する調整が必要です。

最後に、これらの数値をsprintf()関数で整形し、「YYYY-MM-DD HH:MM:SS」形式の文字列を生成しています。このように、localtime()はサーバーの時刻を詳細な要素に分解して取得したい場合に便利な関数です。