bitrix-datetime

日付と時刻

ベースライン：main 23.0+ · 検証済み：main 26.800.0

• Bitrix\Main\Type\Date — 日付のみ（時刻は 00:00:00）です。\DateTime のサブクラスではありません。\DateTime をラップしているため、modify()、sub()、setTimestamp() は存在しません。
• Bitrix\Main\Type\DateTime extends Date — 時刻、タイムゾーン、ユーザー時刻への変換を追加します。

使用可能なメソッド：format()、add()、setDate()、getTimestamp()、getDiff()、toString()。DateTime では、setTime()、setTimeZone()、setDefaultTimeZone()、toUserTime()、disableUserTime() も使用できます。

use Bitrix\Main\Type\Date;
use Bitrix\Main\Type\DateTime;

$d = new Date('25.11.2025', 'd.m.Y');                  // 2nd arg is a PHP format
$dt = new DateTime('2025-11-25 14:30:00', 'Y-m-d H:i:s', new \DateTimeZone('UTC'));
$now = new DateTime();
$fromSite = new DateTime($request->get('DATE'));       // no format = site culture format; bad input throws ObjectException

ユーザー入力の解析

$dt = DateTime::tryParse($input, 'd.m.Y H:i');         // null on error
$isValid = $dt !== null && $dt->format('d.m.Y H:i') === $input;   // strict

Date::isCorrect('31.02.2025', 'd.m.Y') は true を返します。パーサーが日付を繰り越して 03.03.2025 にします。上記の厳密な往復検証か、checkdate() を使用してください。

その他のソース：DateTime::createFromTimestamp($ts)、DateTime::createFromPhp(\DateTime $php)（\DateTimeImmutable の場合は、先に \DateTime::createFromImmutable() が必要です）、Date::createFromText('tomorrow')（DateTime|null を返します）。

カルチャー形式とマスク

カルチャー（Context::getCurrent()->getCulture()）には、PHP 形式ではなく サイトのマスク（DD.MM.YYYY HH:MI:SS）が格納されています。これらを format() に渡さないでください。

$culture = \Bitrix\Main\Context::getCurrent()->getCulture();
echo $dt->toString($culture);                           // culture format, user TZ
echo $dt->format(DateTime::getFormat($culture));        // culture format, no TZ shift
echo $d->format(Date::convertFormatToPhp($culture->getDateFormat()));

Date::convertFormatToPhp()：

マスク	PHP	備考
YYYY、MMMM、MM、DD	Y、F、m、d
MI、SS	i、s
HH / H	H / h	単独の H（HH ではない場合）は 12 時間制です
GG / G	G / g	同じルールですが、先頭にゼロを付けません
TT / T	A / a	AM/PM

日時の計算

add() はオブジェクトを変更し、そのオブジェクトを返します。ISO 間隔（P10D、-P1M、PT30M）と相対テキスト（+2 weeks、-3 days）を受け付けます。

$tomorrow = (clone $now)->add('P1D');
$dayStart = (clone $now)->setTime(0, 0);
$monday = (clone $dayStart)->add('-' . ((int)$now->format('N') - 1) . ' days');
$days = $d1->getDiff($d2)->days;                        // \DateInterval from $d1 to $d2

タイムゾーン

値は サーバー 時刻で保持されます。メインモジュールでタイムゾーンが有効になっている場合、ユーザーにはそれぞれのタイムゾーンで表示されます。

呼び出し	結果
(string)$dt、$dt->toString()	カルチャー形式で ユーザー の TZ（有効で、オブジェクトで無効化されていない場合）
$dt->format(...)	オブジェクト自身の TZ（設定されていなければサーバー TZ。上記の UTC の例を参照）で、ユーザーの時刻に変換されることはありません
$dt->disableUserTime()	toString() はサーバー時刻のままです。ログ、メール、サーバー TZ の人間向けテキストに使用します
DateTime::createFromUserTime($str)	ユーザー TZ の文字列をサーバー時刻として解析します
$dt->toUserTime()	オブジェクト自体の時刻を変換します。必ずクローンに対して使用し、保存しないでください

従来の書き込み処理（CAgent::AddAgent、$DB->Add() / PrepareUpdate()）では、日付文字列に CDatabase::CharToDateFunction() が適用され、ユーザーオフセットが差し引かれます。ユーザー時刻 の文字列を渡してください。disableUserTime() ではなく、通常の toString() を使用します。

\CAgent::AddAgent(
    MyAgent::class . '::run();',
    'vendor.module',
    'N',
    60,
    '',
    'Y',
    (new DateTime())->add('+5 minutes')->toString(),   // user time; the kernel shifts it back
);

ORM

DateField は Date を返し、DatetimeField は DateTime を返します。フィルターには文字列ではなくオブジェクトを使用してください。

PostTable::query()->setSelect(['ID'])->where('CREATED_AT', '>', (new DateTime())->add('-P7D'))->fetchAll();

SQL レベルでは、DateTime はサーバー TZ で書き込まれます（bitrix-database）。\DateTimeInterface を必要とするサードパーティーコードでは、\DateTime::createFromFormat('U', (string)$dt->getTimestamp()) を使用してください。