PHP 8.5: Intl: New `IntlListFormatter` class

Version8.5

TypeNew Feature

The Intl extension in PHP 8.5 adds a new class named IntlListFormatter. It provides locale-aware formatting for lists into human-readable lists of "and"-lists, "or"-lists, or units.

The new IntlListFormatter class follows the same patterns as other classes from the Intl extension; it is instantiated with a valid locale string, and uses ICU data for the actual formatting.

$formatter = new IntlListFormatter('en-US');
$formatter->format(['Zurich', 'Berlin', 'Amsterdam']);
// Zurich, Berlin, and Amsterdam

$formatter = new IntlListFormatter('nl-NL');
echo $formatter->format(['Zurich', 'Berlin', 'Amsterdam']);
// Zurich, Berlin en Amsterdam

$formatter = new IntlListFormatter('id-ID');
echo $formatter->format(['Zurich', 'Berlin', 'Amsterdam']);
// Zurich, Berlin, dan Amsterdam

`IntlListFormatter` Class Synopsis

final class IntlListFormatter {

    public const int TYPE_AND = 0;
    public const int TYPE_OR = 1;
    public const int TYPE_UNITS = 2;

    public const int WIDTH_WIDE = 0;
    public const int WIDTH_SHORT = 1;
    public const int WIDTH_NARROW = 2;

    public function __construct(
        string $locale,
        int $type = IntlListFormatter::TYPE_AND,
        int $width = IntlListFormatter::WIDTH_WIDE
    ) {}

    public function format(array $strings): string|false {}

    public function getErrorCode(): int {}
    public function getErrorMessage(): string {}

}

The new IntlListFormatter class is declared in the global namespace.
It is declared final, so it is not possible to extend this class.

`IntlListFormatter::TYPE_` constants

When instantiating an IntlListFormatter object, the constructor accepts a $type parameter. By default, it is IntlListFormatter::TYPE_AND. It can be:

IntlListFormatter::TYPE_AND: Group the list as "and"-list. e.g. X, Y, and Z.
IntlListFormatter::TYPE_OR: Group the list as "or"-list. e.g. X, Y, or Z.
IntlListFormatter::TYPE_UNITS: Group the list as a compound unit, which is not based on and/or. e.g. 4 hours, 30 minutes.

`IntlListFormatter::WIDTH_` constants

The third parameter of the IntlListFormatter constructor is $width, which accepts one of the IntlListFormatter::WIDTH_ constants. The default value is IntlListFormatter::WIDTH_WIDE.

This parameter controls how narrow or wide the list would be. The input list might need to be adjusted to be consistent with this.

IntlListFormatter::WIDTH_WIDE: The typical list formatter, e.g. X, Y, and Z
IntlListFormatter::WIDTH_SHORT: Attempt to make the list shorter. If the language has a shorter "and"/"or" word or a symbol, it will be used. e.g. A, B & C
IntlListFormatter::WIDTH_NARROW: If the locale has one, use the narrowest possible way to format the list. It often drops the "and" word too. e.g. A, B, C.

Not all locales have distinct short or narrow forms. As seen in the de-DE example below, all width may product identical outputs if the locale does not differentiate them.

Usage Examples

Formatting lists in en-US

`en-US`	`TYPE_AND`	`TYPE_OR`	`TYPE_UNITS`
`WIDTH_WIDE`	A, B, and C	A, B, or C	A, B, C
`WIDTH_SHORT`	A, B, & C	A, B, or C	A, B, C
`WIDTH_NARROW`	A, B, C	A, B, or C	A B C

Formatting lists in ja-JP

`ja-JP`	`TYPE_AND`	`TYPE_OR`	`TYPE_UNITS`
`WIDTH_WIDE`	水、火、木	水、火、または木	水火木
`WIDTH_SHORT`	水、火、木	水、火、または木	水火木
`WIDTH_NARROW`	水、火、木	水、火、または木	水火木

Formatting lists in de-DE

`de-DE`	`TYPE_AND`	`TYPE_OR`	`TYPE_UNITS`
`WIDTH_WIDE`	A, B und C	A, B oder C	A, B und C
`WIDTH_SHORT`	A, B und C	A, B oder C	A, B und C
`WIDTH_NARROW`	A, B und C	A, B oder C	A, B und C

Error handling

If the format call was successful, the getErrorCode method returns int(0), and the getErrorMessage method returns "U_ZERO_ERROR".

If the IntlListFormatter::format method returns false, it indicates an error while formatting. The getErrorCode and getErrorMessage methods can provide more information in this case.

Backward Compatibility Impact

The IntlListFormatter PHP class uses icu::ListFormatter from the ICU library, which was added in ICU 50.

As of PHP 8.5, the Intl extension requires ICU 57.1 or later, so the IntlListFormatter class will be available across all Intl extension builds.

By enumerating the formatting rules for various locales from CLDR (Common Locale Data Repository), it is theoretically possible to polyfill the IntlListFormatter class with user-land PHP. It will, however, need to extract and store the relevant CLDR data for most, if not all, locales.

IntlListFormatter Implementation

PHP 8.5: Intl: New IntlListFormatter class

IntlListFormatter Class Synopsis

IntlListFormatter::TYPE_ constants

IntlListFormatter::WIDTH_ constants