[RFC] ext/intl: Implement IntlRelativeDateTimeFormatter

NEWS

@@ -23,6 +23,9 @@ PHP                                                                        NEWS
     throwing a ValueError. (Marc Bennewitz)
 
 - Intl:
+  . Added IntlRelativeDateTimeFormatter for locale-aware relative date and time
+    formatting, with enums for styles, capitalization contexts, and units.
+    (Weilin Du)
   . Added Transliterator::toRules() and transliterator_to_rules().
     (Weilin Du, David Carlier)
   . Fixed Collator attribute and strength methods not rejecting an

UPGRADING

@@ -50,6 +50,18 @@ PHP 8.7 UPGRADE NOTES
     array of CURLFile or CURLStringFile objects to CURLOPT_POSTFIELDS.
 
 - Intl:
+  . Added IntlRelativeDateTimeFormatter to format relative date and time offsets
+    using locale-specific text, such as "yesterday" or "in 3 days". Its format()
+    method uses a textual form when available and a numeric form otherwise,
+    while formatNumeric() always uses a numeric form. combineDateAndTime()
+    combines already formatted date and time strings according to the locale.
+    The constructor accepts an optional NumberFormatter to customize numeric
+    output; subsequent configuration changes to that object are reflected in
+    formatting results. Styles, capitalization contexts, and units are selected
+    using the IntlRelativeDateTimeFormatterStyle,
+    IntlRelativeDateTimeFormatterCapitalization, and
+    IntlRelativeDateTimeFormatterUnit enums, respectively.
+    RFC: https://wiki.php.net/rfc/reldateformatter
   . Locale::acceptFromHttp() and locale_accept_from_http() now accept an
     optional $availableLocales array argument. When given, the
     Accept-Language header is matched against these locales instead of all
@@ -95,6 +107,11 @@ PHP 8.7 UPGRADE NOTES
 ========================================
 
 - Intl:
+  . IntlRelativeDateTimeFormatter
+  . enum IntlRelativeDateTimeFormatterStyle
+  . enum IntlRelativeDateTimeFormatterCapitalization
+  . enum IntlRelativeDateTimeFormatterUnit
+    RFC: https://wiki.php.net/rfc/reldateformatter
   . Added IntlNumberFormatter class to format a number with a given locale
     and ICU number skeleton, which also covers measurement units, e.g.
     "measure-unit/speed-kilometer-per-hour unit-width-full-name".

ext/intl/CREDITS

@@ -1,2 +1,2 @@
 Internationalization
-Ed Batutis, David Carlier, Vladimir Iordanov, Dmitry Lakhtyuk, Stanislav Malyshev, Vadim Savchuk, Kirti Velankar
+Ed Batutis, David Carlier, Weilin Du, Vladimir Iordanov, Dmitry Lakhtyuk, Stanislav Malyshev, Vadim Savchuk, Kirti Velankar

ext/intl/config.m4

@@ -75,6 +75,7 @@ if test "$PHP_INTL" != "no"; then
     breakiterator/codepointiterator_internal.cpp \
     breakiterator/codepointiterator_methods.cpp \
     listformatter/listformatter_class.cpp \
+    reldateformatter/reldateformatter_class.cpp \
     transliterator/transliterator_class.cpp \
     transliterator/transliterator_methods.cpp \
     idn/idn.cpp \
@@ -125,6 +126,7 @@ if test "$PHP_INTL" != "no"; then
     $ext_builddir/idn
     $ext_builddir/locale
     $ext_builddir/listformatter
+    $ext_builddir/reldateformatter
     $ext_builddir/msgformat
     $ext_builddir/normalizer
     $ext_builddir/numberformatter

ext/intl/config.w32

@@ -42,6 +42,9 @@ if (PHP_INTL != "no") {
 		ADD_SOURCES(configure_module_dirname + "/listformatter", "\
 				listformatter_class.cpp \
 				", "intl");
+		ADD_SOURCES(configure_module_dirname + "/reldateformatter", "\
+				reldateformatter_class.cpp \
+				", "intl");
 		ADD_SOURCES(configure_module_dirname + "/locale", "\
 				locale.cpp \
 				locale_class.cpp \

ext/intl/formatter/formatter_attr.cpp

@@ -181,6 +181,7 @@ U_CFUNC PHP_FUNCTION( numfmt_set_attribute )
 
 	INTL_METHOD_CHECK_STATUS( nfo, "Error setting attribute value" );
 
+	nfo->configuration_version++;
 	RETURN_TRUE;
 }
 /* }}} */
@@ -212,6 +213,7 @@ U_CFUNC PHP_FUNCTION( numfmt_set_text_attribute )
 	unum_setTextAttribute(FORMATTER_UNUM(nfo), static_cast<UNumberFormatTextAttribute>(attribute), svalue.getBuffer(), svalue.length(), &INTL_DATA_ERROR_CODE(nfo));
 	INTL_METHOD_CHECK_STATUS( nfo, "Error setting text attribute" );
 
+	nfo->configuration_version++;
 	RETURN_TRUE;
 }
 /* }}} */
@@ -293,6 +295,7 @@ U_CFUNC PHP_FUNCTION( numfmt_set_symbol )
 	unum_setSymbol(FORMATTER_UNUM(nfo), symbol, svalue.getBuffer(), svalue.length(), &INTL_DATA_ERROR_CODE(nfo));
 	INTL_METHOD_CHECK_STATUS( nfo, "Error setting symbol value" );
 
+	nfo->configuration_version++;
 	RETURN_TRUE;
 }
 /* }}} */
@@ -363,6 +366,7 @@ U_CFUNC PHP_FUNCTION( numfmt_set_pattern )
 		RETURN_FALSE;
 	}
 
+	nfo->configuration_version++;
 	RETURN_TRUE;
 }
 /* }}} */

ext/intl/formatter/formatter_class.cpp

@@ -52,6 +52,7 @@ U_CFUNC zend_object *NumberFormatter_object_create(zend_class_entry *ce)
 
 	intern = reinterpret_cast<NumberFormatter_object *>(zend_object_alloc(sizeof(NumberFormatter_object), ce));
 	formatter_data_init( &intern->nf_data );
+	intern->configuration_version = 0;
 	zend_object_std_init( &intern->zo, ce );
 	object_properties_init(&intern->zo, ce);
 
@@ -68,6 +69,7 @@ U_CFUNC zend_object *NumberFormatter_object_clone(zend_object *object)
 
 	/* clone standard parts */
 	zend_objects_clone_members(&new_nfo->zo, &nfo->zo);
+	new_nfo->configuration_version = nfo->configuration_version;
 
 	/* clone formatter object. It may fail, the destruction code must handle this case */
 	if (FORMATTER_OBJECT(nfo) != nullptr) {

ext/intl/formatter/formatter_class.h

@@ -29,6 +29,7 @@ extern "C" {
 
 typedef struct {
 	formatter_data  nf_data;
+	uint64_t        configuration_version;
 	zend_object     zo;
 } NumberFormatter_object;
 

ext/intl/php_intl.c

@@ -42,6 +42,7 @@
 #include "locale/locale_class.h"
 
 #include "listformatter/listformatter_class.h"
+#include "reldateformatter/reldateformatter_class.h"
 #include "numberformatter/numberformatter_class.h"
 #include "rangeformatter/rangeformatter_class.h"
 
@@ -190,6 +191,9 @@ PHP_MINIT_FUNCTION( intl )
 	/* Register 'ListFormatter' PHP class */
 	listformatter_register_class(  );
 
+	/* Register 'IntlRelativeDateTimeFormatter' PHP class */
+	reldateformatter_register_class(  );
+
 #if U_ICU_VERSION_MAJOR_NUM >= 63
 	/* Register 'IntlNumberFormatter' PHP class */
 	numberformatter_register_class( );

ext/intl/reldateformatter/reldateformatter.stub.php

@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * @generate-class-entries
+ * @generate-c-enums
+ */
+
+enum IntlRelativeDateTimeFormatterStyle
+{
+    case Long;
+    case Short;
+    case Narrow;
+}
+
+enum IntlRelativeDateTimeFormatterCapitalization
+{
+    case None;
+    case MiddleOfSentence;
+    case BeginningOfSentence;
+    case UiListAndMenu;
+    case Standalone;
+}
+
+enum IntlRelativeDateTimeFormatterUnit
+{
+    case Year;
+    case Quarter;
+    case Month;
+    case Week;
+    case Day;
+    case Hour;
+    case Minute;
+    case Second;
+    case Sunday;
+    case Monday;
+    case Tuesday;
+    case Wednesday;
+    case Thursday;
+    case Friday;
+    case Saturday;
+}
+
+/**
+ * @not-serializable
+ * @strict-properties
+ */
+final class IntlRelativeDateTimeFormatter
+{
+    public function __construct(
+        ?string $locale = null,
+        IntlRelativeDateTimeFormatterStyle $style = IntlRelativeDateTimeFormatterStyle::Long,
+        IntlRelativeDateTimeFormatterCapitalization $capitalizationContext = IntlRelativeDateTimeFormatterCapitalization::None,
+        ?NumberFormatter $numberFormatter = null,
+    ) {}
+
+    public function format(int|float $offset, IntlRelativeDateTimeFormatterUnit $unit): string|false {}
+
+    public function formatNumeric(int|float $offset, IntlRelativeDateTimeFormatterUnit $unit): string|false {}
+
+    public function combineDateAndTime(string $relativeDate, string $time): string|false {}
+
+    public function getErrorCode(): int {}
+
+    public function getErrorMessage(): string {}
+}