Re: [PHP-DEV] [RFC] IntlRelativeDateTimeFormatter

Hi

On 2026-08-07 20:46, Weilin Du wrote:
> 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.

As I had mentioned in the voting thread, I think there is a reasonable 
middleground to be achieved here:

     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, int $unit): 
string|false {}

         public function combineDateAndTime(string $relativeDate, string 
$time): string|false {}

         public function getErrorCode(): int {}

         public function getErrorMessage(): string {}
     }

     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;
         // ...
     }

The practical change for the users is just moving some separators 
around:

     $formatter->format(-1, IntlRelativeDateTimeFormatter::UNIT_DAY)
     // becomes
     $formatter->format(-1, IntlRelativeDateTimeFormatterUnit::Day)

Basically the first component of the constant name moves in front of the 
`::` (and underscores are replaced by pascal case).

No namespaces are introduced, leaving a clean place for a redesigned 
Intl API that doesn't just expose the ICU API as-is, but the main 
benefits of using enums are preserved: Better discoverability and 
autocompletion in IDEs. Cleaner documentation (it's possible to document 
both the enum and the individual cases). Simplified input checks in the 
internal implementation (error handling is implicitly provided by the 
engine with the Z_PARAM_ENUM specifier).

I believe that users will value the clearer API signatures provided by 
enums over the tiny inconsistency of placing the “Unit”, “Style” and 
“Capitalization” in front of the `::` instead of after - and enums 
themselves are already used in PHP’s stdlib (e.g. RoundingMode), so 
users have already encountered them.

Best regards
Tim Düsterhus