OpenCart 3 to OpenCart 4 Migration

OpenCart 3 to OpenCart 4 Site Migration

OpenCart 4 is a major update: PHP 8.0+, Twig templates (instead of PHP), redesigned extension system, new Storage API, updated database tables. Direct upgrade is impossible — data migration and complete rewrite of custom code required.

What Changed in OC4

Templates: PHP → Twig. All .tpl.php files need rewriting to .twig.

Extensions: OCMOD replaced by Events System for core modifications without file patching.

Storage: DIR_UPLOAD moved, storage structure changed.

Admin Panel: completely redesigned.

Preparation

# List OC3 extensions
# Admin → Extensions → Installed extensions

# Check PHP compatibility
php -v  # OC4 requires PHP 8.0+

# Export data from OC3
mysqldump -u root opencart3_db > oc3_backup.sql

Data Export for Transfer

-- Products
SELECT
    p.product_id, pd.name, pd.description, pd.meta_title, pd.meta_description,
    p.model, p.sku, p.price, p.quantity, p.status, p.sort_order,
    GROUP_CONCAT(DISTINCT pic.category_id) as categories,
    GROUP_CONCAT(DISTINCT pi.image) as images
FROM oc_product p
JOIN oc_product_description pd ON pd.product_id = p.product_id AND pd.language_id = 1
LEFT JOIN oc_product_to_category pic ON pic.product_id = p.product_id
LEFT JOIN oc_product_image pi ON pi.product_id = p.product_id
GROUP BY p.product_id;

-- Orders (history)
SELECT o.*, os.name as status_name
FROM oc_order o
JOIN oc_order_status os ON os.order_status_id = o.order_status_id AND os.language_id = 1
WHERE o.order_status_id > 0;

-- Customers
SELECT c.*, ca.*
FROM oc_customer c
JOIN oc_address ca ON ca.customer_id = c.customer_id AND ca.default = 1;

OC4 Installation and Basic Setup

# Install OpenCart 4
composer create-project opencart/opencart shop.com 4.x-dev
# or download zip from GitHub releases

# Configure Nginx
# OC4 uses public/ as web-root

Data Transfer via OC4 Import

OC4 has advanced import capabilities via Admin → Catalog → Products → Import.

CSV format for import:

product_id,name(en-gb),description(en-gb),model,sku,price,quantity,status,category_id(0),category_id(1)
1,"Product Name","Description","MODEL-001","SKU-001",1500.00,10,1,5,7

Image Transfer

# image/ folder structure is identical in OC3 and OC4
rsync -avz /var/www/oc3-shop/image/ /var/www/oc4-shop/image/

OC3 Template → OC4 Twig Migration

// OC3 template (catalog/view/theme/default/template/product/product.tpl.php)
<?php foreach ($products as $product) { ?>
<div class="product-thumb">
    <a href="<?php echo $product['href']; ?>"><?php echo $product['name']; ?></a>
    <span><?php echo $product['price']; ?></span>
</div>
<?php } ?>

{# OC4 template (catalog/view/template/product/product.twig) #}
{% for product in products %}
<div class="product-thumb">
    <a href="{{ product.href }}">{{ product.name }}</a>
    <span>{{ product.price }}</span>
</div>
{% endfor %}

OCMOD → Events (OC4)

// OC3 OCMOD modification (XML file patching)
// <modification>
//   <file path="catalog/view/theme/*/template/product/product.twig">
//     <operation>...

// OC4 Event (no patching)
class ExtensionMyExtensionEventProductList {
    public function index(&$route, &$data): void {
        // Modify data before passing to template
        foreach ($data['products'] as &$product) {
            $product['custom_badge'] = 'Sale';
        }
    }
}

Timeline