DateTimeのフォーマット文字を整理する

DateTime::format() とは、書式文字を並べた文字列に従って日付を整形するメソッドです。Y-m-d H:i:s を軸に覚えると、大半の表示に対応できます。

よく使う書式文字を押さえる

DateTime::format() の書式文字は数が多くて、毎回マニュアルを開いている人も多いと思います。実務で頻出するのはごく一部なので、そこだけ体に入れておくと速いです。年 Y、月 m、日 d、時 H(24時間)、分 i、秒 s の組み合わせがほとんどですね。

$dt = new DateTime('2024-03-05 09:07:02');

echo $dt->format('Y-m-d H:i:s'); // 2024-03-05 09:07:02
echo $dt->format('Y/n/j');       // 2024/3/5  (ゼロ埋めなし)
echo $dt->format('g:i A');       // 9:07 AM   (12時間表記)

大文字小文字で意味が変わる点は要注意です。m はゼロ埋めありの月、n はゼロ埋めなし、H は24時間で h は12時間、というあたりを取り違えると出力がずれます。

リテラル文字はバックスラッシュで逃がす

書式文字列の中に「年」「月」みたいな固定文字を混ぜたいとき、たまたま書式文字と重なると勝手に変換されてしまいます。d や y は普通に文字として書きたい場面が多いので、そういう文字はバックスラッシュでエスケープします。

$dt = new DateTime('2024-03-05');

// N は曜日番号なので "Nは" と書くと N が変換される
echo $dt->format('Y\年n\月j\日'); // 2024年3月5日

// 英単語を挟むときも同様に逃がす
echo $dt->format('l \t\h\e jS'); // Tuesday the 5th

日本語は基本そのまま通りますが、間に挟んだアルファベットが書式文字と衝突しがちなので、迷ったら逃がしておくのが安全だと思います。

曜日と週の扱い

曜日まわりも少しクセがあります。N は月曜=1〜日曜=7 の ISO 番号、w は日曜=0〜土曜=6 と起点が違います。曜日名を日本語で出したいなら、N で番号を取って配列を引くのが手っ取り早いです。

$dt = new DateTime('2024-03-05'); // 火曜

$week = ['月', '火', '水', '木', '金', '土', '日'];
$label = $week[(int)$dt->format('N') - 1];

echo $dt->format('Y-m-d') . "({$label})"; // 2024-03-05(火)

まとめ

書式文字は全部覚える必要はなくて、Y-m-d H:i:s を軸に、ゼロ埋めの有無(m/n、d/j)と12/24時間(h/H)の違いを押さえれば大半は書けます。固定文字はバックスラッシュで逃がす、曜日は N の番号から配列で引く、この二つを覚えておくと日本語の日付表示でつまずかなくなると思います。

よくある質問

Q. m と n、H と h の違いは?
A. m はゼロ埋めありの月、n はゼロ埋めなし、H は24時間表記、h は12時間表記です。大文字小文字で意味が変わるので取り違えに注意です。

Q. 「年」「月」などの固定文字を混ぜたいです。
A. 書式文字と重なる文字はバックスラッシュで逃がします。'Y\年n\月j\日' のように書くと 2024年3月5日 になります。

Q. 日本語の曜日を出したいです。
A. N で月曜=1〜日曜=7 の番号を取って配列を引くのが手軽です。w は日曜=0〜土曜=6 と起点が違う点に注意してください。