PHP 8.5: Intl: новый класс IntlListFormatter

Расширение Intl в PHP 8.5 добавляет новый класс IntlListFormatter. Он обеспечивает форматирование списков с учётом локализации в удобные для чтения списки и-списки, или-списки или единицы.

Новый класс IntlListFormatter следует тем же шаблонам, что и другие классы из расширения Intl; он создаётся с помощью валидной строки локали и использует данные ICU для фактического форматирования.

$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

$formatter = new IntlListFormatter('ru-RU');
echo $formatter->format(['Zurich', 'Berlin', 'Amsterdam']);
// Zurich, Berlin и Amsterdam

Синопсис класса IntlListFormatter

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 {}

}

• Новый класс IntlListFormatter объявлен в глобальном пространстве имён.
• Он объявлен как final, поэтому его нельзя расширять (это гарантирует, что форматирование всегда будет использовать библиотеку ICU, что критично для согласованности локализации).

Константы IntlListFormatter::TYPE_

При создании объекта IntlListFormatter конструктор принимает параметр $type. По умолчанию он равен IntlListFormatter::TYPE_AND. Он может быть:

• IntlListFormatter::TYPE_AND: Группировать список как и-список. Например, X, Y и Z.
• IntlListFormatter::TYPE_OR: Группировать список как или-список. Например, X, Y или Z.
• IntlListFormatter::TYPE_UNITS: Группировать список как составную единицу, не основанную на и/или. Например, 4 часа, 30 минут.

Константы IntlListFormatter::WIDTH_

Третьим параметром конструктора IntlListFormatter является $width, принимающий одно из значений константы IntlListFormatter::WIDTH_. Значение по умолчанию — IntlListFormatter::WIDTH_WIDE.

Этот параметр контролирует, насколько узким или широким будет список. Возможно, исходный список потребуется скорректировать, чтобы он соответствовал этому параметру.

• IntlListFormatter::WIDTH_WIDE: Типичный форматтер списка, например X, Y и Z.
• IntlListFormatter::WIDTH_SHORT: Попытается сократить список. Если в языке есть более короткое слово и/или или символ, оно будет использовано. Например, A, B & C.
• IntlListFormatter::WIDTH_NARROW: Если в локали есть возможность, использовать максимально узкий способ форматирования списка. Часто при этом также опускается слово и. Например: A, B, C.

Не все языковые настройки имеют отдельные короткие или узкие формы. Как видно из примера de-DE ниже, все ширины могут давать одинаковые результаты, если языковая настройка не различает их.

Примеры использования

Форматирование списков в en-US

Форматирование списков в ru-RU

Форматирование списков в jp-JP

Форматирование списков в de-DE

Обработка ошибок

Если вызов format был успешным, метод getErrorCode возвращает int(0), а метод getErrorMessage возвращает "U_ZERO_ERROR".

Если метод IntlListFormatter::format возвращает false, это указывает на ошибку при форматировании. В этом случае методы getErrorCode и getErrorMessage могут предоставить дополнительную информацию.

Влияние на обратную совместимость

Класс PHP IntlListFormatter использует icu::ListFormatter из библиотеки ICU, добавленный в ICU 50.

Начиная с PHP 8.5, расширение Intl требует ICU 57.1 или более поздней версии, поэтому класс IntlListFormatter будет доступен во всех сборках расширения Intl.

Перечислив правила форматирования для различных локалей из CLDR, теоретически можно реализовать полифилл класса IntlListFormatter с помощью пользовательского PHP. Однако для этого потребуется извлечь и сохранить соответствующие данные CLDR для большинства, если не всех, локалей.