convert_cyr_string()
A função convert_cyr_string() era usada para converter strings entre conjuntos de caracteres Cirílicos. Descontinuada no PHP 7.4 e removida no PHP 8.0.
convert_cyr_string() foi descontinuada no PHP 7.4 e removida no PHP 8.0. É uma função legada que não deve ser usada em código moderno. Para converter entre codificações de caracteres, use mb_convert_encoding() ou iconv() — veja a seção de migração abaixo.
Este capítulo explica o que convert_cyr_string() fazia, por que existia, por que foi removida e o que usar em seu lugar. É material de referência para leitura ou manutenção de código PHP antigo — não é uma função que você deve chamar em nada novo.
O que convert_cyr_string() fazia
A função convertia uma string de um conjunto de caracteres Cirílico de byte único para outro. Antes de UTF-8 se tornar o padrão, textos Cirílicos eram armazenados em vários encodings de 8 bits incompatíveis (Windows-1251, KOI8-R, ISO 8859-5, página de código DOS 866 e alguns conjuntos Mac/mainframe). convert_cyr_string() remapeava os bytes de um desses conjuntos legados para outro.
Sintaxe
string convert_cyr_string ( string $str , string $from , string $to )A função recebia três parâmetros e retornava a string convertida:
| Parâmetro | Descrição |
|---|---|
$str | A string a ser convertida. |
$from | Um único caractere que identifica o conjunto de caracteres de origem. |
$to | Um único caractere que identifica o conjunto de caracteres de destino. |
Os argumentos $from e $to eram códigos de uma letra, não nomes completos de encoding:
| Código | Conjunto de caracteres |
|---|---|
k | KOI8-R |
w | Windows-1251 |
i | ISO 8859-5 |
a / d | x-cp866 (DOS) |
m | x-mac-cyrillic |
Exemplo
<?php
// Legacy code only — this throws a fatal error on PHP 8+.
$converted = convert_cyr_string($str, "w", "k"); // Windows-1251 -> KOI8-R
echo $converted;
?>Aqui, $str é assumida como contendo bytes brutos de Windows-1251 ("w"), e a função os reescreve como bytes KOI8-R ("k"). O ponto fundamental a entender é que convert_cyr_string() operava em bytes brutos e assumia que a string de origem já estava no encoding $from. Se você passasse uma string UTF-8 (o padrão moderno), a saída seria lixo sem sentido (mojibake), porque bytes UTF-8 não correspondem a nenhum conjunto Cirílico legado de byte único.
Por que foi removida
- Ela conhecia apenas uma lista fixa de encodings Cirílicos legados de 8 bits — UTF-8 nunca foi suportado, portanto não podia participar do tratamento moderno de texto baseado em Unicode.
- Ela corrompida silenciosamente qualquer entrada que não estivesse realmente no encoding
$fromdeclarado. - Seu trabalho é totalmente coberto pelas funções de uso geral
iconv()emb_convert_encoding(), que suportam centenas de encodings, incluindo UTF-8.
Por essas razões, foi descontinuada no PHP 7.4 e removida no PHP 8.0. Chamá-la hoje gera um Error fatal.
O que usar em seu lugar
Use mb_convert_encoding() (da extensão mbstring) ou iconv(). Ambas aceitam nomes de encoding reais e ambas suportam UTF-8:
<?php
// Convert Windows-1251 bytes to UTF-8.
$utf8 = mb_convert_encoding($legacy, "UTF-8", "Windows-1251");
// The same thing with iconv().
$utf8 = iconv("Windows-1251", "UTF-8", $legacy);
// Convert KOI8-R to UTF-8.
$utf8 = mb_convert_encoding($legacy, "UTF-8", "KOI8-R");
?>Converter para UTF-8 (em vez de entre dois conjuntos legados) é quase sempre o que você deseja: uma vez que o texto está em UTF-8, ele funciona em todo lugar no PHP moderno, em bancos de dados e nos navegadores.
Resumo
convert_cyr_string() era um auxiliar pré-Unicode para trocar bytes entre encodings Cirílicos legados. Ela foi removida a partir do PHP 8.0. Se você a encontrar em código antigo, substitua cada chamada por iconv() ou mb_convert_encoding() e migre seus dados para UTF-8.
Para mais informações sobre como trabalhar com texto em PHP, veja PHP Strings e htmlentities().