WordPress5.3, 日付/時刻取得の変更と新しい関数。DateTimeクラスが基準になる。

WordPress5.3では日付/取得関数が大きく変わります。これまでの関数は非推奨になり将来なくなります。それに代わって新しい関数が追加されました。

PHPではすでにDateTimeを使うのが当たり前だったので、やっとWPもやってくれた印象。

公式ガイドからサンプルコードつきでかんたんに解説します。

WPタイムスタンプの段階的廃止

これまで、WordPressの日付/時刻コンポーネントはWordPressタイムスタンプに依存していました。

タイムゾーンオフセットはローカライズとも呼ばれ、UTCの基準（グリニッジ）からの時差です。WordPressでは、管理画面で設定されたタイムゾーンを整数値に変換します。

WPタイムスタンプを基準にしたことが、多くのバグを発生させ上流のPHPや外部システムとの相互運用性が欠如していました。

またドキュメントでは、これらを誤ってUnixタイムスタンプと呼んでいました。

公式ガイドでは、下位バージョンとの互換性を保ったままWPタイムスタンプを廃止することは不可能だと言い切っています。

（あきらめてる？）

と同時に、これらの作業をしていくそうです。

WordPress5.3では新しい関数が追加されています。

新旧API比較

WP5.3で新しいAPI（関数）が追加されたことで、いままで慣れ親しんだAPIが非推奨になりました。その対応表です。

非推奨

いままで使いなれた関数で、WP5.3以降、非推奨になったものです。

WPタイムスタンプで日時を取得しない

基準値を取っているように見えますが、じっさいはタイムゾーンも含みます。

WPタイムスタンプをもとにローカライズしない

タイムゾーンオフセットを足してパラメータに渡す人が多かった？ みたいです。

（これをするとタイムゾーン × 2が足される。）

その他

そのほか注意事項があります。

（公式ガイドの直訳）

推奨

じゃあどうすりゃいいのか？

代わりの関数がWordPress5.3で追加されました。それを使いましょうってこと。

UnixタイムスタンプまたはDateTimeImmutableオブジェクトで日時を取得する。

PHPでの日時操作はクラスオブジェクトを使うようになっています。WordPressでもやっとそれに合わせました。

Unixタイムスタンプをもとにローカライズする

wp_date( DATE_RFC3339, $timestamp );

その他

そのほかの注意事項です。

新しい関数を使ってみた

非推奨・推奨をつらつらと並べてきましたが何のこっちゃです。じっさいに使いながら見ていきましょう。

統一されたタイムゾーン取得

UNIXタイムスタンプ基準にしたことでタイムゾーンが必要だろうと、新しく取得関数が追加されました。

タイムゾーンを取得する唯一の方法だと公式ガイドは言っています。

（これを使ってくれってこと。）

wp_timezone_string()

管理メニューの『設定 -> 一般』のタイムゾーンから文字列を取得します。

echo wp_timezone_string();

Asia/Tokyo

DateTimeZoneクラスを返すものも追加されてます。

wp_timezone()

$tz = wp_timezone();
echo $tz->getName() . PHP_EOL;
echo var_dump($tz->getLocation());

Asia/Tokyo
array(4) { ["country_code"]=> string(2) "JP" ["latitude"]=> float(35.65444) ["longitude"]=> float(139.74472) ["comments"]=> string(0) "" }

現在日時取得

current_datetime()

新旧同時に実行してみましょう。

echo current_time('Y/m/d H:i:s') . PHP_EOL;
echo current_datetime()->format('Y/m/d H:i:s');

2019/12/20 13:24:10
2019/12/20 13:24:10

結果は同じです。ただ、新関数はパラメータ無しでシンプルに使えます。

また、リターン値がオブジェクトなので、フォーマット変換にはオブジェクトのformat()メソッドを使います。

任意の日時取得

date_i18n()が非推奨になってwp_date()が追加されました。

wp_date( $format, $timestamp, $timezone )

echo date_i18n('Y/m/d H:i:s') . PHP_EOL;
echo wp_date('Y/m/d H:i:s');

2019/12/19 17:01:55
2019/12/19 17:01:55

date_i18n()は内部でwp_date()を使っている（レガシーラッパー）ので結果は同じです。

ただwp_date()では、タイムゾーンが指定できます。（デフォルトが設定値なだけ。）

UNIXタイムスタンプを基準にしたのでタイムゾーン設定値を足しません。

公式ガイドでも言っています。

Note that, unlike date_i18n(), this function accepts a true Unix timestamp, not summed with timezone offset.

（date_i18n()とは異なり、この関数はUnixタイムスタンプを受け入れ、タイムゾーンオフセットは加算されないことに注意してください。）

公式ガイドより。筆者訳

いや、タイムゾーン足すじゃん

と思ったのですが、ここがポイントです。たとえば、このサンプルを見てください。

echo date_i18n('Y/m/d H:i:s P e', strtotime('20151015 13:22:43')) . PHP_EOL;
echo wp_date('Y/m/d H:i:s P e', strtotime('20151015 13:22:43'));

指定日時のフォーマット変換として使ったとします。結果はこうなります。

2015/10/15 13:22:43 +09:00 Asia/Tokyo
2015/10/15 22:22:43 +09:00 Asia/Tokyo

wp_date()の時刻が進んでしまいました。デフォルトのタイムゾーンが足されるからです。

ここがWordPress5.3の変更点の肝です。非推奨・推奨のところでいろいろな注意点がありましたが、ぜんぶここで解決しましょう。

date_i18n()の問題点

今度は、PHP関数date()もいっしょに実行してみましょう。

$format = 'Y/m/d H:i:s P e';
$time = '20151015 13:22:43';
echo date_i18n($format, strtotime($time)) . ' <--- date_i18n()' . PHP_EOL;
echo wp_date($format, strtotime($time)) . ' <--- wp_date()' . PHP_EOL ;
echo date($format, strtotime($time)) . ' <--- date()';

2015/10/15 13:22:43 +09:00 Asia/Tokyo <--- date_i18n()
2015/10/15 22:22:43 +09:00 Asia/Tokyo <--- wp_date()
2015/10/15 13:22:43 +00:00 UTC <--- date()

ひとつだけおかしいです。どれだと思いますか？

答えはdate_i18n()です。PHPにかぎらずプログラミングではタイムスタンプとタイムゾーンは分けて考えます。

（タイムスタンプ + タイムゾーン = 日時）

このなかでは、date_i18n()だけが『指定タイムスタンプがそのままローカル時間』になっています。

ちなみに、date()とwp_date()の結果は同じです。ただ、ロンドン時間と日本時間になっているだけで。

（タイムスタンプは同じでタイムゾーンがちがう。）

これが『WordPressとPHPやシステムの互換性がない』です。

date_default_timezone_set()を使うな！

ここで、サンプルコードを修正しました。

$format = 'Y/m/d H:i:s P e';
$time = '20151015 13:22:43';
echo date_i18n($format, strtotime($time)) . ' <--- date_i18n()' . PHP_EOL;
date_default_timezone_set( 'Asia/Tokyo' );
echo wp_date($format, strtotime($time)) . ' <--- wp_date()' . PHP_EOL ;
echo date($format, strtotime($time)) . ' <--- date()';

2015/10/15 13:22:43 +09:00 Asia/Tokyo <--- date_i18n()
2015/10/15 13:22:43 +09:00 Asia/Tokyo <--- wp_date()
2015/10/15 13:22:43 +09:00 Asia/Tokyo <--- date()

すべて同じになりましたね？ でもプログラムとして失敗です。

もし、世界を相手にする企業のシステムを作っていて、ロンドン・ニューヨーク、ドバイ、香港、東京の時間を表示するとしたら？

date_default_timezone_set()を連発しますか？ってなりますし、マルチスレッド処理があって、ほぼ同時に日時を取得したら、別の処理のタイムゾーンまで変わってしまいます。

だから、WordPressの公式ガイドでも『date_default_timezone_set()でタイムゾーンを変更するな！』って言ってるんですね？

WordPressの新しい日時は、『タイムスタンプとタイムゾーンを分ける』が基本です。これを忘れると間違いなくバグが出ます。

投稿日時・更新日時取得

get_post_time()で投稿日時を取得していましたが、残念なところがありました。

WordPressではそれに代わる関数が追加されました。ついでに投稿日時のタイムスタンプ取得関数まで。

get_post_datetime( $post, $field, $source )

get_post_timestamp( $post, $field )

$format = 'Y/m/d H:i:s P e';
$date = get_post_datetime(13);
$modified = get_post_datetime(13, 'modified');

echo $date->format($format) . ' <--- date' . PHP_EOL;
echo $modified->format($format) . ' <--- modified' . PHP_EOL;
echo PHP_EOL;

$tz = new DateTimeZone('UTC');
$date_ts = get_post_timestamp(13);
$modified_ts = get_post_timestamp(13, 'modified');

echo wp_date($format, $date_ts, $tz) . ' <--- date utc' . PHP_EOL;
echo wp_date($format, $modified_ts, $tz) . ' <--- modified utc' . PHP_EOL;
echo PHP_EOL;

$tz = new DateTimeZone('Australia/Sydney');

echo wp_date($format, $date_ts, $tz) . ' <--- date sydney' . PHP_EOL;
echo wp_date($format, $modified_ts, $tz) . ' <--- modified sydney' . PHP_EOL;

2017/05/26 19:30:42 +09:00 Asia/Tokyo <--- date
2017/07/09 16:01:18 +09:00 Asia/Tokyo <--- modified

2017/05/26 10:30:42 +00:00 UTC <--- date utc
2017/07/09 07:01:18 +00:00 UTC <--- modified utc

2017/05/26 20:30:42 +10:00 Australia/Sydney <--- date sydney
2017/07/09 17:01:18 +10:00 Australia/Sydney <--- modified sydney

投稿日時をかんたんに各国の現地日時に変更できます。記事の更新日時もかんたんに取れます。

WordPress日時の仕様変更でやりたいことはこれ！

ここまで、非推奨だ、推奨だ、なんだと言ってきましたが、これからのWordPressの日時でやりたいことは、たったこれだけです。

PHP5.2から、日時はクラスオブジェクトで扱うようになりました。

このオブジェクトは、タイムゾーンとタイムスタンプを分けて管理して、いろいろな変更ができるようになっています。

WordPressタイムスタンプだと、タイムゾーンを含めて管理するのでどうしても扱いづらくなっていました。

（他地域の時刻に変換するとか。）

PHP5.2は2011年リリースなので、いまPHPでプログラミングしている人は当たり前のようにクラスオブジェクトを使っているでしょう。

むしろ新しいWordPressの日時の考え方のほうがやりやすくなるはずです。