How to Update OpenCart 3 for PHP 8 Compatibility

If your OpenCart version is below 3.0.3.9, your system is not compatible with PHP 8. Unfortunately, OpenCart 3 has no automatic upgrade that would let you move to the current latest version 3.0.4.0. However, the compatibility issue can be solved by adapting the older OpenCart version to PHP 8.x requirements.

Our guide is intended for OpenCart 3.0.2.0, 3.0.3.1, 3.0.3.2, 3.0.3.3, 3.0.3.5, 3.0.3.6, 3.0.3.7, 3.0.3.8. Don't forget to make a full backup of the site before performing these operations. 

There are several methods to update an older OpenCart 3.0 version for PHP 8 support:

1. Clone the OpenCart libraries and individual files from the latest build into your system
2. Update the libraries via composer and make some fixes.
3. Create a new site on OpenCart 3.0.4.0 and migrate the template, database, and all modules to the new system. 

Method 1. Cloning files from the latest OpenCart 3 build

This method is the simplest and fastest — here's what to do:

1. Download the latest OpenCart 3 version — currently 3.0.4.0
2. Unpack the downloaded archive on your PC and open the upload folder
3. Copy the system folder to your site, replacing the corresponding folders and files
4. Copy the system/storage folder to your site into your 'storage' directory (it may be located outside the domain folder, since OpenCart after installation requires moving storage outside the domain folder). If you don't know where your storage is located, open config.php and find DIR_STORAGE.
5. Copy with replacement the file catalog/controller/event/theme.php
6. Fix minor PHP errors (see the list of possible errors and fixes below)

Method 2. Updating libraries via composer in the terminal 

1. Determine the location of the storage folder on your site — open config.php and find DIR_STORAGE, where the path to the folder is specified.
2. Upload the composer.json file to that folder
3. Open a terminal (console) on the server and run the following commands in sequence:
   cd path/to/storage/folder
   composer update
4. If your OpenCart is below 3.0.3.7 — you need to replace some system files:
   catalog/controller/event/theme.php
   system/library/template/twig.php
5. Fix minor PHP errors (see the list of possible errors and fixes below)

Method 3. New site with data migration

This is probably the most complex method, since it requires creating a new site with a sequential transfer of all data. We do not recommend considering this method as it is equivalent to building a new site. In that case, you might as well develop the site on the latest build — currently OpenCart 4.1.0.3 — and get full PHP 8 compatibility plus the use of newer libraries and frameworks.

If you have still decided to migrate to a new OpenCart 3 site with PHP 8 compatibility, here is a brief guide:

1. Download and install the latest OpenCart 3 version — currently 3.0.4.0.
2. Swap in your database — drop the tables and import your database dump.
3. Copy the image folder from your old site to the new one
4. Install the template and all the necessary modules for OpenCart 3

List of possible PHP errors and how to fix them

After moving OpenCart 3.0 to newer PHP versions, especially PHP 8.0, 8.1, 8.2, 8.3, 8.4, errors, warnings, and deprecation notices often appear. This is because OpenCart 3 was created back when PHP 7.0–7.3 was current. Below are the most common errors, their explanations, and recommendations:

Unknown:  mysqli::real_escape_string(): Passing null to parameter #1 ($string) of type string is deprecated in /system/library/db/mysqli.php on line 46

Cause: in PHP 8.1+ you cannot pass null instead of a required string parameter.
Solution: add a check or a type cast for the problematic variable:
return $this->connection->real_escape_string($value);
replace with:
return $this->connection->real_escape_string((string)$value);

Unknown:  round(): Passing null to parameter #1 ($num) of type int|float is deprecated in /catalog/model/catalog/product.php on line 45

Cause: in PHP 8, calling round(null) is no longer allowed — null is not a valid argument type.
Solution: Before calling round(), you need to make sure the argument is not null or do a type cast:
'rating'           => round($query->row['rating']),
replace with:
'rating'           => round((float)$query->row['rating']),

Unknown:  Automatic conversion of false to array is deprecated in /system/library/cart/user.php on line 43

Cause: A value that was false is automatically cast to array, which is now deprecated and potentially unsafe
Solution: You need to add an array check before the problematic line: if (is_array($var)) 

Unknown: Creation of dynamic property Request::$request is deprecated in /system/library/request.php on line 26
Unknown: Creation of dynamic property Session\DB::$db is deprecated in/system/library/session/db.php on line 8
Unknown: Creation of dynamic property Proxy::$getTranslations is deprecated in /system/engine/proxy.php on line 30
Unknown: Creation of dynamic property Cart\Cart::$config is deprecated in /system/library/cart/cart.php on line 7

Cause: in PHP 8.2+ you cannot create object properties "on the fly."
Solution: Declare the property in the class in advance, at the beginning of the PHP class, for example:

private $request;
private $db;
private $proxy;
private $cart;