Stdlib: DateTimeImmutable / DateInterval — ext/date OOP phase 2 (#3072 follow-up)

[PurHur]

Category

stdlib

Problem

#3072 landed VM DateTime + DateTimeZone via lib/VM/DateTimeSupport.php (host PHP date extension for parse/format). Zend also provides DateTimeImmutable, DateInterval, and DateTime::diff() — common in logging, sessions, and immutable config snapshots.

PHP 8.4 follow-ups (separate issues but same ext/date surface): DateTime::createFromTimestamp() (#5973), createFromInterface() (#5936).

php-src reference

• php/php-src ext/date/php_datetime.c — DateTimeImmutable, DateInterval, DateTime::diff
• php/php-src ext/date/php_datetime.stub.php — method signatures
• php/php-src ext/date/php_date.c — procedural date_diff()

Repro A — immutable + modify (failure today)

<?php
$immutable = new DateTimeImmutable('2026-05-29 12:00:00', new DateTimeZone('UTC'));
$modified = $immutable->modify('+1 day');
echo $modified->format('Y-m-d'), "\n";
var_export($immutable === $modified);
echo "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php repro_datetime_immutable.php
php bin/vm.php repro_datetime_immutable.php
'

Runtime	format	$immutable === $modified
Zend	2026-05-30	false (new instance)
VM today	compile/runtime error — DateTimeImmutable unknown	—

Repro B — DateInterval via diff()

<?php
$dt = new DateTime('2026-05-29');
$interval = $dt->diff(new DateTime('2026-06-05'));
echo $interval->days, "\n";
echo $interval->invert ? 'inverted' : 'forward', "\n";

Zend: 6 and forward.
VM today: DateInterval class missing.

Repro C — procedural date_diff() (optional v1)

<?php
$di = date_diff(new DateTime('2026-01-01'), new DateTime('2026-01-08'));
echo $di->days, "\n";

Track in same PHPT or defer to #4604.

Scope (this repo)

Layer	Path	Notes
VM classes	Extend lib/VM/DateTimeSupport.php	DateTimeImmutable shares storage; modify returns new instance
VM classes	DateInterval object with days, invert, format()
Methods v1	__construct, format, modify, getTimestamp, getTimezone, diff	Defer createFromTimestamp to #5973
Registration	lib/VM/BuiltinClasses.php or date module loader	Mirror DateTime phase-1 pattern
JIT/AOT	VM defer v1 (same as #3072)	Document in matrix; JIT issue if method dispatch blocked
Tests	test/compliance/cases/stdlib/datetime_immutable.phpt, datetime_diff.phpt
Matrix	script/capability-matrix.php

PHP-in-PHP note: long-term replace host \DateTime delegation with native parsing in ext/date/ — out of scope here; keep host bridge for v1.

Done when

• Repro A prints 2026-05-30 and false on VM
• Repro B prints 6 and forward on VM
• class_exists('DateTimeImmutable') and class_exists('DateInterval') true
• ./script/ci-fast.sh --filter datetime_immutable green
• docs/capabilities-syntax.md / matrix updated (Immutable + Interval rows)

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter datetime_immutable'

Dependencies

• Stdlib: DateTime / DateTimeImmutable OOP (ext/date parity) #3072 ✅ DateTime / DateTimeZone VM phase 1
• Host date extension in Docker image (same as phase 1)

Links

• Stdlib: DateTime::createFromTimestamp() / DateTimeImmutable::createFromTimestamp() (PHP 8.4, ext/date/php_date.c) #5973 createFromTimestamp · Stdlib: date_add()/date_sub()/date_modify()/date_diff() — procedural DateTime mutation (ext/date/php_date.c parity) #4604 date_add/sub/modify/diff procedural · Stdlib: DatePeriod OOP — date range iteration (ext/date/php_date.c parity) #3633 DatePeriod · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

[PurHur]

claim: PHP Compiler STD Lib — starting this run (DateTime::diff() / DateTimeImmutable::diff() OOP methods, phase 2 of #3162)

[PurHur]

Merged PR #8454 — DateTime::diff() / DateTimeImmutable::diff() registered on VM.

Verification:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php test/repro-maintainer/parity_datetime_diff.php
php bin/vm.php test/repro-maintainer/parity_datetime_diff.php
vendor/bin/phpunit --filter datetime_diff
'

VM + Zend both print 7 / forward / 7; PHPUnit 2/2 OK.

Remaining on #3162: DatePeriod OOP, broader DateInterval surface, native AOT method lowering (#4043).