CompatNav

“Function utf8_encode() is deprecated” in WordPress: what to use instead

By CompatNav · Published · Last reviewed · 3 min read

Short answer

It’s a deprecation notice from PHP 8.2 and later: a plugin or theme converts text with utf8_encode() or utf8_decode(), which PHP has marked for removal. The code keeps working. The replacement is mb_convert_encoding(), which also fixes a quiet problem of the old functions: they only know one old character set, so curly quotes and the € sign from Windows files came out wrong. Update the plugin, or send the message to its developer.

The message, exactly

An importer plugin reads an old CSV export, stored in the ISO-8859-1 character set, and converts it to UTF-8 for WordPress. On PHP 8.1 it runs without a message; from PHP 8.2 on, PHP adds the notice:

wp-content/plugins/old-importer/import.php

<?php
$latin1 = "Caf\xE9";               // "Café" in ISO-8859-1, as an old CSV export stores it
echo utf8_encode($latin1), "\n";

Output on PHP 8.1.34

Café

Output on PHP 8.2.34

Deprecated: Function utf8_encode() is deprecated in /var/www/html/wp-content/plugins/old-importer/import.php on line 3
Café

Its counterpart gets the same treatment. php.net: “utf8_encode() and utf8_decode() have been deprecated.” (php.net)

wp-content/plugins/old-importer/export.php

<?php
$text = 'Café';                    // UTF-8, as WordPress stores it
echo bin2hex(utf8_decode($text)), "\n";

Output on PHP 8.1.34

436166e9

Output on PHP 8.2.34

Deprecated: Function utf8_decode() is deprecated in /var/www/html/wp-content/plugins/old-importer/export.php on line 3
436166e9

What the functions do, and what they don’t

php.net: “This function converts the string string from the ISO-8859-1 encoding to UTF-8.” And: “This function does not attempt to guess the current encoding of the provided string, it assumes it is encoded as ISO-8859-1” (php.net).

That assumption is where the old function went quietly wrong. Files saved by Windows programs, such as a CSV from Excel, usually use the Windows-1252 character set. It matches ISO-8859-1 for ordinary letters, but not for curly quotes and the € sign:

wp-content/plugins/old-importer/import.php

<?php
$from_excel = "\x93Quoted\x94 \x80 5";   // curly quotes and the euro sign, as Windows saves them

echo bin2hex(@utf8_encode($from_excel)), "  utf8_encode()\n";
echo mb_convert_encoding($from_excel, 'UTF-8', 'Windows-1252'), "  Windows-1252\n";

Output on PHP 8.2.34

c29351756f746564c29420c2802035  utf8_encode()
“Quoted” € 5  Windows-1252

The first line shows the bytes utf8_encode() produced: c293 and c294 instead of curly quotes, c280 instead of €. Those are invisible control characters, not the symbols. Converting from Windows-1252 by name gives the right text.

Is it urgent?

No. The result on PHP 8.2 is the same as on 8.1; PHP only adds the notice. It still needs a fix, because a future PHP version is expected to remove what is deprecated today, and the notices can fill your log.

Who fixes it

  1. Find the plugin or theme: the folder after wp-content/plugins/ or wp-content/themes/ in the message.
  2. Update it (Dashboard → Updates).
  3. Already on the latest version? Send the full message to its developer, with a note if your imported files come from Excel or other Windows programs: the right replacement depends on it.
  4. Keep notices off your pages meanwhile: the WordPress debug log shows how to log them instead.

A check that reads code finds every call, while your site still runs PHP 8.1:

CompatNav names the replacement in its message. Choosing the right source character set (ISO-8859-1 or Windows-1252) stays with the developer, who knows where the text comes from. Other PHP 8.2 changes are in WordPress and PHP 8.2.

Key takeaways

  • It’s a deprecation notice from PHP 8.2 and later; the code keeps working.
  • utf8_encode() converts from ISO-8859-1 to UTF-8; utf8_decode() the other way. Both are deprecated.
  • The replacement is mb_convert_encoding() with both character sets named, for example mb_convert_encoding( $text, 'UTF-8', 'ISO-8859-1' ).
  • The old function assumed ISO-8859-1. Text from Windows programs such as Excel is usually Windows-1252, where curly quotes and € differ: utf8_encode() turned them into invisible control characters.
  • A check that reads code finds every call before you upgrade.

Frequently asked questions

Is it urgent?

No. The result is the same as before; PHP only adds the notice. A future PHP version is expected to remove the functions, so the plugin should be updated.

What is the replacement for utf8_decode()?

The same function the other way round: mb_convert_encoding( $text, 'ISO-8859-1', 'UTF-8' ). The examples on this page show both directions.

Does mb_convert_encoding() work on every host?

It needs PHP’s mbstring extension. If a plugin reports that the function doesn’t exist, ask your host to enable mbstring.

Why did my imported text have strange characters before?

If the file came from a Windows program, it was probably Windows-1252, not ISO-8859-1. utf8_encode() assumed ISO-8859-1 and converted some characters wrongly. Naming the right character set in mb_convert_encoding() fixes it.

Check your own site before you upgrade

CompatNav is a free WordPress plugin. It reads the code of your plugins and themes on your own server and tells you, in plain words, what will break and what will only show notices on the PHP version you choose. It never changes your code. It can’t see problems that only appear while code runs with real data, so a quick check of your site after the upgrade still matters.

Get CompatNav on wordpress.org How it works

Sources

About the code examples: each output is the real output of the code shown, run with the official PHP builds, without a php.ini, with all errors reported and displayed. Only the file path was replaced by a neutral server path.