mb_list_encodings
Returns an array of every character encoding name supported by the mbstring extension.
mb_list_encodings(): array- Added in PHP 5.0
Return value
arrayA numerically indexed array of the canonical names of all supported encodings.
Changelog
- PHP 7.4.0The pseudo-encoding "auto" is no longer included in the returned list.
mb_list_encodings() takes no arguments and hands back the canonical names of every encoding this build of mbstring understands — roughly eighty of them, covering the UTF family, the ISO-8859 series, the Windows code pages, the Japanese, Chinese and Korean legacy encodings, and a few oddities.
Its real job is validation. When an encoding name comes from a config file, a request parameter or a CSV header, checking it against this list lets you fail with a clear message instead of catching the ValueError that mb_convert_encoding() throws on PHP 8. It is also handy in a diagnostics endpoint that reports what the runtime actually supports, which can differ between builds.
Two traps are worth knowing. The list contains canonical names only, so common aliases people actually type — utf8, latin1, cp1252 — are absent even though the functions accept them happily. Expand each entry with mb_encoding_aliases() if you want a complete acceptance set. And encoding names are matched case-insensitively when you pass them to mbstring functions, but the array holds one fixed spelling, so a strict in_array() on lowercase input will fail.
Do not pass this whole array to mb_detect_encoding(). Detection gets less accurate with every extra candidate, not more.
Example
When to use it
- Validate an encoding name that came from a config file before using it.
- Show the supported charsets in an import screen's dropdown.
- Report available encodings from a health-check or diagnostics endpoint.
- Confirm a build of PHP includes the Japanese encodings a legacy job depends on.
Frequently asked questions
How do I check whether PHP supports a given encoding?
Compare a lowercased version of the name against mb_list_encodings() expanded with mb_encoding_aliases(). A plain strict in_array() will reject valid aliases such as 'utf8' or 'latin1'.
Why is 'utf8' missing from mb_list_encodings?
The array contains canonical names only, and the canonical name is 'UTF-8'. 'utf8' is a registered alias, so mbstring functions accept it even though it never appears in the list.
Can I pass mb_list_encodings() to mb_detect_encoding?
You can, but you should not — detection accuracy drops sharply as candidates are added, and dozens of encodings will match almost any byte sequence. Pass two or three encodings you genuinely expect.
More examples
Validate a user-supplied encoding name
Folding both the canonical names and every alias to lowercase builds a lookup set that accepts what users actually type. "utf8" and "latin1" pass as aliases of UTF-8 and ISO-8859-1; the nonsense name fails, letting you return a helpful error instead of catching a ValueError later.
<?php
function isSupported(string $enc): bool {
static $known = null;
if ($known === null) {
$known = [];
foreach (mb_list_encodings() as $name) {
$known[strtolower($name)] = true;
foreach (mb_encoding_aliases($name) as $alias) {
$known[strtolower($alias)] = true;
}
}
}
return isset($known[strtolower($enc)]);
}
var_dump(isSupported('utf8'), isSupported('latin1'), isSupported('klingon'));Filter the list by family
The ISO-8859 series covers Western European, Cyrillic, Greek, Hebrew and more, and mbstring ships most of them. Filtering like this is the practical way to populate a dropdown for a specific region rather than dumping all eighty-odd names on a user.
<?php
$iso = array_values(array_filter(
mb_list_encodings(),
static fn(string $e): bool => str_starts_with($e, 'ISO-8859')
));
echo count($iso), " ISO-8859 variants\n";
print_r(array_slice($iso, 0, 4));Confirm an encoding actually round-trips
Being present in mb_list_encodings() only means mbstring can read and write the encoding, not that your text survives it. Latin-1 and UTF-16 return the German text intact; the Cyrillic ISO-8859-5 has no ü or ß, so those become substitution characters and the round trip is reported as lossy.
<?php
$sample = 'Grüße';
$targets = ['ISO-8859-1', 'ISO-8859-5', 'UTF-16'];
foreach ($targets as $t) {
$back = mb_convert_encoding(
mb_convert_encoding($sample, $t, 'UTF-8'), 'UTF-8', $t
);
printf("%-12s %s %s\n", $t, $back, $back === $sample ? 'ok' : 'lossy');
}
Discussion