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 = 3;

    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