Added DateTime[Immutable]::[get|set]Microseconds (#12557)

* Added DateTime[Immutable]::[get|set]Microseconds

Author: marc-mabe

NEWS

@@ -19,6 +19,7 @@ PHP                                                                        NEWS
 
 - Date:
   . Added DateTime[Immutable]::createFromTimestamp. (Marc Bennewitz)
+  . Added DateTime[Immutable]::[get|set]Microseconds. (Marc Bennewitz)
 
 - DOM:
   . Added DOMNode::compareDocumentPosition(). (nielsdos)

UPGRADING

@@ -146,6 +146,9 @@ PHP 8.4 UPGRADE NOTES
 - Date:
   . Added static methods
     DateTime[Immutable]::createFromTimestamp(int|float $timestamp): static.
+  . Added method DateTime[Immutable]::getMicroseconds(): int.
+  . Added method
+    DateTime[Immutable]::setMicroseconds(int $microseconds): static.
 
 - DOM:
   . Added constant DOMNode::DOCUMENT_POSITION_DISCONNECTED.

ext/date/php_date.c

@@ -3844,12 +3844,76 @@ PHP_METHOD(DateTimeImmutable, setTimestamp)
 }
 /* }}} */
 
+/* {{{ */
+PHP_METHOD(DateTimeImmutable, setMicroseconds)
+{
+	zval *object, new_object;
+	php_date_obj *dateobj, *new_dateobj;
+	zend_long us;
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS(), "l", &us) == FAILURE) {
+		RETURN_THROWS();
+	}
+
+	if (UNEXPECTED(us < 0 || us > 999999)) {
+		zend_argument_error(
+			date_ce_date_range_error,
+			1,
+			"must be between 0 and 999999, " ZEND_LONG_FMT " given",
+			us
+		);
+		RETURN_THROWS();
+	}
+
+	object = ZEND_THIS;
+	dateobj = Z_PHPDATE_P(object);
+	DATE_CHECK_INITIALIZED(dateobj->time, Z_OBJCE_P(object));
+
+	date_clone_immutable(object, &new_object);
+	new_dateobj = Z_PHPDATE_P(&new_object);
+
+	php_date_set_time_fraction(new_dateobj->time, (int)us);
+
+	RETURN_OBJ(Z_OBJ(new_object));
+}
+/* }}} */
+
+/* {{{ */
+PHP_METHOD(DateTime, setMicroseconds)
+{
+	zval *object;
+	php_date_obj *dateobj;
+	zend_long us;
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS(), "l", &us) == FAILURE) {
+		RETURN_THROWS();
+	}
+
+	if (UNEXPECTED(us < 0 || us > 999999)) {
+		zend_argument_error(
+			date_ce_date_range_error,
+			1,
+			"must be between 0 and 999999, " ZEND_LONG_FMT " given",
+			us
+		);
+		RETURN_THROWS();
+	}
+
+	object = ZEND_THIS;
+	dateobj = Z_PHPDATE_P(object);
+	DATE_CHECK_INITIALIZED(dateobj->time, Z_OBJCE_P(object));
+	php_date_set_time_fraction(dateobj->time, (int)us);
+
+	RETURN_OBJ_COPY(Z_OBJ_P(object));
+}
+/* }}} */
+
 /* {{{ Gets the Unix timestamp. */
 PHP_FUNCTION(date_timestamp_get)
 {
 	zval         *object;
 	php_date_obj *dateobj;
-	zend_long          timestamp;
+	zend_long     timestamp;
 	int           epoch_does_not_fit_in_zend_long;
 
 	if (zend_parse_method_parameters(ZEND_NUM_ARGS(), getThis(), "O", &object, date_ce_interface) == FAILURE) {
@@ -3873,6 +3937,21 @@ PHP_FUNCTION(date_timestamp_get)
 }
 /* }}} */
 
+PHP_METHOD(DateTime, getMicroseconds) /* {{{ */
+{
+	zval *object;
+	php_date_obj *dateobj;
+
+	ZEND_PARSE_PARAMETERS_NONE();
+
+	object = ZEND_THIS;
+	dateobj = Z_PHPDATE_P(object);
+	DATE_CHECK_INITIALIZED(dateobj->time, Z_OBJCE_P(object));
+
+	RETURN_LONG((zend_long)dateobj->time->us);
+}
+/* }}} */
+
 /* {{{ Returns the difference between two DateTime objects. */
 PHP_FUNCTION(date_diff)
 {

ext/date/php_date.stub.php

@@ -412,6 +412,9 @@ public function setTimezone(DateTimeZone $timezone): DateTime {}
      */
     public function getOffset(): int {}
 
+    /** @tentative-return-type */
+    public function getMicroseconds(): int {}
+
     /**
      * @tentative-return-type
      * @alias date_time_set
@@ -436,6 +439,9 @@ public function setISODate(int $year, int $week, int $dayOfWeek = 1): DateTime {
      */
     public function setTimestamp(int $timestamp): DateTime {}
 
+    /** @tentative-return-type */
+    public function setMicroseconds(int $microseconds): static {}
+
     /**
      * @tentative-return-type
      * @alias date_timestamp_get
@@ -503,6 +509,12 @@ public function getOffset(): int {}
      */
     public function getTimestamp(): int {}
 
+    /**
+     * @alias DateTime::getMicroseconds
+     * @tentative-return-type
+     */
+    public function getMicroseconds(): int {}
+
     /**
      * @tentative-return-type
      * @alias date_diff
@@ -533,6 +545,9 @@ public function setISODate(int $year, int $week, int $dayOfWeek = 1): DateTimeIm
     /** @tentative-return-type */
     public function setTimestamp(int $timestamp): DateTimeImmutable {}
 
+    /** @tentative-return-type */
+    public function setMicroseconds(int $microseconds): static {}
+
     /** @tentative-return-type */
     public static function createFromMutable(DateTime $object): static {}