Stdlib: DateTime::diff() / DateTimeImmutable::diff() VM methods (#3162)

lib/VM/Builtin/DateTimeDiff.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPCompiler\VM\Builtin;
+
+use PHPCompiler\ext\standard\VmMath;
+use PHPCompiler\Frame;
+use PHPCompiler\VM\DateTimeSupport;
+
+/**
+ * DateTime::diff() / DateTimeImmutable::diff() — VM (#3162, php-src zim_DateTime_diff).
+ */
+final class DateTimeDiff extends VmClassMethod
+{
+    public function __construct()
+    {
+        parent::__construct('diff');
+    }
+
+    public function execute(Frame $frame): void
+    {
+        $argc = \count($frame->calledArgs);
+        if ($argc < 2 || $argc > 3) {
+            throw new \ArgumentCountError(\sprintf(
+                'DateTime::diff() expects at least 1 argument, %d given',
+                $argc - 1
+            ));
+        }
+        if (null === $frame->returnVar || null === $frame->vmContext) {
+            return;
+        }
+
+        $receiver = DateTimeSupport::requireDateTimeLike($frame->calledArgs[0], 'DateTime::diff()');
+        $label = DateTimeSupport::isDateTimeImmutable($receiver) ? 'DateTimeImmutable' : 'DateTime';
+        $target = DateTimeSupport::requireDateTimeLike(
+            $frame->calledArgs[1],
+            "{$label}::diff()",
+            $frame->vmContext
+        );
+
+        $absolute = false;
+        if ($argc >= 3) {
+            $absolute = VmMath::parseBoolBuiltinArg(
+                $frame->calledArgs[2]->resolveIndirect(),
+                "{$label}::diff",
+                2,
+                'absolute'
+            );
+        }
+
+        $interval = DateTimeSupport::diffDateTimes(
+            $receiver,
+            $target,
+            $absolute,
+            $frame->vmContext
+        );
+        $frame->returnVar->object($interval);
+    }
+}

lib/VM/BuiltinClasses.php

@@ -8,6 +8,7 @@
 use PHPCompiler\VM\Builtin\DateIntervalConstruct;
 use PHPCompiler\VM\Builtin\DateIntervalFormat;
 use PHPCompiler\VM\Builtin\DateTimeConstruct;
+use PHPCompiler\VM\Builtin\DateTimeDiff;
 use PHPCompiler\VM\Builtin\DateTimeCreateFromImmutable;
 use PHPCompiler\VM\Builtin\DateTimeCreateFromInterface;
 use PHPCompiler\VM\Builtin\DateTimeCreateFromTimestamp;
@@ -832,6 +833,7 @@ private static function registerDateTime(Context $ctx): void
             'gettimestamp' => new DateTimeGetTimestamp(),
             'getmicrosecond' => new DateTimeGetMicrosecond(),
             'modify' => new DateTimeModify(),
+            'diff' => new DateTimeDiff(),
             'setmicrosecond' => new DateTimeSetMicrosecond(),
             'settimezone' => new DateTimeSetTimezone(),
         ];

test/compliance/cases/stdlib/datetime_diff.phpt

@@ -0,0 +1,17 @@
+--TEST--
+stdlib DateTime::diff() / DateTimeImmutable::diff() — DateInterval between instances (#3162, ext/date/php_date.c)
+--FILE--
+<?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";
+
+$immutable = new DateTimeImmutable('2026-01-01');
+$span = $immutable->diff(new DateTimeImmutable('2026-01-08'));
+echo $span->days, "\n";
+?>
+--EXPECT--
+7
+forward
+7

test/repro-maintainer/parity_datetime_diff.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+$dt = new DateTime('2026-05-29');
+$interval = $dt->diff(new DateTime('2026-06-05'));
+echo $interval->days, "\n";
+echo $interval->invert ? 'inverted' : 'forward', "\n";
+
+$immutable = new DateTimeImmutable('2026-01-01');
+$span = $immutable->diff(new DateTimeImmutable('2026-01-08'));
+echo $span->days, "\n";