Re: [PHP-DEV] [RFC] IntlRelativeDateTimeFormatter

Mailing Lists php.internals
1

Hi Weilin Du,

Really interesting RFC. Now that the Duration RFC has passed and will be released with PHP8.6
I wonder if you should consider adding its support in some of the proposed public API ?

Thanks for your proposal,
Ignace

On Fri, Aug 7, 2026 at 4:42 PM Weilin Du <weilin-du@qq.com> wrote:

Hi internals,

I would like to bring out my latest RFC: https://wiki.php.net/rfc/reldateformatter targeting PHP 8.7

I hope you find this interesting :slight_smile:

Cheers,
Weilin Du <weilindu@php.net>

2

Here my two cents,

- I would be in favor of an enum instead for the constants.
- I would be in favor of an appropriate namespace to avoid conflicts.
- It seems there are missing parts, e.g. how do you plan (or do you
plan to) express the 2nd argument of ureldateformat_open().

There is probably more to it, just surface level first impressions.

Cheers.

3

Hi Ignace, David,

Thanks for the feedback. IMHO I tend to not accept Duration object as a parameter.

IntlRelativeDateTimeFormatter formats a caller-selected offset and unit. Time\Duration
represents stopwatch time as seconds and nanoseconds. This cause a huge amount of
issue which immediately comes into my head when thinking of this.

The API looks like

$fmt->format(3, UNIT_DAY); // in 3 days
$fmt->format(2, UNIT_MONTH); // in 2 months
$fmt->format(-1, UNIT_SUNDAY);// last Sunday

If we are now accepting Durations, they look like

Time\Duration::fromMinutes(90)

We don’t know how to deal with 90 minutes here. It can be 90 minutes or 1.5 hour.

Nevertheless, what about weekdays? things like UNIT_SUNDAY are not durations.
Not to mention months, quarters, and years need calendar context.

For enums and namespaces: I kept class constants and the global Intl* class name to stay
consistent with the existing ext/intl API, such as IntlDateFormatter, IntlListFormatter
IntlNumberRangeFormatter, and IntlDatePatternGenerator. I don’t want to make
IntlRelativeDateTimeFormatter somehow special here just because this is added later.
I agree that enums and namespaces would be nicer in isolation, indeed. But,
introducing them for only this one formatter would make the API inconsistent with the rest
of ext/intl.

For the second argument of ureldatefmt_open(): the initial implementation will pass NULL,
so ICU uses the default number formatter for the selected locale. This is intended.
Exposing a custom NumberFormatter is possible future scope, but it needs extra care
because ICU adopts ownership of the supplied UNumberFormat, so PHP would need to
clone the underlying formatter before passing it to ICU.

What do you think?

Cheers,
Weilin

4

On Fri, 7 Aug 2026 at 19:49, Weilin Du <weilin-du@qq.com> wrote:

Hi Ignace, David,

Thanks for the feedback. IMHO I tend to not accept Duration object as a parameter.

IntlRelativeDateTimeFormatter formats a caller-selected offset and unit. Time\Duration
represents stopwatch time as seconds and nanoseconds. This cause a huge amount of
issue which immediately comes into my head when thinking of this.

The API looks like

$fmt->format(3, UNIT_DAY); // in 3 days
$fmt->format(2, UNIT_MONTH); // in 2 months
$fmt->format(-1, UNIT_SUNDAY);// last Sunday

If we are now accepting Durations, they look like

Time\Duration::fromMinutes(90)

We don't know how to deal with 90 minutes here. It can be 90 minutes or 1.5 hour.

Nevertheless, what about weekdays? things like UNIT_SUNDAY are not durations.
Not to mention months, quarters, and years need calendar context.

For enums and namespaces: I kept class constants and the global Intl* class name to stay
consistent with the existing ext/intl API, such as IntlDateFormatter, IntlListFormatter
IntlNumberRangeFormatter, and IntlDatePatternGenerator. I don't want to make
IntlRelativeDateTimeFormatter somehow special here just because this is added later.
I agree that enums and namespaces would be nicer in isolation, *indeed*. But,
introducing them for only this one formatter would make the API inconsistent with the rest
of ext/intl.

For the second argument of ureldatefmt_open(): the initial implementation will pass NULL,
so ICU uses the default number formatter for the selected locale. *This is intended.*
Exposing a custom NumberFormatter is possible future scope, but it needs extra care
because ICU adopts ownership of the supplied UNumberFormat, so PHP would need to
clone the underlying formatter before passing it to ICU.

Well I guess you have time until next release to try out the value of this.

What do you think?

Cheers,
Weilin

5

Hi David,

I tried this as an experimental feature. The implementation is way more smoother than I
expected. As the numberFormatter class in PHP side is somehow very suitable for this.

The proposed constructor is now:

public function __construct(
?string $locale = null,
int $style = self::STYLE_LONG,
int $capitalizationContext = self::CAPITALIZATION_NONE,
?NumberFormatter $numberFormatter = null,
) {}

Also, considering enums and namespaces. Tim raised this suggestion to me before. So I’d
like to put this in the future scope of this RFC. A broader ext/intl modernization RFC could
revisit namespaces and PHP enums consistently across intl classes. This is not we are
supposed to do in this specific RFC imho. However, the idea is reasonable.

Thanks for the feedback!

Cheers,
Weilin