Stdlib: iconv() / mb_convert_encoding() — charset conversion (ext/iconv + ext/mbstring parity)

[PurHur]

Category

stdlib · php-src-strict

Status (expanded 2026-06-19 — implementation-ready)

Umbrella for charset conversion builtins missing from the VM registry. Overlaps #3075 (mb_convert_encoding / mb_detect_encoding); implement both functions in one PR and close #3075 as duplicate when green.

Problem

Only mb_strlen() exists under ext/types/ / ext/mbstring/. Real PHP apps use iconv() and mb_convert_encoding() for UTF-8 ↔ legacy encodings, HTTP header decoding, and CSV imports. Both are missing from the builtin registry (function_exists → false).

php-src reference

• php/php-src ext/iconv/iconv.c — PHP_FUNCTION(iconv)
• php/php-src ext/mbstring/mbstring.c — PHP_FUNCTION(mb_convert_encoding), mb_detect_encoding
• php/php-src ext/mbstring/php_unicode.h — conversion tables / fallback
• PHPTs: ext/iconv/tests/iconv*.phpt, ext/mbstring/tests/mb_convert_encoding*.phpt

Repro A — mb_convert_encoding missing

test/repro-maintainer/parity_mb_convert_encoding.php:

<?php
$bytes = "\xE9"; // é in ISO-8859-1
var_export(function_exists('mb_convert_encoding'));
echo "\n";
echo mb_convert_encoding($bytes, 'UTF-8', 'ISO-8859-1'), "\n";

Repro B — iconv missing

test/repro-maintainer/parity_iconv.php:

<?php
$bytes = "\xE9";
var_export(function_exists('iconv'));
echo "\n";
echo iconv('ISO-8859-1', 'UTF-8', $bytes), "\n";

Repro C — invalid encoding (error shape)

<?php
var_export(@iconv('UTF-8', 'NO_SUCH', 'x'));
echo "\n";
try {
    mb_convert_encoding('x', 'UTF-8', 'NO_SUCH_ENCODING');
} catch (Throwable $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php test/repro-maintainer/parity_mb_convert_encoding.php
php bin/vm.php test/repro-maintainer/parity_mb_convert_encoding.php
php test/repro-maintainer/parity_iconv.php
php bin/vm.php test/repro-maintainer/parity_iconv.php
'

Check	Zend	VM today
function_exists('mb_convert_encoding')	true	false
ISO-8859-1 é → UTF-8	é	undefined function
function_exists('iconv')	true	false
invalid encoding	false + warning / ValueError	undefined function

Scope (PHP-in-PHP first)

Piece	Path
Module	ext/mbstring/Module.php (preferred) or extend ext/types/
VM	ext/mbstring/VmMbstring.php — v1 may delegate to host \mb_convert_encoding / \iconv when ext available on harness; pure PHP tables for bootstrap subset later
iconv	ext/standard/iconv.php or ext/mbstring/iconv.php
Constants	subset of MB_* encoding names used by repro
JIT	VM-first; capability matrix no until lowered
Tests	test/compliance/cases/stdlib/mb_convert_encoding.phpt, iconv_basic.phpt

Forbidden: permanent charset logic in runtime/*.c.

Done when (php-src-strict)

• Repro A/B output byte-identical to Zend on Docker harness (é round-trip)
• Repro C error/warning class and return value match Zend
• mb_detect_encoding() from Stdlib: mb_convert_encoding / mb_detect_encoding (ext/mbstring parity) #3075 implemented in same module or follow-up linked PR
• script/capability-matrix.php rows added
• ./script/ci-fast.sh --filter MbConvert green

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter mb_convert_encoding'

Related

• Stdlib: mb_convert_encoding / mb_detect_encoding (ext/mbstring parity) #3075 (duplicate target) · Stdlib: mb_str_pad() — multibyte string padding (ext/mbstring/mbstring.c parity) #4006 / Stdlib: mb_lcfirst() / mb_ucfirst() — multibyte case change (ext/mbstring/mbstring.c parity) #4007 · Stdlib: iconv() / mb_convert_encoding() — charset conversion (ext/iconv + ext/mbstring parity) #3222 · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

[PurHur]

claim: PHP Compiler Ext — I/O & Crypto — starting this run

[PurHur]

Merged via #19084.

Fix: mb_convert_encoding() now accepts an array first operand (string elements converted, other types/keys preserved) and enum operands throw TypeError with Zend array|string message shape.

Verification:
```bash
./script/docker-exec.sh -- bash -lc 'php test/repro/maintainer_gap_mb_convert_encoding_array.php'
./script/docker-exec.sh -- bash -lc 'php bin/vm.php test/repro/maintainer_gap_mb_convert_encoding_array.php'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter mb_convert_encoding_array'
```
→ ok / ok / OK (2 tests, 2 assertions)

Note: base iconv() / mb_convert_encoding() registration was already green; this closes the array-batch slice of #3222.