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

<?php

/**
 * DateTimeInterfaceオブジェクトを特定のフォーマット文字列に変換する関数です。
 * date_format関数を利用して、日時データを読みやすい形式に整形する方法を示します。
 *
 * @param DateTimeInterface $dateTimeObject フォーマットするDateTimeInterfaceオブジェクト。
 *                                          通常はDateTimeクラスのインスタンスを使用します。
 * @param string $formatString 日時をフォーマットするための文字列。
 *                                     PHPのdate関数で使われる書式指定子 (例: 'Y-m-d H:i:s') を指定します。
 * @return string フォーマットされた日時文字列。
 */
function formatDateTimeObject(DateTimeInterface $dateTimeObject, string $formatString): string
{
    // date_format関数は、DateTimeInterfaceオブジェクトを第一引数に、
    // フォーマット文字列を第二引数に取り、整形された日時文字列を返します。
    return date_format($dateTimeObject, $formatString);
}

// --- formatDateTimeObject 関数の使用例 ---

// 1. 現在の日時を表すDateTimeオブジェクトを作成します。
//    DateTimeクラスはDateTimeInterfaceを実装しているため、date_format関数に渡すことができます。
$currentDateTime = new DateTime();

// 2. 日時をフォーマットするための書式文字列を定義します。
//    よく使われる書式指定子:
//    - Y: 4桁の年 (例: 2023)
//    - m: 2桁の月 (01～12)
//    - d: 2桁の日 (01～31)
//    - H: 24時間形式の時 (00～23)
//    - i: 2桁の分 (00～59)
//    - s: 2桁の秒 (00～59)
$standardFormat = 'Y-m-d H:i:s';

// 3. `formatDateTimeObject`関数を呼び出して日時をフォーマットし、結果を出力します。
$formattedStandard = formatDateTimeObject($currentDateTime, $standardFormat);
echo "現在の標準フォーマット日時: " . $formattedStandard . PHP_EOL;

// 別のフォーマット文字列での使用例: 月の名称、日、年、12時間形式の時、分、午前/午後
//    - F: 月の完全な名称 (例: January)
//    - j: 日 (先頭にゼロなし、1～31)
//    - g: 12時間形式の時 (先頭にゼロなし、1～12)
//    - a: 午前/午後 (am/pm)
$friendlyFormat = 'F j, Y, g:i a';
$formattedFriendly = formatDateTimeObject($currentDateTime, $friendlyFormat);
echo "現在のフレンドリーフォーマット日時: " . $formattedFriendly . PHP_EOL;

// 特定の日時をフォーマットする例
$specificDateTime = new DateTime('2024-03-01 09:30:15');
$formattedSpecific = formatDateTimeObject($specificDateTime, 'd/m/Y (H:i:s)');
echo "特定の日時: " . $formattedSpecific . PHP_EOL;

?>

PHPのdate_format関数は、日付や時刻の情報を特定の書式文字列に基づいて整形し、人間が読みやすい形式の文字列として取得するために利用されます。この関数は、DateTimeInterface型のオブジェクトと、日時をどのように表示するかを定義する書式文字列の2つの引数を必要とします。

第一引数のDateTimeInterface $objectには、対象となる日時データを持つオブジェクトを渡します。通常、現在時刻や特定の日時を表すDateTimeクラスのインスタンスが使用されます。第二引数のstring $formatは、年、月、日、時、分、秒といった日時要素をどのような順番や形式で表示するかを指定する書式指定子（例: 'Y-m-d H:i:s'）からなる文字列です。date_format関数はこれらの情報を受け取り、整形された日時データを文字列として返します。

サンプルコードでは、まず現在の時刻を表すDateTimeオブジェクトを作成し、それをdate_format関数を呼び出すformatDateTimeObject関数に渡しています。例えば、'Y-m-d H:i:s'という書式指定子を使えば「2024-07-26 10:30:00」のように標準的な形式に変換され、'F j, Y, g:i a'という書式指定子では「July 26, 2024, 10:30 am」のような表現に整形されます。このように、date_format関数を使用することで、日時データを表示要件に応じて柔軟に調整することが可能です。

<?php

/**
 * Demonstrates the use of the global date_format() function in PHP.
 *
 * This function creates a DateTime object (which implements DateTimeInterface)
 * and then formats it into a string using a specified format. It specifically
 * highlights the 't' format specifier, which represents the number of days
 * in the given month (e.g., 28, 29, 30, or 31).
 *
 * @param string|null $dateString Optional date string to initialize the DateTime object.
 *                                If null, the current date and time are used.
 * @return void Outputs the original and formatted date strings to the console.
 */
function demonstrateDateFormatT(string $dateString = null): void
{
    // Create a DateTime object. DateTime objects implement DateTimeInterface.
    // Using a try-catch block for robust error handling, especially if $dateString is invalid.
    try {
        $dateTimeObject = $dateString ? new DateTime($dateString) : new DateTime();
    } catch (Exception $e) {
        echo "Error: Could not create DateTime object from '{$dateString}': " . $e->getMessage() . PHP_EOL;
        return;
    }

    // Define the format string.
    // 'Y': Four digit year (e.g., 2023)
    // 'm': Two digit month (e.g., 01 for January)
    // 'd': Two digit day of the month (e.g., 05)
    // 't': This is the key specifier. It outputs the number of days in the month
    //      represented by the DateTime object (e.g., 28, 29, 30, or 31).
    $formatString = 'Y-m-d (Days in month: t)';

    // Use the global date_format() function to format the DateTime object.
    // It takes a DateTimeInterface object and a format string as arguments.
    $formattedDate = date_format($dateTimeObject, $formatString);

    // Output the original and formatted dates for clarity.
    echo "Original Date: " . $dateTimeObject->format('Y-m-d') . PHP_EOL;
    echo "Formatted Date with 't' (days in month): " . $formattedDate . PHP_EOL;
    echo str_repeat('-', 30) . PHP_EOL; // Separator for multiple examples
}

// --- Example Usages for System Engineer Beginners ---

// 1. Demonstrate with the current date and time.
echo "--- Current Date/Time Example ---" . PHP_EOL;
demonstrateDateFormatT();

// 2. Demonstrate with a specific date in October (31 days).
echo "--- October (31 Days) Example ---" . PHP_EOL;
demonstrateDateFormatT('2023-10-26');

// 3. Demonstrate with a specific date in April (30 days).
echo "--- April (30 Days) Example ---" . PHP_EOL;
demonstrateDateFormatT('2023-04-15');

// 4. Demonstrate with a specific date in February of a leap year (29 days).
echo "--- February 2024 (Leap Year, 29 Days) Example ---" . PHP_EOL;
demonstrateDateFormatT('2024-02-01');

// 5. Demonstrate with a specific date in February of a non-leap year (28 days).
echo "--- February 2023 (Non-Leap Year, 28 Days) Example ---" . PHP_EOL;
demonstrateDateFormatT('2023-02-01');

?>

PHPのdate_format関数は、日付と時刻の情報を、指定された書式に従って整形された文字列に変換する際に利用されます。

この関数は二つの引数を取ります。最初の引数である$objectには、DateTimeInterfaceを実装したオブジェクト（例えばDateTimeクラスのインスタンス）を渡します。これは変換したい具体的な日付と時刻の情報を持つオブジェクトです。二番目の引数である$formatには、日付や時刻をどのように表示するかを定義する書式文字列を指定します。関数は、この書式文字列に基づいて整形された日付時刻のstring（文字列）を戻り値として返します。

今回のサンプルコードでは、特に書式文字列の中にある't'という指定子に焦点を当てています。't'は、対象となる月が何日まであるか、その月の総日数を数値で出力するために使用されます。例えば、31日間の月であれば「31」と、28日間の月であれば「28」と表示されます。サンプルでは、現在の月、31日の月、30日の月、うるう年の2月（29日）、うるう年ではない2月（28日）といった様々な日付を用いて、't'指定子が月の総日数を正確に表示することを示しています。これにより、ユーザーは日付に基づいて月の総日数を容易に取得できるようになります。