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

<?php

/**
 * mktime 関数の使用例：指定した日時に対応する Unix タイムスタンプを取得する.
 */

// 現在の日付で、時間を指定
$timestamp1 = mktime(10, 30, 0); // 10時30分0秒

// 特定の日付を指定
$timestamp2 = mktime(0, 0, 0, 12, 25, 2024); // 2024年12月25日0時0分0秒

// エラー処理：引数が不正な場合
$timestamp3 = mktime(25, 0, 0, 1, 1, 2023); // 存在しない時間を指定

if ($timestamp3 === false) {
    echo "mktime() は無効な日付のため、FALSE を返しました。\n";
}

// 結果を出力
echo "現在の日の10時30分のタイムスタンプ: " . $timestamp1 . "\n";
echo "2024年12月25日のタイムスタンプ: " . $timestamp2 . "\n";

mktime関数は、指定された日時をUnixタイムスタンプ（1970年1月1日午前0時0分0秒からの経過秒数）に変換するPHPの関数です。システム開発において、特定の日時を数値として扱う場合に非常に便利です。

引数は、時間($hour)、分($minute)、秒($second)、月($month)、日($day)、年($year)の順に指定します。これらの引数はすべて整数型（int）です。ただし、$minute、$second、$month、$day、$yearはオプションの引数であり、省略可能です。省略された場合は、現在の日時が使用されます。

このサンプルコードでは、mktime関数を使用して、現在の日付の10時30分のタイムスタンプと、2024年12月25日のタイムスタンプを取得しています。

また、引数に存在しない日時（例えば25時）を指定した場合、mktime関数はFALSEを返します。サンプルコードでは、このエラー処理の例も示しており、FALSEが返された場合にエラーメッセージを表示する処理を実装しています。

mktime関数の戻り値は、正常に日時が変換された場合は整数型のUnixタイムスタンプを返し、エラーが発生した場合はFALSEを返します。戻り値の型はint|falseと定義されています。この戻り値を利用して、日付処理が成功したかを確認できます。

<?php

/**
 * mktime() と strtotime() 関数の違いと使い方を示すサンプルコード。
 *
 * mktime() は、指定された日付と時刻の各要素（年、月、日、時、分、秒）を数値で直接指定して
 * UNIXタイムスタンプ（1970年1月1日 00:00:00 UTCからの秒数）を生成します。
 *
 * strtotime() は、人間が読める形式の文字列（例: "2023-10-27 15:30:00", "next monday"）を解析して
 * UNIXタイムスタンプを生成します。より柔軟な日付/時刻表現に対応します。
 */
function demonstrateTimeComparison(): void
{
    // UNIXタイムスタンプを生成する対象の日付と時刻
    $year   = 2023;
    $month  = 10;
    $day    = 27;
    $hour   = 15;
    $minute = 30;
    $second = 0;

    echo "--- mktime() の使用例 ---\n";
    // mktime(hour, minute, second, month, day, year) の順に引数を指定
    // 指定された数値からUNIXタイムスタンプを生成
    $timestampMktime = mktime($hour, $minute, $second, $month, $day, $year);

    if ($timestampMktime !== false) {
        echo "mktime() で生成されたUNIXタイムスタンプ: " . $timestampMktime . "\n";
        echo "変換された日付と時刻: " . date('Y-m-d H:i:s', $timestampMktime) . "\n\n";
    } else {
        echo "mktime() の実行に失敗しました。\n\n";
    }

    echo "--- strtotime() の使用例 ---\n";
    // 人間が読める形式の文字列からUNIXタイムスタンプを生成
    // 様々な日付/時刻フォーマットに対応
    $dateTimeString = "{$year}-{$month}-{$day} {$hour}:{$minute}:{$second}";
    $timestampStrtotime = strtotime($dateTimeString);

    if ($timestampStrtotime !== false) {
        echo "strtotime() で生成されたUNIXタイムスタンプ: " . $timestampStrtotime . "\n";
        echo "変換された日付と時刻: " . date('Y-m-d H:i:s', $timestampStrtotime) . "\n\n";
    } else {
        echo "strtotime() の実行に失敗しました。\n\n";
    }

    echo "--- 結果の比較 ---\n";
    // 両方の関数が同じUNIXタイムスタンプを生成することを確認
    if ($timestampMktime !== false && $timestampStrtotime !== false) {
        if ($timestampMktime === $timestampStrtotime) {
            echo "mktime() と strtotime() は同じUNIXタイムスタンプを生成しました。\n";
            echo "違いは、mktime() が個々の数値引数を取るのに対し、strtotime() は文字列を解析する点です。\n";
        } else {
            echo "mktime() と strtotime() で生成されたUNIXタイムスタンプは異なります（通常は同じになります）。\n";
        }
    } else {
        echo "片方または両方の関数が失敗したため、比較できませんでした。\n";
    }
}

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

PHPのmktime()関数は、指定された年、月、日、時、分、秒の各要素を数値で受け取り、UNIXタイムスタンプを生成する関数です。UNIXタイムスタンプとは、1970年1月1日 00:00:00 UTCからの経過秒数を整数で表したものです。引数には $hour, $minute, $second, $month, $day, $year の順に整数で時刻と日付の各要素を渡します。成功した場合はUNIXタイムスタンプ（整数）を返し、日付や時刻として不正な値が指定されるなど失敗した場合は false を返します。

この関数は、strtotime()関数と比較されることがよくあります。mktime()が日付や時刻の各要素を個別の数値で直接指定するのに対し、strtotime()は「2023-10-27 15:30:00」のような人間が読める形式の文字列を解析してUNIXタイムスタンプを生成します。

サンプルコードでは、特定の日時をmktime()に数値として渡し、また同じ日時を文字列としてstrtotime()に渡して、それぞれUNIXタイムスタンプを生成しています。最終的に両関数が同じUNIXタイムスタンプを生成することを示し、それぞれの使い方と目的の違いを明確にしています。mktime()は要素が明確な場合に適しており、strtotime()はより柔軟な文字列解析が必要な場合に便利です。

<?php

/**
 * mktime 関数の使用例：指定した日時に対応する Unix タイムスタンプを取得する.
 */

// 現在の日付で、時間を指定する
$timestamp1 = mktime(10, 30, 0); // 10時30分0秒
echo "現在の日の10時30分のタイムスタンプ: " . $timestamp1 . PHP_EOL;

// 特定の日付と時間を指定する
$timestamp2 = mktime(0, 0, 0, 12, 31, 2024); // 2024年12月31日0時0分0秒
echo "2024年12月31日のタイムスタンプ: " . $timestamp2 . PHP_EOL;

// 引数を省略した場合の動作
$timestamp3 = mktime(); // 引数省略時は現在時刻
echo "引数省略時のタイムスタンプ: " . $timestamp3 . PHP_EOL;

// mktimeはタイムスタンプを返す。失敗した場合はfalseを返す
$timestamp4 = mktime(30, 0, 0, 1, 1, 2024); // 存在しない時間を指定
if ($timestamp4 === false) {
    echo "mktime が失敗しました" . PHP_EOL;
} else {
    echo "2024年1月1日の30時のタイムスタンプ: " . $timestamp4 . PHP_EOL;
}
?>

mktime関数は、指定した日時をUnixタイムスタンプ（1970年1月1日0時0分0秒からの経過秒数）に変換するPHPの関数です。システムエンジニアを目指す上で、日時処理は避けて通れないため、mktime関数は非常に重要です。

引数には、時間、分、秒、月、日、年をそれぞれ整数で指定します。引数の順番はhour, minute, second, month, day, yearです。引数を省略した場合、現在の日時が使用されます。例えば、mktime(10, 30, 0)とすると、現在の日の10時30分0秒のタイムスタンプを取得できます。mktime(0, 0, 0, 12, 31, 2024)のように、特定の日時を指定することも可能です。引数を全て省略したmktime()は、現在時刻のタイムスタンプを返します。

mktime関数は、正常に日時をタイムスタンプに変換できた場合、整数型のタイムスタンプを返します。しかし、存在しない日時（例えば30時など）を指定した場合や、範囲外の値を指定した場合はfalseを返します。戻り値がfalseかどうかをチェックすることで、エラーハンドリングを行うことができます。タイムゾーンの設定によっては結果が変わる可能性がある点にも注意が必要です。

<?php

/**
 * 指定された年と月の月末のUNIXタイムスタンプを取得します。
 *
 * mktime関数の日付引数（第5引数）に0を指定すると、
 * 指定された月の「前日」として扱われる特性を利用しています。
 * 例えば、2月0日は1月31日を意味します。
 *
 * @param int|null $year  年。省略した場合は現在の年を使用します。
 * @param int|null $month 月。省略した場合は現在の月を使用します。
 * @return int|false 月末のUNIXタイムスタンプ。失敗した場合はfalseを返します。
 */
function getEndOfMonth(?int $year = null, ?int $month = null): int|false
{
    // 引数が省略された場合、現在の年と月を取得します。
    if ($year === null) {
        $year = (int)date('Y'); // 現在の年 (例: 2023)
    }
    if ($month === null) {
        $month = (int)date('n'); // 現在の月 (先頭にゼロが付かない、例: 1, 2, ..., 12)
    }

    // mktime() を使用して月末のUNIXタイムスタンプを計算します。
    // 引数の順序は、mktime(時, 分, 秒, 月, 日, 年) です。
    // ここでは、翌月の0日目を指定することで、現在の月の最終日を取得します。
    // 例: 1月の月末を知るには、2月0日を指定します (0, 0, 0, 1+1, 0, $year)。
    $endOfMonthTimestamp = mktime(0, 0, 0, $month + 1, 0, $year);

    return $endOfMonthTimestamp;
}

// --- サンプル利用例 ---

// 現在の月の月末日を取得し、表示します。
$currentEndOfMonthTimestamp = getEndOfMonth();
if ($currentEndOfMonthTimestamp !== false) {
    echo "現在の月の月末日: " . date('Y-m-d', $currentEndOfMonthTimestamp) . "\n";
} else {
    echo "現在の月の月末日の取得に失敗しました。\n";
}

// 2023年2月の月末日を取得し、表示します（閏年ではない年）。
$feb2023EndOfMonthTimestamp = getEndOfMonth(2023, 2);
if ($feb2023EndOfMonthTimestamp !== false) {
    echo "2023年2月の月末日: " . date('Y-m-d', $feb2023EndOfMonthTimestamp) . "\n"; // 結果: 2023-02-28
} else {
    echo "2023年2月の月末日の取得に失敗しました。\n";
}

// 2024年2月の月末日を取得し、表示します（閏年）。
$feb2024EndOfMonthTimestamp = getEndOfMonth(2024, 2);
if ($feb2024EndOfMonthTimestamp !== false) {
    echo "2024年2月の月末日: " . date('Y-m-d', $feb2024EndOfMonthTimestamp) . "\n"; // 結果: 2024-02-29
} else {
    echo "2024年2月の月末日の取得に失敗しました。\n";
}

PHPのmktime関数は、指定された日時からUNIXタイムスタンプ（1970年1月1日 00:00:00 UTCからの経過秒数）を生成するために使用されます。このサンプルコードでは、mktime関数を応用して、指定した年と月の月末日を正確に取得するgetEndOfMonth関数を定義しています。

getEndOfMonth関数は、年と月を引数として受け取りますが、これらは省略可能です。引数を省略した場合は、現在の年と月が自動的に使われます。この関数の核心は、mktime関数の日付に関するユニークな特性を利用している点です。mktime関数は、日付引数に「0」を指定すると、指定された月の「前日」として扱われるという挙動があります。例えば、2月0日は1月31日を意味します。この特性を活かし、翌月の「0日目」を指定することで、現在の月の最終日を計算しています。これにより、各月の異なる日数や閏年による2月の変化にも自動的に対応し、常に正しい月末日を取得できます。

最終的にgetEndOfMonth関数は、計算された月末のUNIXタイムスタンプを整数値で返します。何らかの理由で日付の生成に失敗した場合はfalseを返しますので、呼び出し側ではその戻り値を確認して適切に処理する必要があります。サンプルコードの利用例では、現在の月の月末や、特定の年月の月末（閏年を含む2月）を実際に取得し、date関数で人間が読める形式に変換して表示する様子が示されています。