<?php
declare(strict_types=1);

$supplierBytes = "\xD7\xE0\xE9";
$name = iconv('Windows-1251', 'UTF-8', $supplierBytes);
if ($name === false) { throw new RuntimeException('Не удалось прочитать название'); }
echo $name, "\n";
echo bin2hex($supplierBytes), ' -> ', bin2hex($name), "\n";

Чай
d7e0e9 -> d0a7d0b0d0b9

Слева три байта старого формата, справа шесть байт UTF-8. bin2hex только показывает байты; само преобразование делает iconv. Проверка === false отделяет ошибку от допустимых пустой строки и строки "0".

<?php
declare(strict_types=1);

$line = "SKU-7;Чай;2\r\n";
$export = iconv('UTF-8', 'Windows-1251', $line);
if ($export === false) { throw new RuntimeException('Строка не представима в формате обмена'); }
echo bin2hex($export), "\n";
echo iconv('Windows-1251', 'UTF-8', $export);

534b552d373bd7e0e93b320d0a
SKU-7;Чай;2

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

<?php
declare(strict_types=1);

$priceLabel = 'A€B';
echo iconv('UTF-8', 'ASCII//IGNORE', $priceLabel), "\n";
echo iconv('UTF-8', 'ASCII//TRANSLIT', $priceLabel), "\n";

AB
AEURB

Точный результат TRANSLIT проверен на libiconv 1.19 в данной PHP 8.5.11. Другой backend/окружение может дать иную замену или отказ. Нельзя строить переносимый идентификатор или правило равенства людей на таком результате.

<?php
declare(strict_types=1);

$diagnostic = null;
set_error_handler(static function (int $level, string $message) use (&$diagnostic): bool {
    $diagnostic = $level; // Только тип ошибки, без содержимого входной строки.
    return true;
}, E_NOTICE | E_WARNING);
try { $text = iconv('UTF-8', 'UTF-8', "A\xFFB"); }
finally { restore_error_handler(); }
echo $text === false && $diagnostic !== null ? "Импорт отклонён\n" : "Принят\n";

Импорт отклонён

Обработчик ограничен одним вызовом и обязательно снят. В приложении запишите безопасный ID пакета и причину, а не весь текст клиента. Фреймворк может преобразовать notice в ErrorException: тогда учитывается его политика ошибок, а не добавляется @.

<?php
declare(strict_types=1);

$name = 'Чай';
echo strlen($name), " bytes\n";
echo iconv_strlen($name, 'UTF-8'), " characters\n";
echo iconv_strlen("e\u{0301}", 'UTF-8'), " code points\n";

6 bytes
3 characters
2 code points

Комбинирующий акцент U+0301 здесь указан явно. Если продукт считает то, что человек воспринимает одной буквой, нужен grapheme_strlen из Intl, а не замена лимита байтов лимитом кодовых точек.

<?php
declare(strict_types=1);

$name = 'Чай с мятой';
$length = iconv_strlen($name, 'UTF-8');
if ($length === false) { throw new RuntimeException('Неверная кодировка'); }
$accepted = $length <= 20 && strlen($name) <= 64;
echo $accepted ? "Название подходит\n" : "Слишком длинно\n";
var_dump(iconv_strlen('', 'UTF-8'));

Название подходит
int(0)

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

<?php
declare(strict_types=1);

$title = 'Чай, кофе, чай';
var_dump(iconv_strpos($title, 'Чай', 0, 'UTF-8'));
var_dump(iconv_strpos($title, 'кофе', 0, 'UTF-8'));
var_dump(iconv_strpos($title, 'сок', 0, 'UTF-8'));

int(0)
int(5)
bool(false)

Ноль — успешный поиск в начале. Проверяйте !== false; условие if ($position) пропустит найденное первое слово. Поиск чувствителен к регистру: Чай и чай различаются.

<?php
declare(strict_types=1);

$labels = 'чай|кофе|чай';
$first = iconv_strpos($labels, 'чай', 0, 'UTF-8');
if ($first === false) { throw new RuntimeException('Первой метки нет'); }
$second = iconv_strpos($labels, 'чай', $first + 1, 'UTF-8');
echo $first, '/', $second, "\n";
echo iconv_strpos($labels, 'чай', -3, 'UTF-8'), "\n";

0/9
9

offset — точка, с которой начинается просмотр; возвращаемая позиция всё равно отсчитывается от начала всей строки. +1 допускает перекрывающиеся совпадения; для неперекрывающихся прибавьте длину непустой искомой строки.

<?php
declare(strict_types=1);

$label = 'чай / набор / 2026';
var_dump(iconv_strrpos($label, ' / ', 'UTF-8'));
var_dump(iconv_strrpos('чай', 'чай', 'UTF-8'));

int(11)
int(0)

Результат — начало последнего совпадения, отсчитанное от начала строки. Значение 0 также является успехом.

<?php
declare(strict_types=1);

$label = 'чай / набор / 2026';
$position = iconv_strrpos($label, ' / ', 'UTF-8');
$visible = $position === false ? $label : iconv_substr($label, 0, $position, 'UTF-8');
echo $visible, "\n";
var_dump(iconv_strrpos($label, 'нет', 'UTF-8'));

чай / набор
bool(false)

Это фиксированный формат метки, а не парсер пути/URL. При отсутствии разделителя оставляем весь текст. Оба этапа используют символы, поэтому кириллица не сдвигает границу.

<?php
declare(strict_types=1);

$text = 'Чай с мятой';
echo iconv_substr($text, 0, 3, 'UTF-8'), "\n";
echo iconv_substr($text, -5, null, 'UTF-8'), "\n";
echo iconv_substr('абвг', 1, -1, 'UTF-8'), "\n";

Чай
мятой
бв

Нулевой offset начинает с первой буквы, -5 берёт старт за пять символов до конца, null означает всё до конца. Отрицательная length отбрасывает указанное число символов с конца, а не идёт назад.

<?php
declare(strict_types=1);

$description = 'Чай с мятой';
$limit = 5;
$length = iconv_strlen($description, 'UTF-8');
if ($length === false) { throw new RuntimeException('Неверный текст'); }
$preview = $length > $limit ? iconv_substr($description, 0, $limit, 'UTF-8') . '…' : $description;
echo $preview, "\n";
var_dump(iconv_substr('абвг', 4, null, 'UTF-8'));
var_dump(iconv_substr('абвг', 99, null, 'UTF-8'));

Чай с…
string(0) ""
string(0) ""

Многоточие добавляет ещё один знак к пяти выбранным. Это ограничение по кодовым точкам, не по словам/графемам: составной emoji или буква с комбинирующим знаком всё ещё может оказаться разделённой.

<?php
declare(strict_types=1);

$field = iconv_mime_encode('Subject', 'Заказ готов', [
    'input-charset' => 'UTF-8',
    'output-charset' => 'UTF-8',
]);
if ($field === false) { throw new RuntimeException('Тема не закодирована'); }
echo $field, "\n";
echo iconv_mime_decode($field, ICONV_MIME_DECODE_STRICT, 'UTF-8'), "\n";

Subject: =?UTF-8?B?0JfQsNC60LDQtyDQs9C+0YLQvtCy?=
Subject: Заказ готов

Первая строка — фактическое содержимое поля для передачи: Subject — его имя, UTF-8 — кодировка исходного текста, B — упаковка байтов в Base64, заключительное ?= закрывает encoded-word. Вторая строка показывает, что прочитает почтовая программа после декодирования. Само письмо пока никуда не отправляется. Если API отправки принимает только значение темы, нельзя передать ему целое поле Subject:; иначе имя продублируется.

<?php
declare(strict_types=1);

$subject = 'Чай с мятой: заказ №42';
$field = iconv_mime_encode('Subject', $subject, [
    'scheme' => 'Q', 'input-charset' => 'UTF-8', 'output-charset' => 'UTF-8',
    'line-length' => 60, 'line-break-chars' => "\r\n",
]);
if ($field === false) { throw new RuntimeException('Тема не закодирована'); }
$lines = explode("\r\n", $field);
foreach ($lines as $index => $line) {
    echo 'Строка ', $index + 1, ': ', $line, "\n";
    echo 'Байт: ', strlen($line), "\n";
}
echo 'После чтения: ', iconv_mime_decode($field, ICONV_MIME_DECODE_STRICT, 'UTF-8'), "\n";

Строка 1: Subject: =?UTF-8?Q?=D0=A7=D0=B0=D0=B9=20=D1=81=20=D0=BC?=
Байт: 57
Строка 2:  =?UTF-8?Q?=D1=8F=D1=82=D0=BE=D0=B9:=20=D0=B7=D0=B0=D0=BA?=
Байт: 59
Строка 3:  =?UTF-8?Q?=D0=B0=D0=B7=20=E2=84=9642?=
Байт: 39
После чтения: Subject: Чай с мятой: заказ №42

В выводе видны сами строки поля, их длины и восстановленная тема. Пробел в начале продолжения связывает его с тем же полем Subject. PHP-файл следует сохранить в UTF-8, иначе обещание input-charset не совпадёт с байтами. Лимит 60 выбран для наглядности, стандартное значение функции — 76. Точное разбиение здесь относится к проверенной сборке, а смысл темы должен сохраняться при любом корректном разбиении.

<?php
declare(strict_types=1);

$subject = "Готово\r\nBcc: injected@example.invalid";
if (str_contains($subject, "\r") || str_contains($subject, "\n")) {
    echo "Тема должна быть одной логической строкой\n";
} else {
    $field = iconv_mime_encode('Subject', $subject,
        ['input-charset' => 'UTF-8', 'output-charset' => 'UTF-8']);
    echo $field === false ? "Ошибка кодировки\n" : "Тема подготовлена\n";
}

Тема должна быть одной логической строкой

Имя поля фиксировано разработчиком, входные CR/LF отклоняются до кодирования. Разрешённые переносы создаёт сама функция. Это один слой безопасного формирования темы; адреса, вложения и полноценную отправку должен собирать почтовый компонент с отдельными правилами.

<?php
declare(strict_types=1);

$field = 'Subject: =?UTF-8?Q?=D0=A7=D0=B0=D0=B9?=';
$decoded = iconv_mime_decode($field, ICONV_MIME_DECODE_STRICT, 'UTF-8');
if ($decoded === false) { throw new RuntimeException('Неверная тема'); }
echo $decoded, "\n";

Subject: Чай

Имя Subject остаётся в результате, если было во входе. Можно декодировать и только значение. Q-encoded слово — не произвольная строка для quoted_printable_decode: нужно также разобрать оболочку и применить заявленную кодировку.

<?php
declare(strict_types=1);

$value = "=?UTF-8?B?0KfQsNC5?=\r\n =?UTF-8?B?INGBINC80Y/RgtC+0Lk=?=";
echo iconv_mime_decode($value, ICONV_MIME_DECODE_STRICT, 'UTF-8'), "\n";

Чай с мятой

Пробел, который является частью фразы, находится внутри второго encoded-word. Служебные пробелы/перенос между соседними encoded-word не следует вручную удалять или добавлять: декодер разбирает структуру.

<?php
declare(strict_types=1);

$broken = 'Subject: =?NO-SUCH?B?QQ==?= tail';
$fallback = iconv_mime_decode($broken,
    ICONV_MIME_DECODE_STRICT | ICONV_MIME_DECODE_CONTINUE_ON_ERROR, 'UTF-8');
echo $fallback === $broken ? "Фрагмент оставлен без декодирования\n" : "Иной результат\n";

Фрагмент оставлен без декодирования

Это пример аварийного просмотра, не правило приёма бизнес-данных. Нельзя считать строковый результат доказательством, что заголовок полностью корректен; continue допускает частичный разбор. В интерфейсе результат всё равно экранируют для HTML.

<?php
declare(strict_types=1);

$raw = "Subject: =?UTF-8?B?0KfQsNC5?=\r\nX-Order: 42\r\n\r\nBody: ignored";
$headers = iconv_mime_decode_headers($raw, ICONV_MIME_DECODE_STRICT, 'UTF-8');
if ($headers === false) { throw new RuntimeException('Заголовки не прочитаны'); }
echo $headers['Subject'], '/', $headers['X-Order'], "\n";
var_dump(array_key_exists('Body', $headers));

Чай/42
bool(false)

Возвращается ассоциативный массив, не объект сообщения. Ключи из примера фиксированы, но реальные заголовки могут отсутствовать/повторяться: следующий опыт показывает, почему прямого $headers["Subject"] недостаточно.

<?php
declare(strict_types=1);

$raw = "X-Tag: tea\r\nX-Tag: mint\r\nx-tag: sale\r\nSubject: One\r\nsubject: Two\r\n";
$decoded = iconv_mime_decode_headers($raw, ICONV_MIME_DECODE_STRICT, 'UTF-8');
if ($decoded === false) { throw new RuntimeException('Неверный блок'); }
$fields = [];
foreach ($decoded as $name => $values) {
    $key = strtolower($name); // В этом формате имена полей ASCII.
    foreach ((array) $values as $value) { $fields[$key][] = $value; }
}
echo implode(', ', $fields['x-tag']), "\n";
echo count($fields['subject'] ?? []) === 1 ? "Одна тема\n" : "Неоднозначная тема\n";

tea, mint, sale
Неоднозначная тема

Одинаково написанное имя повторяется массивом; имя с другим регистром может стать отдельным ключом. (array) превращает одну строку в одноэлементный массив, чтобы общий цикл сохранил все значения. HTTP/email-имена обычно сравнивают без регистра, поэтому array_change_key_case без накопления мог бы затереть одно значение.

<?php
declare(strict_types=1);

echo iconv_get_encoding('internal_encoding'), "\n";
var_dump(iconv_get_encoding('not_a_setting'));
echo implode(', ', array_keys(iconv_get_encoding('all'))), "\n";

UTF-8
bool(false)
input_encoding, output_encoding, internal_encoding

UTF-8 — результат настройки этой лаборатории, не обещание любого сервера. Неизвестный ключ возвращает false. Массив содержит входную, выходную и внутреннюю настройку, но не список поддерживаемых кодировок.

<?php
declare(strict_types=1);

$old = ini_get('internal_encoding');
try {
    ini_set('internal_encoding', 'ISO-8859-1');
    echo ini_get('iconv.internal_encoding') === '' ? "Iconv override пуст\n" : "Iconv override задан\n";
    echo iconv_get_encoding('internal_encoding'), "\n";
    echo iconv_strlen("\xE9"), "\n";
} finally { ini_set('internal_encoding', $old); }

Iconv override пуст
ISO-8859-1
1

В опыте iconv.internal_encoding изначально пуст, как в проектной ini. Используется общий internal_encoding, затем настройка восстанавливается. Если legacy override непуст, он имеет приоритет: поэтому одной проверки default_charset при диагностике недостаточно.

<?php
declare(strict_types=1);

$old = ini_get('iconv.internal_encoding');
$deprecations = 0;
set_error_handler(static function (int $level, string $message) use (&$deprecations): bool {
    if ($level === E_DEPRECATED && str_contains($message, 'iconv.internal_encoding')) {
        ++$deprecations; return true;
    }
    return false;
});
try {
    $changed = iconv_set_encoding('internal_encoding', 'UTF-8');
    $effective = iconv_get_encoding('internal_encoding');
} finally {
    iconv_set_encoding('internal_encoding', $old);
    restore_error_handler();
}
var_dump($changed);
echo $effective, "\n";
echo $deprecations > 0 ? "Устаревшая директива диагностирована\n" : "Нет диагностики\n";

bool(true)
UTF-8
Устаревшая директива диагностирована

Перехватывается только известное предупреждение этой директивы; исходная настройка восстанавливается в finally. Это лабораторный приём, не совет отключить E_DEPRECATED в рабочем проекте.

<?php
declare(strict_types=1);

$old = ini_get('iconv.internal_encoding');
set_error_handler(static function (int $level, string $message): bool {
    return $level === E_DEPRECATED && str_contains($message, 'iconv.internal_encoding');
});
try {
    var_dump(iconv_set_encoding('unknown_key', 'UTF-8'));
    var_dump(iconv_set_encoding('internal_encoding', 'NO-SUCH-CHARSET'));
    echo iconv_get_encoding('internal_encoding'), "\n";
} finally {
    iconv_set_encoding('internal_encoding', $old);
    restore_error_handler();
}

bool(false)
bool(true)
NO-SUCH-CHARSET

Setter сохраняет имя, но не создаёт конвертер и не проверяет возможность работы с ним. Следующий настоящий вызов может отказать. Поэтому ввод charset не принимают произвольно от посетителя и не проверяют одним setter.

<?php
declare(strict_types=1);

$oldInternal = ini_get('internal_encoding');
$oldOutput = ini_get('output_encoding');
ini_set('internal_encoding', 'UTF-8');
ini_set('output_encoding', 'Windows-1251');
ob_start();
ob_start('ob_iconv_handler');
echo 'Привет';
$active = in_array('ob_iconv_handler', ob_list_handlers(), true);
ob_end_flush();
$converted = ob_get_clean();
ini_set('internal_encoding', $oldInternal);
ini_set('output_encoding', $oldOutput);
var_dump($active, function_exists('ob_iconv_handler'));
echo bin2hex($converted), "\n";

bool(true)
bool(false)
cff0e8e2e5f2

Пример начинается до любого вывода, iconv.* overrides в проектной ini пусты. Меняются только настройки этого изолированного процесса, затем восстанавливаются. Внешний буфер позволяет исследовать преобразование в CLI; работа HTTP-заголовков этим не проверяется.

<?php
declare(strict_types=1);

$oldInternal = ini_get('internal_encoding');
$oldOutput = ini_get('output_encoding');
ini_set('internal_encoding', 'UTF-8');
ini_set('output_encoding', 'Windows-1251');
ob_start('ob_iconv_handler');
echo 'Чай';
$raw = ob_get_clean();
ini_set('internal_encoding', $oldInternal);
ini_set('output_encoding', $oldOutput);
echo bin2hex($raw), "\n";
echo $raw === 'Чай' ? "Получено исходное содержимое буфера\n" : "Другой результат\n";

d0a7d0b0d0b9
Получено исходное содержимое буфера

ob_get_clean возвращает исходное содержимое своего буфера, а обработанный вывод при clean не становится его возвращаемым значением. Поэтому попытка использовать его как iconv-обёртку часто ничего не преобразует. Для одной строки проще явный iconv.

<?php
declare(strict_types=1);

ini_set('internal_encoding', 'UTF-8');
ini_set('output_encoding', 'Windows-1251');
header('Content-Type: text/html; charset=Windows-1251');

ob_start('ob_iconv_handler');
echo "<h1>Заказ №42</h1>\n";
echo "<p>Чай с мятой — 2 упаковки.</p>\n";
ob_end_flush();

HTTP 200
Content-Type: text/html; charset=Windows-1251

На странице:
Заказ №42
Чай с мятой — 2 упаковки.

header задаёт описание ответа до его отправки. ob_start включает буферизацию, echo наполняет буфер, ob_end_flush передаёт результат наружу через обработчик. Настройки действуют в данном запросе. Сам заголовок не конвертирует текст: если убрать обработчик, браузер прочитает UTF-8-байты как Windows-1251 и покажет неверные буквы. Для нового сайта согласуйте UTF-8 во всех частях и не добавляйте такую конвертацию без требования внешнего потребителя.