Why You Need to Replace Your utf8_encode and utf8_decode PHP Functions to Prepare to Upgrade to PHP 8.2 and Newer PHP Versions

In this article you will learn:

1. What is the Purpose of the PHP Functions utf8_encode and utf8_decode

2. Why You Need to Update Your Current Projects If You Used the utf8_encode and utf8_decode to Upgrade to PHP 8.2 or a Newer PHP Version

3. How Can You Change Your Code to Avoid Using the PHP Functions utf8_encode and utf8_decode

3.1 Create a Wrapper Function

3.2 Search For the Old Function Calls in Your Code and Replace by Wrapper Function Calls

3.3 Change The Implementation of the Wrapper Functions to Use Functions of Modern PHP Extensions

1. What is the Purpose of the PHP Functions utf8_encode and utf8_decode

utf8_encode and utf8_decode are functions that have existed in PHP for a long time. They convert text encoding between UTF-8 and ISO 8859-1 (also known as Latin 1).

ISO Latin 1 encoding is used in the text that is in most European languages. Using UTF-8 encoding is better because it supports encoding text in most of the languages used around the world. UTF-8 also uses 8-bit characters.

So if you developed a database application in PHP that uses database tables with fields of types like CHAR, VARCHAR, and TEXT, you should use UTF-8 when you create your database tables.

Suppose your PHP applications started being developed a long time ago. In that case, you may still have to convert text from HTTP request parameters in ISO Latin 1 to support old browsers that only supported that type of text encoding.

utf8_encode and utf8_decode are functions used to perform that text encoding conversion.

2. Why You Need to Update Your Current Projects If You Used the utf8_encode and utf8_decode to Upgrade to PHP 8.2 or a Newer PHP Version

In PHP 8.2 the utf8_encode and utf8_decode functions became deprecated. Starting with version 8.2, PHP will issue deprecation notices every time a PHP application calls these functions. These notices can be seen in the PHP error log if you have the error_log option enabled.

The PHP core developers approved an RFC (Request For Change) proposal to deprecate the utf8_encode and utf8_decode functions in PHP 8.2 and remove the functions from PHP in version 9.0.

If you use PHP in a hosting environment where the hosting provider controls the PHP version that is used, or if, for some other reason, you need to upgrade to a newer PHP version, it is better if you become prepared to use a version that no longer has the utf8_encode and utf8_decode functions.  

3. How Can You Change Your Code to Avoid Using the PHP Functions utf8_encode and utf8_decode

If you are starting a new project, avoid using the utf8_encode and utf8_decode functions. Instead, you can use the mb_convert_encoding function of the mb extension, or transcode function of the intl extension, or the iconv function.

Any of these functions is OK. Check first if any PHP extensions (mb, intl, iconv) are available in your PHP environment to decide which function you can use.

If you have a PHP function that still uses the utf8_encode and utf8_decode functions, what you can do to make a smooth transition in just 3 steps:

3.1 Create a Wrapper Function

The wrapper function can be like this:

function my_utf8_encode($text) {

  return utf8_encode($text);

}

function my_utf8_decode($text) {

  return utf8_decode($text);

}

3.2 Search For the Old Function Calls in Your Code and Replace by Wrapper Function Calls

Then search for all calls in your PHP application to utf8_encode and replace them with calls to my_utf8_encode. Also, search for all calls in your PHP application to utf8_decode and replace them with calls to my_utf8_decode.

3.3 Change The Implementation of the Wrapper Functions to Use Functions of Modern PHP Extensions

Then change the implementation of the my_utf8_encode and my_utf8_decode functions to use functions of one of the extensions mentioned above that can do the text encoding conversion.

For instance, if you have the mb extension available in your PHP environment, change the functions like this:

function my_utf8_encode($text) {

  return mb_convert_encoding($text, 'UTF-8', 'ISO-8859-1');

}

function my_utf8_decode($text) {

  return mb_convert_encoding($text, 'ISO-8859-1', 'UTF-8');

}