You are here: Installation > Update eShop to UTF-8 encoding

Update eShop to UTF-8 encoding

Requirements

These instructions are for updating a Version equal or newer to 4.1.1 to UTF-8.
Older eShop versions cannot be updated to UTF-8.

Update Files

Enterprise Edition

5.3.0 – 5.3.x: Download OXID_UTF8UPDATE_EE_5.3.0.zip
5.2.0 – 5.2.x: Download OXID_UTF8UPDATE_EE_5.2.0.zip
5.1.0 – 5.1.x: Download OXID_UTF8UPDATE_EE_5.1.0.zip
5.0.0 – 5.0.x: Download OXID_UTF8UPDATE_EE_5.0.0.zip
4.6.0 – 4.6.x: Download OXID_UTF8UPDATE_FOR_4.6.0.zip
4.5.1 – 4.5.x: Download OXID_UTF8UPDATE_EE_4.5.1-4.5.x.zip
4.5.0: Download OXID_UTF8UPDATE_EE_4.5.0.zip
4.4.0 – 4.4.x: Download OXID_UTF8UPDATE_EE_4.4.0.zip
4.3.0 – 4.3.2: Download OXID_UTF8UPDATE_EE_4.3.0.zip
4.1.6 – 4.2.0: Download OXID_UTF8UPDATE_EE_4.1.6-4.2.0.zip
4.1.1 – 4.1.5: Download OXID_UTF8UPDATE_EE_4.1.1-4.1.5.zip

Professional Edition

4.10.0 – 4.10.x: Download OXID_UTF8UPDATE_PE_4.10.0.zip
4.9.0 – 4.9.x: Download OXID_UTF8UPDATE_PE_4.9.0.zip
4.8.0 – 4.8.x: Download OXID_UTF8UPDATE_PE_4.8.0.zip
4.7.0 – 4.7.x: Download OXID_UTF8UPDATE_PE_4.7.0.zip
4.6.0 – 4.6.x: Download OXID_UTF8UPDATE_FOR_4.6.0.zip
4.5.1 – 4.5.x: Download OXID_UTF8UPDATE_PE_4.5.1-4.5.x.zip
4.5.0: Download OXID_UTF8UPDATE_PE_4.5.0.zip
4.4.0 – 4.4.x: Download OXID_UTF8UPDATE_PE_4.4.0.zip
4.3.0 – 4.3.2: Download OXID_UTF8UPDATE_PE_4.3.0.zip
4.1.6 – 4.2.0: Download OXID_UTF8UPDATE_PE_4.1.6-4.2.0.zip
4.1.1 – 4.1.5: Download OXID_UTF8UPDATE_PE_4.1.1-4.1.5.zip

Community Edition

4.10.0 – 4.10.x: Download OXID_UTF8UPDATE_CE_4.10.0.zip
4.9.0 – 4.9.x: Download OXID_UTF8UPDATE_CE_4.9.0.zip
4.8.0 – 4.8.x: Download OXID_UTF8UPDATE_CE_4.8.0.zip
4.7.0 – 4.7.x: Download OXID_UTF8UPDATE_CE_4.7.0.zip
4.6.0 – 4.6.x: Download OXID_UTF8UPDATE_FOR_4.6.0.zip
4.5.1 – 4.5.x: Download OXID_UTF8UPDATE_CE_4.5.1-4.5.x.zip
4.5.0: Download OXID_UTF8UPDATE_CE_4.5.0.zip
4.4.0 – 4.4.x: Download OXID_UTF8UPDATE_CE_4.4.0.zip
4.3.0 – 4.3.2: Download OXID_UTF8UPDATE_CE_4.3.0.zip
4.1.6 – 4.2.0: Download OXID_UTF8UPDATE_CE_4.1.6-4.2.0.zip
4.1.1 – 4.1.5: Download OXID_UTF8UPDATE_CE_4.1.1-4.1.5.zip

1. Check if System Requirements for UTF-8 are met

  • Log in to eShop Admin
  • Select Service -> System Requirements
  • Check if mbstring and UTF-8 support are green:

The UTF-8 update will only work if the requirements mentioned above are met (green square). Otherwise, installing this update might break your eShop!

2. Make eShop temporarily offline

The eShop has to be offline for this update. The best way to do so is to replace the index.php file in the main directory of your eShop.

  • Backup your existing index.php file located in the main directory of your eShop.
  • Create a new index.php file with the following content: <?php echo “The eShop is temporarily offline for maintenance. Please try again later”;?>
  • Overwrite the index.php with the new one.

Try opening your eShop in your browser. The maintenance message should appear.

3. Backup Database

  • Make a complete backup of your database.

4. Change Database to UTF-8

Next, the database is updated to use UTF-8 encoding. All database commands are in the .sql file in the update package.

Before running the database commands, you have to edit the file:
replace _NAME_OF_DB_ with the name of the database.

There are several ways to execute the file:

  • Many web hosts offer phpmyadmin for managing databases. In phpmyadmin, you can use the Import function.
  • If you have command line access to the database, you can run the update via command line.

The database commands cover the standard database of OXID eShop. If you made any changes to the database, you have to convert these changes to UTF-8 manually.

5. Check language files

While working in UTF-8 mode non UTF-8 data stored in language files must be prepared. For doing this, the charset of each language file has to be defined. Check all language files in the following folders (LANG_ABBR stands for language abbreviation, e.g. en, de, fr):

Admin language files: /out/admin/LANG_ABBR/
Frontend language files: /out/azure/LANG_ABBR/

  • Check each file if the charset is defined in its code, e.g.: ‘charset’ => ‘ISO-8859-15’,
  • If the charset is not defined, the language files are ignored. To get them properly working, find out the character encoding with a text editor and add the charset information to the language file after the line $aLang = array(:
    $aLang = array(
    ‘charset’ => ‘CHARSET_NAME’,

The following charsets are supported by PHP: ISO-8859-1, ISO-8859-15, UTF-8, cp866, cp1251, cp1252, KOI8-R, BIG5, GB2312, BIG5-HKSCS, Shift_JIS, EUC-JP

6. Check custom files

If you made any extensions to OXID eShop, these files should be encoded as ISO-8859-15. Otherwise, special chars can lead to problems.
Only language files are allowed to have other encoding than ISO-8859-15.

  • Check all your custom files except language files if they are saved in ISO-8859-15.

7. Run update.php

  • Copy update.php from the UTF-8 update package to the main directory of your eShop.
  • Open the update script with your browser (http://www.youreshop.com/update.php).
  • In the first update step, the character set currently used is detected automatically. Click on Proceed to run the update.
  • After the update, the results are shown. Here you can see all updated data. Please review the data if any chars are not as they should be (especially currency setting, see public bugtracker). If necessary, change the data in admin after update is finished.

8. Update config.inc.php

  • Check if the entry $this->iUtfMode exists in the config.inc.php (located in the main directory of your eShop).
  • If yes: Adjust the config.inc.php file: set
    $this->iUtfMode to 1.
  • If no: Add the following line to the config.inc.php file:
    $this->iUtfMode = ‘1’; // 1 – enables UTF-8, 0 – disables UTF-8

9. Delete temporary files

  • Delete all files in /tmp.

10. Restore index.php

Copy the backup of index.php made in step 2 back to the main directory of your eShop.

Update is finished

The update to UTF-8 character encoding is finished.