PHP convert_cyr_string() Function

What You’ll Learn

The convert_cyr_string() function converts strings between legacy Cyrillic encodings such as KOI8-R and Windows-1251. It is a historical PHP function—removed in PHP 8—but understanding it helps when reading older code or migrating legacy Russian/Ukrainian text data.

Definition and Usage

In PHP, convert_cyr_string() maps bytes from one Cyrillic character set to another. Unlike UTF-8 conversion, it works with older single-byte encodings common in 1990s–2000s Russian-language software. You pass the raw byte string and two one-letter charset identifiers.

📝 Syntax

The convert_cyr_string() function accepts three parameters:

string convert_cyr_string(string $str, string $from, string $to)

Parameters

• $str — the input string, already encoded in the $from charset (raw bytes, not UTF-8 unless converting from a UTF-8-compatible path via other tools).
• $from — single-letter code for the source Cyrillic encoding.
• $to — single-letter code for the target Cyrillic encoding.

Charset Letter Codes

Return Value

Returns the converted string on success. The original string is not modified.

Examples Gallery

These examples teach how convert_cyr_string() worked in PHP 7 and below. On PHP 8+, use the iconv() / mb_convert_encoding() alternatives shown in Examples 4 and 5.

<?php
// Cyrillic "ABV" (АБВ) in Windows-1251: bytes C0 C1 C2
$win1251 = "\xC0\xC1\xC2";

$koi8r = convert_cyr_string($win1251, "w", "k");

echo "Win-1251 hex: " . bin2hex($win1251) . "\n";
echo "KOI8-R hex:   " . bin2hex($koi8r) . "\n";
?>

Win-1251 hex: c0c1c2
KOI8-R hex:   e1e2e3

<?php
$original = "\xE1\xE2\xE3";  // KOI8-R bytes for АБВ

$temp = convert_cyr_string($original, "k", "w");
$back = convert_cyr_string($temp, "w", "k");

echo "Original: " . bin2hex($original) . "\n";
echo "Back:     " . bin2hex($back) . "\n";
echo "Match:    " . ($back === $original ? "yes\n" : "no\n");
?>

Original: e1e2e3
Back:     e1e2e3
Match:    yes

<?php
// This string is UTF-8, NOT KOI8-R — a frequent beginner error
$utf8Text = "Привет, мир!";

$wrong = convert_cyr_string($utf8Text, "k", "i");

echo "UTF-8 bytes:  " . bin2hex($utf8Text) . "\n";
echo "Wrong output: " . bin2hex($wrong) . "\n";
echo "Lesson: \$from must match the actual byte encoding of \$str\n";
?>

UTF-8 bytes:  d09fd180d0b8d0b2d0b5d1822c20d0bcd0b8d18021
Wrong output: <garbled bytes — not valid ISO-8859-5 text>
Lesson: $from must match the actual byte encoding of $str

<?php
$koi8r = "\xE1\xE2\xE3";  // KOI8-R bytes for АБВ

$utf8 = iconv("KOI8-R", "UTF-8//IGNORE", $koi8r);

echo "KOI8-R hex: " . bin2hex($koi8r) . "\n";
echo "UTF-8 text: $utf8\n";
echo "UTF-8 hex:  " . bin2hex($utf8) . "\n";
?>

KOI8-R hex: e1e2e3
UTF-8 text: АБВ
UTF-8 hex:  d090d091d092

<?php
$win1251 = "\xC0\xC1\xC2";  // Windows-1251 АБВ

$utf8 = mb_convert_encoding($win1251, "UTF-8", "Windows-1251");

echo "Win-1251 hex: " . bin2hex($win1251) . "\n";
echo "UTF-8 text:   $utf8\n";

// Convert back to Windows-1251
$back = mb_convert_encoding($utf8, "Windows-1251", "UTF-8");
echo "Round-trip:   " . ($back === $win1251 ? "yes\n" : "no\n");
?>

Win-1251 hex: c0c1c2
UTF-8 text:   АБВ
Round-trip:   yes

🚀 Common Use Cases

• Reading legacy databases — data stored in KOI8-R or Windows-1251 before UTF-8 adoption.
• Migrating old PHP code — understand what convert_cyr_string() did before replacing it with iconv().
• Flat-file imports — converting Cyrillic text files from Soviet-era encodings.
• Email and news (FidoNet) — historical systems that standardized on KOI8-R.
• Learning encoding concepts — see why UTF-8 replaced dozens of regional charsets.

📝 Notes

• Removed in PHP 8.0 — do not use in new projects; use iconv() or mb_convert_encoding().
• Only converts between the listed legacy Cyrillic encodings—not UTF-8, Latin-1, or general Unicode.
• The input string must already be in the $from encoding.
• Charset parameters are single characters ("k", not "KOI8-R").
• Modern web apps should store and transmit text as UTF-8 end to end.

💡 Best Practices