PHP: полный мануал с примерами, функциями и ООП

Первая задача: показать число по правилам читателя

В базе магазина хранится число 1234.5. Один посетитель ожидает 1,234.5, другой — 1.234,5. Это одно значение, но разные правила записи. Intl предоставляет готовые правила языков и регионов: числа, даты, алфавитный порядок, формы слов и обработку Unicode. Вам не нужно собирать сотни условий для каждого языка.

Локаль (locale) — идентификатор набора языковых правил. В de_DE de означает немецкий, DE — регион Германия. Локаль не является переводом вашего интерфейса, валютой счёта или часовым поясом. Расширение Intl использует ICU — библиотеку правил Unicode и данных локалей; PHP обращается к ней через функции и объекты.

<?php
declare(strict_types=1);

$formatter = new NumberFormatter("de_DE", NumberFormatter::DECIMAL);
echo $formatter->format(1234.5), "
";

1.234,5

<?php
declare(strict_types=1);

$english = new NumberFormatter("en_US", NumberFormatter::DECIMAL);
$german = new NumberFormatter("de_DE", NumberFormatter::DECIMAL);
echo $english->format(1234.5), "
";
echo $german->format(1234.5), "
";

1,234.5
1.234,5

Если пока незнакомы объект, метод или аргумент, сначала откройте механизм вызова функции и введение в объекты. Дальше каждая карточка начинает с минимального вызова, затем показывает применение и ограничения. Справочник охватывает весь официальный раздел Intl и текущие методы, для которых на PHP.net пока есть только краткая сигнатура.

Установка Intl и проверка того процесса, который обслуживает сайт

Intl — расширение PHP, а ICU — его внешняя библиотека. Исторический минимум ICU был 4.0; с PHP 7.4 требуется ICU 50.1 или новее. Отдельные возможности требуют более новой ICU: номер PHP сам по себе не доказывает наличие всех алгоритмов и данных.

<?php
declare(strict_types=1);

var_dump(extension_loaded("intl"));
var_dump(class_exists(NumberFormatter::class));
echo INTL_ICU_VERSION, " / ", INTL_ICU_DATA_VERSION, "
";

bool(true)
bool(true)
77.1 / 77.1

Три настройки php.ini и границы глобального состояния

<?php
declare(strict_types=1);

$previous = Locale::getDefault();
try {
    Locale::setDefault("de_DE");
    $formatter = new NumberFormatter(Locale::getDefault(), NumberFormatter::DECIMAL);
    echo $formatter->format(1234.5), "
";
} finally {
    Locale::setDefault($previous);
}

1.234,5

Отключить сообщения не значит обработать отказ. Пример $name = Normalizer::normalize($raw) нужно продолжать строгой проверкой false или подходящим catch. Иначе невалидное имя может попасть в базу как пустое.

Функция и метод: два способа вызвать одну операцию

Многие семейства предоставляют два интерфейса. Объектный стиль: $collator->compare($left, $right). Процедурный: collator_compare($collator, $left, $right). Во втором объект явно передаётся первым аргументом; правила сортировки остаются теми же. У некоторых новых семейств процедурной пары нет.

<?php
declare(strict_types=1);

$collator = collator_create("en_US");
$result = collator_compare($collator, "apple", "banana");
echo $result < 0 ? "apple first
" : "other order
";

apple first

<?php
declare(strict_types=1);

$collator = new Collator("en_US");
$result = $collator->compare("apple", "banana");
echo $result < 0 ? "apple first
" : "other order
";

apple first

Большинство текстовых API Intl принимает/возвращает UTF-8. Но UConverter специально работает с произвольными кодировками, getSortKey и getBinaryRules возвращают бинарные строки, а индексы некоторых API измеряются в UTF-16. Читайте договор конкретного метода: общая фраза «всё Unicode» не определяет единицы аргумента.

Выбрать семейство по реальной задаче

Collator: назначение, константы и операции

Языковая сортировка для каталога, адресной книги и поиска по названиям.

Класс

Collator связывает локаль и настройки с операциями. Процедурные collator_* функции используют тот же объект; это два интерфейса одного механизма. Ни один режим не делает строки безопасными для HTML и не решает права доступа. Версию ICU учитывайте при сохранении sort keys и воспроизводимых тестах.

Собственные операции: Collator::__construct, Collator::create, Collator::compare, Collator::sort, Collator::sortWithSortKeys, Collator::asort, Collator::getAttribute, Collator::setAttribute, Collator::getStrength, Collator::setStrength, Collator::getLocale, Collator::getErrorCode, Collator::getErrorMessage, Collator::getSortKey

NumberFormatter: назначение, константы и операции

Число остаётся числом в программе; локализованная строка появляется на границе интерфейса.

Класс

Один объект связывает locale, style, pattern, атрибуты и символы. Повторно используйте его для набора значений с одинаковой политикой. Не изменяйте случайно общий объект настройками соседнего отчёта. Ни format, ни parse не переводят валюту и не делают float точным decimal.

Собственные операции: NumberFormatter::__construct, NumberFormatter::create, NumberFormatter::format, NumberFormatter::parse, NumberFormatter::formatCurrency, NumberFormatter::parseCurrency, NumberFormatter::setAttribute, NumberFormatter::getAttribute, NumberFormatter::setTextAttribute, NumberFormatter::getTextAttribute, NumberFormatter::setSymbol, NumberFormatter::getSymbol, NumberFormatter::setPattern, NumberFormatter::getPattern, NumberFormatter::getLocale, NumberFormatter::getErrorCode, NumberFormatter::getErrorMessage

Normalizer: назначение, константы и операции

Одна видимая буква может иметь несколько допустимых представлений Unicode. Класс предоставляет статические операции; создавать объект не требуется.

Класс

Нормализация отвечает за представление Unicode. Сортировку по языку выполняет Collator, видимые символы считает grapheme_strlen, перевод алфавитов делает Transliterator. Эти задачи нельзя подменять одной заменой байтов.

Собственные операции: Normalizer::normalize, Normalizer::isNormalized, Normalizer::getRawDecomposition

IntlListFormatter: назначение, константы и операции

Список имён в письме или вариантов доставки должен читаться естественно на языке адресата.

Класс final: нельзя наследовать.

Начните с массива строк, затем выберите локаль и вид соединения. Метод не переводит сами элементы: названия товаров уже должны быть подготовлены приложением.

Собственные операции: IntlListFormatter::__construct, IntlListFormatter::format, IntlListFormatter::getErrorCode, IntlListFormatter::getErrorMessage

Locale: назначение, константы и операции

Локаль — набор предпочтений представления, который приложение выбирает для человека и передаёт форматтерам.

Класс

Все операции Locale статические: Locale::getRegion("en_US") не требует new Locale. Начните с фиксированного списка переводов, затем учитывайте сохранённый выбор пользователя и только потом заголовок браузера. Locale не переводит ваши тексты автоматически.

Собственные операции: Locale::getDefault, Locale::setDefault, Locale::getPrimaryLanguage, Locale::getScript, Locale::getRegion, Locale::getKeywords, Locale::getDisplayScript, Locale::getDisplayRegion, Locale::getDisplayName, Locale::getDisplayLanguage, Locale::getDisplayVariant, Locale::composeLocale, Locale::parseLocale, Locale::getAllVariants, Locale::filterMatches, Locale::lookup, Locale::canonicalize, Locale::acceptFromHttp, Locale::isRightToLeft, Locale::addLikelySubtags, Locale::minimizeSubtags

MessageFormatter: назначение, константы и операции

Шаблон хранит целое переводимое предложение, а массив приносит переменные данные: имя, количество, сумму.

Класс

Путь данных: ["name" => "Anna"] → {name} → "Hello, Anna!". Вызов format возвращает строку; echo отдельно показывает её. Сначала освойте одну подстановку, затем число и plural, потом select и вложенные сообщения.

Подробности синтаксиса и совместимости: руководство ICU MessageFormat. PHP MessageFormatter использует этот API; не считайте его реализацией любой новой версии MessageFormat 2.0.

Собственные операции: MessageFormatter::__construct, MessageFormatter::create, MessageFormatter::format, MessageFormatter::formatMessage, MessageFormatter::parse, MessageFormatter::parseMessage, MessageFormatter::setPattern, MessageFormatter::getPattern, MessageFormatter::getLocale, MessageFormatter::getErrorCode, MessageFormatter::getErrorMessage

Transliterator: назначение, константы и операции

Преобразователь изменяет представление Unicode по правилам ICU; он полезен для поисковых ключей, совместимости и известной схемы транслитерации.

Класс

Свойство id описывает выбранное преобразование. Создавайте его через фабрику и повторно используйте для серии строк. Оригиналы сохраняйте: упрощение часто необратимо. Подробный синтаксис: ICU Transforms.

Собственные операции: Transliterator::__construct, Transliterator::create, Transliterator::createFromRules, Transliterator::createInverse, Transliterator::listIDs, Transliterator::transliterate, Transliterator::getErrorCode, Transliterator::getErrorMessage

ResourceBundle: назначение, константы и операции

ICU хранит данные локалей как дерево ресурсов; ResourceBundle открывает это дерево для чтения.

Класс Интерфейсы: IteratorAggregate, Traversable, Countable.

Обычные приложения чаще используют NumberFormatter/IntlDateFormatter, которые сами читают нужные ICU-данные. ResourceBundle нужен при прямом доступе к ресурсам или собственном подготовленном пакете. get("ключ") похож на выбор подписанного отделения органайзера: внутри может лежать значение или ещё одна коробка. Аналогия не означает, что здесь PHP array: сложная ветка остаётся ResourceBundle.

Собственные операции: ResourceBundle::__construct, ResourceBundle::create, ResourceBundle::get, ResourceBundle::count, ResourceBundle::getLocales, ResourceBundle::getErrorCode, ResourceBundle::getErrorMessage, ResourceBundle::getIterator

Байты, кодовые точки и графемы: выберите единицу задачи

Для подписи посетителя обычно нужны графемы; для ограничения сетевого сообщения — байты; для Unicode-свойств — кодовая точка. Их нельзя взаимозаменять. Правила графем приближают то, что человек считает символом, но не измеряют ширину шрифта и не определяют смысл слова.

IntlDateFormatter: назначение, константы и операции

Дата в базе — момент или согласованные поля; дата на экране — представление по языку, календарю и поясу.

Класс

Разделяйте четыре понятия: Unix timestamp в секундах; IntlCalendar time в миллисекундах; часовой пояс; календарные поля. Для человека выбирайте локализованный формат, для API — заранее оговорённый формат обмена. Таблица символов ICU объясняет шаблоны и отличия от PHP date().

Собственные операции: IntlDateFormatter::__construct, IntlDateFormatter::create, IntlDateFormatter::getDateType, IntlDateFormatter::getTimeType, IntlDateFormatter::getCalendar, IntlDateFormatter::setCalendar, IntlDateFormatter::getTimeZoneId, IntlDateFormatter::getCalendarObject, IntlDateFormatter::getTimeZone, IntlDateFormatter::setTimeZone, IntlDateFormatter::setPattern, IntlDateFormatter::getPattern, IntlDateFormatter::getLocale, IntlDateFormatter::setLenient, IntlDateFormatter::isLenient, IntlDateFormatter::format, IntlDateFormatter::formatObject, IntlDateFormatter::parse, IntlDateFormatter::parseToCalendar, IntlDateFormatter::localtime, IntlDateFormatter::getErrorCode, IntlDateFormatter::getErrorMessage

IntlDatePatternGenerator: назначение, константы и операции

Генератор превращает набор желаемых полей в локализованный шаблон ICU.

Класс

Нужны год, месяц и день → skeleton yMd → шаблон вроде M/d/y или d.M.y → IntlDateFormatter → готовая дата. Не используйте возвращённый шаблон в PHP date(): это разные языки форматирования.

Собственные операции: IntlDatePatternGenerator::__construct, IntlDatePatternGenerator::create, IntlDatePatternGenerator::getBestPattern

IntlTimeZone: назначение, константы и операции

Пояс хранит правила перевода момента в местные часы. Он не равен текущему числу «+3 часа», стране или языку.

Класс

Для событий сохраняйте момент и нужный ID пояса. Для расписания «каждый день в 09:00» нужны также правила локального времени, включая пропущенные и повторённые часы при DST. IntlCalendar описывает разрешение таких ситуаций. Часть страниц PHP содержит только сигнатуры; дополнительные контракты сверены с реализацией PHP 8.5.11 и ICU TimeZone.

Собственные операции: IntlTimeZone::__construct, IntlTimeZone::countEquivalentIDs, IntlTimeZone::createDefault, IntlTimeZone::createEnumeration, IntlTimeZone::createTimeZone, IntlTimeZone::createTimeZoneIDEnumeration, IntlTimeZone::fromDateTimeZone, IntlTimeZone::getCanonicalID, IntlTimeZone::getDisplayName, IntlTimeZone::getDSTSavings, IntlTimeZone::getEquivalentID, IntlTimeZone::getErrorCode, IntlTimeZone::getErrorMessage, IntlTimeZone::getGMT, IntlTimeZone::getIanaID, IntlTimeZone::getID, IntlTimeZone::getOffset, IntlTimeZone::getRawOffset, IntlTimeZone::getRegion, IntlTimeZone::getTZDataVersion, IntlTimeZone::getUnknown, IntlTimeZone::getWindowsID, IntlTimeZone::getIDForWindowsID, IntlTimeZone::hasSameRules, IntlTimeZone::toDateTimeZone, IntlTimeZone::useDaylightTime

IntlCalendar: назначение, константы и операции

Календарь связывает момент с полями выбранной системы и правилами местного времени. Все изменения полей выполняются в объекте, а вычисление момента может откладываться.

Класс

Начните с createInstance("UTC", "en_US"), затем setTime(0) и чтения года/месяца. Когда строите новую дату из полей, сначала clear(), затем задайте все значимые поля. Месяц от 0; время ICU в миллисекундах. В реальном сервисе отдельно решите, храните ли вы момент события или обещание «09:00 по местному времени».

Собственные операции: IntlCalendar::__construct, IntlCalendar::createInstance, IntlCalendar::equals, IntlCalendar::fieldDifference, IntlCalendar::add, IntlCalendar::after, IntlCalendar::before, IntlCalendar::clear, IntlCalendar::fromDateTime, IntlCalendar::get, IntlCalendar::getActualMaximum, IntlCalendar::getActualMinimum, IntlCalendar::getAvailableLocales, IntlCalendar::getDayOfWeekType, IntlCalendar::getErrorCode, IntlCalendar::getErrorMessage, IntlCalendar::getFirstDayOfWeek, IntlCalendar::getGreatestMinimum, IntlCalendar::getKeywordValuesForLocale, IntlCalendar::getLeastMaximum, IntlCalendar::getLocale, IntlCalendar::getMaximum, IntlCalendar::getMinimalDaysInFirstWeek, IntlCalendar::setMinimalDaysInFirstWeek, IntlCalendar::getMinimum, IntlCalendar::getNow, IntlCalendar::getRepeatedWallTimeOption, IntlCalendar::getSkippedWallTimeOption, IntlCalendar::getTime, IntlCalendar::getTimeZone, IntlCalendar::getType, IntlCalendar::getWeekendTransition, IntlCalendar::inDaylightTime, IntlCalendar::isEquivalentTo, IntlCalendar::isLenient, IntlCalendar::isWeekend, IntlCalendar::roll, IntlCalendar::isSet, IntlCalendar::set, IntlCalendar::setDate, IntlCalendar::setDateTime, IntlCalendar::setFirstDayOfWeek, IntlCalendar::setLenient, IntlCalendar::setRepeatedWallTimeOption, IntlCalendar::setSkippedWallTimeOption, IntlCalendar::setTime, IntlCalendar::setTimeZone, IntlCalendar::toDateTime

IntlGregorianCalendar: назначение, константы и операции

Конкретная реализация IntlCalendar для григорианской системы с настраиваемым историческим переходом от юлианской.

Класс Родитель: IntlCalendar.

Все поля, арифметика, timezone и правила недели наследуются из IntlCalendar. Дополнительные методы решают создание из полей, високосность и границу календарной реформы. Не путайте юлианский календарь с FIELD_JULIAN_DAY: последнее — числовой номер дня.

Собственные операции: IntlGregorianCalendar::createFromDate, IntlGregorianCalendar::createFromDateTime, IntlGregorianCalendar::__construct, IntlGregorianCalendar::setGregorianChange, IntlGregorianCalendar::getGregorianChange, IntlGregorianCalendar::isLeapYear

UConverter: назначение, константы и операции

Конвертер декодирует байты источника в Unicode, затем кодирует Unicode в целевые байты. Именно на этих двух границах возникают разные ошибки.

Класс

Схема: Latin-1 E9 → Unicode U+00E9 → UTF-8 C3 A9. from/to в имени callback относятся к Unicode, а не к направлению бизнес-интеграции. Сначала используйте известную пару кодировок, затем явную политику замены и только при необходимости наследник с callbacks. Документация многих методов содержит лишь synopsis; детали сверены с исходниками PHP 8.5.11 UConverter.

Собственные операции: UConverter::__construct, UConverter::convert, UConverter::fromUCallback, UConverter::getAliases, UConverter::getAvailable, UConverter::getDestinationEncoding, UConverter::getDestinationType, UConverter::getErrorCode, UConverter::getErrorMessage, UConverter::getSourceEncoding, UConverter::getSourceType, UConverter::getStandards, UConverter::getSubstChars, UConverter::reasonText, UConverter::setDestinationEncoding, UConverter::setSourceEncoding, UConverter::setSubstChars, UConverter::toUCallback, UConverter::transcode

Spoofchecker: назначение, константы и операции

Проверка помогает заметить, что новое имя похоже на существующее или нарушает разрешённый профиль символов.

Класс

Не смешивайте три пространства констант: setChecks принимает маску проверок, setRestrictionLevel один уровень, setAllowedChars свои опции UnicodeSet. Переменная errorCode у isSuspicious/areConfusable получает маску найденных признаков при успешном вызове, несмотря на неоднозначное имя. Это подтверждается реализацией PHP.

Собственные операции: Spoofchecker::__construct, Spoofchecker::isSuspicious, Spoofchecker::areConfusable, Spoofchecker::setAllowedLocales, Spoofchecker::setChecks, Spoofchecker::setRestrictionLevel, Spoofchecker::setAllowedChars

Граница — место между символами, а не сам символ

Редактору нужно поставить курсор после целого символа, поиску — выделить слово, аннотации — взять первое предложение. Разрезать UTF-8 по случайному байту нельзя: одна буква может занимать несколько байтов, а один видимый знак — несколько кодовых точек. Итератор хранит исходный текст и текущее место между его частями; next передвигает это место.

Именно байтовые позиции возвращает PHP IntlBreakIterator. Поэтому найденные начала и длины можно передавать substr, но нельзя без преобразования передавать как символьные индексы mb_substr. Character работает с границами графем, CodePoint — кодовых точек. Границы слова включают пробелы и пунктуацию: чтобы считать только слова, используйте статус сегмента.

Последовательность: создать подходящий итератор → setText → first/next или foreach → получить позиции либо getPartsIterator для готовых фрагментов. Объект хранит изменяемую позицию: два вложенных обхода одного объекта мешают друг другу. Для независимых обходов используйте разные объекты/копии. Повторно используйте настроенный объект для последовательных текстов: создание анализатора дороже смены текста. Результаты языковых правил могут меняться с ICU и словарями.

IntlBreakIterator: назначение, константы и операции

Базовый API поиска границ графем, кодовых точек, слов, строк и предложений.

Класс Интерфейсы: IteratorAggregate, Traversable.

0 и конец текста — полноценные границы. Результаты сегментации не доказывают, что слово существует в словаре или что произвольная строка написана грамматически верно. Для поискового морфологического анализа нужен другой уровень обработки. IntlRuleBasedBreakIterator добавляет статусы правил, IntlPartsIterator возвращает текст сегментов.

Собственные операции: IntlBreakIterator::createCharacterInstance, IntlBreakIterator::createCodePointInstance, IntlBreakIterator::createLineInstance, IntlBreakIterator::createSentenceInstance, IntlBreakIterator::createTitleInstance, IntlBreakIterator::createWordInstance, IntlBreakIterator::__construct, IntlBreakIterator::current, IntlBreakIterator::first, IntlBreakIterator::following, IntlBreakIterator::getErrorCode, IntlBreakIterator::getErrorMessage, IntlBreakIterator::getLocale, IntlBreakIterator::getPartsIterator, IntlBreakIterator::getText, IntlBreakIterator::isBoundary, IntlBreakIterator::last, IntlBreakIterator::next, IntlBreakIterator::preceding, IntlBreakIterator::previous, IntlBreakIterator::setText, IntlBreakIterator::getIterator

IntlRuleBasedBreakIterator: назначение, константы и операции

Анализатор с правилами ICU: стандартные word/line/sentence фабрики часто возвращают именно его.

Класс Родитель: IntlBreakIterator. Интерфейсы: Traversable, IteratorAggregate.

Методы границ наследуются из IntlBreakIterator. Дополнительные операции позволяют получить грамматику, её бинарное представление и метки сработавших правил. Это полезно для объяснимой классификации каждого сегмента. Для переносимых собственных правил храните текст и версию ICU вместе с контрольными примерами.

Собственные операции: IntlRuleBasedBreakIterator::__construct, IntlRuleBasedBreakIterator::getBinaryRules, IntlRuleBasedBreakIterator::getRules, IntlRuleBasedBreakIterator::getRuleStatus, IntlRuleBasedBreakIterator::getRuleStatusVec

Почему next() и next(n) различаются при чтении кодовой точки

<?php
declare(strict_types=1);

$iterator = IntlBreakIterator::createCodePointInstance();
$iterator->setText("Aя");
$iterator->next();
$iterator->next();
echo $iterator->getLastCodePoint(), "
";

1103

IntlCodePointBreakIterator: назначение, константы и операции

Специализация для обхода отдельных кодовых точек UTF-8.

Класс Родитель: IntlBreakIterator. Интерфейсы: Traversable, IteratorAggregate.

Получается фабрикой createCodePointInstance. Не используйте такой обход для удаления «последнего видимого символа»: можно оставить оторванный комбинируемый знак; для пользовательского текста нужна графемная граница.

Собственные операции: IntlCodePointBreakIterator::getLastCodePoint

IntlIterator: назначение, константы и операции

Общий объект последовательного обхода, который возвращают различные фабрики Intl.

Класс Интерфейсы: Iterator, Traversable.

Обычно вы получаете его из операции другого класса, а не создаёте пустой объект вручную. Например, IntlTimeZone возвращает перечисления зон, а IntlPartsIterator отдаёт части текста. Iterator — договор из пяти методов; foreach вызывает их за вас. Для маленького набора iterator_to_array удобен, но сохраняет все элементы в памяти.

Собственные операции: IntlIterator::current, IntlIterator::key, IntlIterator::next, IntlIterator::rewind, IntlIterator::valid

IntlPartsIterator: назначение, константы и операции

Готовые текстовые фрагменты между границами; наследует методы Iterator от IntlIterator.

Класс Родитель: IntlIterator. Интерфейсы: Traversable, Iterator.

Получайте через getPartsIterator. KEY_LEFT/RIGHT измеряются в байтах исходного UTF-8. Справа граница не включена: substr(text, left, right - left). Чтение частей не нормализует строку и не удаляет пробелы автоматически.

Собственные операции: IntlPartsIterator::getBreakIterator, IntlPartsIterator::getRuleStatus

IntlChar: от непонятного символа к его номеру и свойствам

В выгрузке пришёл внешне обычный пробел, но поиск его не находит. Для человека он похож на другой, а Unicode присвоил каждому свой номер. IntlChar позволяет посмотреть одну кодовую точку: номер, имя, категорию, числовое значение, регистр и свойства. Это похоже на справочную карточку отдельной детали. Ограничение модели: один видимый знак может состоять из нескольких деталей — буква плюс акцент или emoji sequence.

<?php
declare(strict_types=1);

echo IntlChar::ord("А"), "
";

1040

<?php
declare(strict_types=1);

$points = ["e", "\u{0301}"];
foreach ($points as $point) printf("U+%04X\n", IntlChar::ord($point));
echo 'Графем: ', grapheme_strlen(implode('', $points)), "\n";

U+0065
U+0301
Графем: 1

Почти все методы с codepoint возвращают null при некорректном входе. Ошибку читают сразу через intl_get_error_code/message; поведение exception/error_level зависит от настройки intl. false у предиката обычно означает корректный символ без свойства. Методы именования свойств возвращают false, digit имеет false, forDigit возвращает integer0, числовое отсутствие — NO_NUMERIC_VALUE: универсальное if(!$result) ошибочно. Подробнее intl_get_error_code.

Таблица кодовых точек включает surrogate диапазон D800–DFFF, но это не самостоятельные Unicode scalar values. PHP8.5 wrapper проверяет общий диапазон, поэтому для генерации UTF-8 из недоверенного integer сначала исключают surrogate значения. Присвоенность isdefined не заменяет эту проверку. Noncharacters и private use тоже требуют политики конкретного протокола. Этот класс не доказывает язык текста, наличие глифа, безопасность логина или правильность HTML.

Применение к форме и импорту: от строки к понятной диагностике

Теперь применим справочник к целому значению из импорта. Сначала строку UTF-8 разделяют на кодовые точки, затем у каждого элемента спрашивают нужное свойство. Программа ниже только объясняет подозрительный промежуток: она не удаляет форматирующие знаки из имени клиента и не меняет данные без выбранного правила.

<?php
declare(strict_types=1);

$input = "ID\u{00A0}A42";
$points = preg_split('//u', $input, -1, PREG_SPLIT_NO_EMPTY);
if ($points === false) throw new InvalidArgumentException('Ожидался корректный UTF-8');
foreach ($points as $index => $char) {
    if (IntlChar::isUWhiteSpace($char)) {
        printf("Позиция %d: U+%04X %s\n", $index, IntlChar::ord($char), IntlChar::charName($char));
    }
}

Позиция 2: U+00A0 NO-BREAK SPACE

<?php
declare(strict_types=1);

$input = '٢٣';
$points = preg_split('//u', $input, -1, PREG_SPLIT_NO_EMPTY);
if ($points === false || $points === [] || count($points) > 3) throw new InvalidArgumentException('Нужны от1 до3 цифр');
$quantity = 0;
foreach ($points as $char) {
    $digit = IntlChar::charDigitValue($char);
    if ($digit === null || $digit < 0) throw new InvalidArgumentException('Разрешены только десятичные цифры');
    $quantity = $quantity * 10 + $digit;
}
echo "Количество: $quantity\n";

Количество: 23

Упражнение: дополните отчёт названиями категорий, сохраняя исходную строку. Для каждого элемента получите charType и передайте результат в getPropertyValueName с PROPERTY_GENERAL_CATEGORY. Проверьте текст с обычным пробелом, NBSP и буквой с отдельным акцентом. Объясните, почему последняя видимая буква может дать две строки отчёта. Решение строится из уже показанного обхода и карточек charType/getPropertyValueName; строковое исправление выполняют только после согласования правил импорта.

IntlChar: назначение, константы и операции

Справочник одной Unicode точки: номер, имя, свойства, преобразования и все константы.

Класс

Константы читаются как IntlChar::PROPERTY_SCRIPT без скобок. PROPERTY_* выбирает вопрос; CHAR_CATEGORY_*, BLOCK_CODE_* и другие enum группы описывают ответ. SHORT/LONG_PROPERTY_NAME выбирает форму подписи. COUNT/LIMIT — служебные границы, а не ещё один допустимый вариант. Выше показаны все 666 констант текущего PHP8.5 / ICU77.1 снимка с назначением.

Имена блоков и joining groups сохранены как стандартные Unicode обозначения. ICU может знать более новые значения, для которых PHP обёртка ещё не экспортирует отдельную константу: используйте getPropertyEnum/getPropertyValueEnum и проверяйте результат. Не считайте COUNT размером плотного списка имён. Некоторые старые aliases остаются для совместимости. Все методы статические: создавать IntlChar объект для каждого символа не нужно.

Практический маршрут: неизвестный знак → ord + charName → charType / нужное property → понятное решение импорта. Для всей строки не используйте $text[$i] как Unicode обход. Выберите разбиение по кодовым точкам или BreakIterator и ограничьте длину входа. Для видимой длины — grapheme_strlen, для нормализации — Normalizer::normalize, для похожих знаков в логинах — Spoofchecker::isSuspicious. Эти операции дополняют друг друга.

Собственные операции: IntlChar::hasBinaryProperty, IntlChar::charAge, IntlChar::charDigitValue, IntlChar::charDirection, IntlChar::charFromName, IntlChar::charMirror, IntlChar::charName, IntlChar::charType, IntlChar::chr, IntlChar::digit, IntlChar::enumCharNames, IntlChar::enumCharTypes, IntlChar::foldCase, IntlChar::forDigit, IntlChar::getBidiPairedBracket, IntlChar::getBlockCode, IntlChar::getCombiningClass, IntlChar::getFC_NFKC_Closure, IntlChar::getIntPropertyMaxValue, IntlChar::getIntPropertyMinValue, IntlChar::getIntPropertyValue, IntlChar::getNumericValue, IntlChar::getPropertyEnum, IntlChar::getPropertyName, IntlChar::getPropertyValueEnum, IntlChar::getPropertyValueName, IntlChar::getUnicodeVersion, IntlChar::isalnum, IntlChar::isalpha, IntlChar::isbase, IntlChar::isblank, IntlChar::iscntrl, IntlChar::isdefined, IntlChar::isdigit, IntlChar::isgraph, IntlChar::isIDIgnorable, IntlChar::isIDPart, IntlChar::isIDStart, IntlChar::isISOControl, IntlChar::isJavaIDPart, IntlChar::isJavaIDStart, IntlChar::isJavaSpaceChar, IntlChar::islower, IntlChar::isMirrored, IntlChar::isprint, IntlChar::ispunct, IntlChar::isspace, IntlChar::istitle, IntlChar::isUAlphabetic, IntlChar::isULowercase, IntlChar::isupper, IntlChar::isUUppercase, IntlChar::isUWhiteSpace, IntlChar::isWhitespace, IntlChar::isxdigit, IntlChar::ord, IntlChar::tolower, IntlChar::totitle, IntlChar::toupper

IntlException: назначение, константы и операции

Исключение для ошибок расширения Intl; наследует обычный Exception.

Класс Родитель: Exception. Интерфейсы: Throwable, Stringable.

Включение intl.use_exceptions переводит многие ICU-ошибки в IntlException. Однако не все случаи зависят только от этой настройки: например, конструктор IntlRuleBasedBreakIterator явно бросает IntlException при неверных правилах. Ошибка типа или недопустимый PHP-аргумент могут быть TypeError/ValueError. Не перехватывайте только IntlException и не считайте все другие ошибки невозможными.

<?php
declare(strict_types=1);

$before = ini_set("intl.use_exceptions", "1");
try {
    Normalizer::normalize("\xFF");
} catch (IntlException $error) {
    echo "conversion failed
";
} finally {
    if ($before !== false) { ini_set("intl.use_exceptions", $before); }
}

conversion failed

<?php
declare(strict_types=1);

$before = ini_set("intl.use_exceptions", "0");
try {
    new IntlRuleBasedBreakIterator("[");
} catch (IntlException $error) {
    echo "rules rejected
";
} finally {
    if ($before !== false) { ini_set("intl.use_exceptions", $before); }
}

rules rejected

Собственные операции: Собственных методов нет; используйте унаследованные.

Все глобальные константы Intl: режимы, версии и ошибки

Имена важнее чисел: значения отражают PHP 8.5.11 / ICU 77.1, а в другом окружении зависящие от библиотеки константы могут отличаться. Три разных договора: режим операции, код состояния ICU и битовая маска ошибок IDNA. Их нельзя взаимозаменять. Для кода ICU используйте intl_is_failure; для IDNA errors — побитовую проверку конкретного флага.

Версии, локали и графемы

IDNA: режимы и отдельная маска errors

UErrorCode: статусы ICU и границы диапазонов

Историческая INTL_IDNA_VARIANT_2003 отсутствует в текущем runtime. Она была deprecated с PHP 7.2; сегодня выбирайте UTS46. Не объявляйте её вручную, чтобы обойти несовместимость. Историческая документация также указывает limit locale 80 и transitional default; текущие значения выше получены из установленной ICU, поэтому справочник явно показывает разницу.

Домен в Unicode и ASCII: куда относится IDNA

Читатель видит bücher.example, а система может ожидать xn--bcher-kva.example. idn_to_ascii и idn_to_utf8 преобразуют именно имя домена. URL содержит также схему, порт, путь, query; их нельзя целиком передать в IDNA. После преобразования отдельно проверяются допустимость адреса вашей интеграцией и ограничения сетевого доступа.

Ошибки, единицы измерения и воспроизводимость результата

Последовательность надёжной интеграции: понять формат поставщика → ограничить размер входа → проверить кодировку и структуру → получить смысловые значения → применить правила продукта → оформить для выбранного читателя. Intl решает языковые операции в середине этой цепочки; авторизация, HTML-экранирование, SQL-параметры и бизнес-проверки остаются отдельными шагами.

Какие операции могут быть дорогими

Сначала измеряйте свой объём и результат, затем оптимизируйте. Нельзя обещать одинаковую скорость для ICU разных версий и разных языков. Повторное использование объектов не означает бесконтрольный глобальный singleton с постоянно меняющейся locale.

Вопросы из практики и разобранные решения

Обсуждения ниже дали реальные ситуации, в которых синтаксиса функции недостаточно. Ответы разных лет не являются нормативным источником: контракты сверены с PHP Manual, текущим PHP и ICU; учебные примеры написаны отдельно.

Полный указатель Intl: классы, методы и процедурные формы

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