PHP 8.5: Intl: New IntlListFormatter
class
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.