How to Add a Custom Product Field in OpenCart 4.x

Learn how to add a custom product field in OpenCart 4.x with this detailed, step-by-step guide. Ideal for developers customizing product pages through code or phpMyAdmin with real examples and tips.

If you’re running an online store with OpenCart and want to add extra details to your products, like a special label, warranty info, or a custom description, this guide is for you.

We’ll walk you through adding a new field called custom_field to your products in OpenCart 4.x. This field can store anything you want, like “Eco-Friendly” for green products or “2-Year Warranty” for electronics. We’ll keep things super simple, use easy words, and share real-world examples to make it fun and clear. Let’s get started!

Note: This guide is tested on OpenCart 4.1.0.3 but should work for other 4.x versions. Always back up your database and files before making changes!

Why Add a Custom Field?

Imagine you’re selling gadgets, and you want to show a “Special Feature” for each product, like “Waterproof” for a smartwatch or “Organic” for food items. OpenCart’s default product fields (name, price, description) might not cover this. A custom field lets you add and display unique info in the admin panel and on your store’s front page. Here’s what we’ll do:

• Add a custom_field to the product database table.
• Update OpenCart files to save and show this field in the admin panel.

Real-World Scenarios

Before we dive in, let’s look at some cool ways to use a custom field:

• E-commerce Store: Add a “Product Badge” field to highlight “Best Seller” or “Limited Edition” products.
• Clothing Store: Use custom_field for “Material Type” (e.g., “100% Cotton”).
• Electronics Shop: Show “Warranty Period” (e.g., “1 Year”) on product pages.
• Food Store: Add “Dietary Info” like “Gluten-Free” or “Vegan”.

For this guide, we’ll add a custom_field to store a short text (e.g., “Eco-Friendly”) and display it in the admin panel and on the product page.

Step 1: Add the Custom Field to the Database

First, we need to add the custom_field column to the oc_product table in your database. This is where OpenCart stores product info. We’ll use phpMyAdmin, a tool that comes with XAMPP, to make this change.

How to Do It

1. Open phpMyAdmin (usually at http://localhost/phpmyadmin in XAMPP).
2. Select your OpenCart database (e.g., opencart).
3. Find the oc_product table (replace oc_ with your table prefix if different).
4. Go to the Structure tab, click Add 1 column, and set:
   • Name: custom_field
   • Type: VARCHAR
   • Length: 200
   • Default: '' (empty string)
5. Click Save.

Or, run this SQL query in phpMyAdmin’s SQL tab:

ALTER TABLE `oc_product` ADD `custom_field` VARCHAR(200) DEFAULT '';

Note: If your database uses a different prefix (e.g., oc4_) or no prefix, adjust the table name (e.g., oc4_product or product).

UPDATE `oc_product` SET `custom_field` = 'Eco-Friendly' WHERE `product_id` = 1;

Step 2: Update OpenCart Files

Now, let’s modify OpenCart files to save, edit, and display custom_field. We’ll work in the admin panel first, then the frontend. Use VS Code (or any editor) to open your OpenCart folder (e.g., C:\xampp\htdocs\your_opencart).

File 1: Update the Admin Model

The model handles database queries. We need to update admin/model/catalog/product.php to fetch and save custom_field.

1. Open admin/model/catalog/product.php.
2. In the addProduct function, find the INSERT query. Add custom_field after the date_modified field:

   $this->db->query("INSERT INTO `" . DB_PREFIX . "product` SET `master_id` = '" . (int)$data['master_id'] . "', `model` = '" . $this->db->escape((string)$data['model']) . "', `location` = '" . $this->db->escape((string)$data['location']) . "', `variant` = '" . $this->db->escape(!empty($data['variant']) ? json_encode($data['variant']) : '') . "', `override` = '" . $this->db->escape(!empty($data['override']) ? json_encode($data['override']) : '') . "', `quantity` = '" . (int)$data['quantity'] . "', `minimum` = '" . (int)$data['minimum'] . "', `subtract` = '" . (isset($data['subtract']) ? (bool)$data['subtract'] : 0) . "', `stock_status_id` = '" . (int)$data['stock_status_id'] . "', `date_available` = '" . $this->db->escape((string)$data['date_available']) . "', `manufacturer_id` = '" . (int)$data['manufacturer_id'] . "', `shipping` = '" . (isset($data['shipping']) ? (bool)$data['shipping'] : 0) . "', `price` = '" . (float)$data['price'] . "', `points` = '" . (int)$data['points'] . "', `weight` = '" . (float)$data['weight'] . "', `weight_class_id` = '" . (int)$data['weight_class_id'] . "', `length` = '" . (float)$data['length'] . "', `width` = '" . (float)$data['width'] . "', `height` = '" . (float)$data['height'] . "', `length_class_id` = '" . (int)$data['length_class_id'] . "', `status` = '" . (bool)($data['status'] ?? 0) . "', `tax_class_id` = '" . (int)$data['tax_class_id'] . "', `sort_order` = '" . (int)$data['sort_order'] . "', `date_added` = NOW(), `date_modified` = NOW(), `custom_field` = '" . $this->db->escape((string)$data['custom_field']) . "'");

3. In the editProduct function, find the UPDATE query. Add custom_field after the date_modified field:

   $this->db->query("UPDATE `" . DB_PREFIX . "product` SET `model` = '" . $this->db->escape((string)$data['model']) . "', `location` = '" . $this->db->escape((string)$data['location']) . "', `variant` = '" . $this->db->escape(!empty($data['variant']) ? json_encode($data['variant']) : '') . "', `override` = '" . $this->db->escape(!empty($data['override']) ? json_encode($data['override']) : '') . "', `quantity` = '" . (int)$data['quantity'] . "', `minimum` = '" . (int)$data['minimum'] . "', `subtract` = '" . (isset($data['subtract']) ? (bool)$data['subtract'] : 0) . "', `stock_status_id` = '" . (int)$data['stock_status_id'] . "', `image` = '" . $this->db->escape((string)$data['image']) . "', `date_available` = '" . $this->db->escape((string)$data['date_available']) . "', `manufacturer_id` = '" . (int)$data['manufacturer_id'] . "', `shipping` = '" . (isset($data['shipping']) ? (bool)$data['shipping'] : 0) . "', `price` = '" . (float)$data['price'] . "', `points` = '" . (int)$data['points'] . "', `weight` = '" . (float)$data['weight'] . "', `weight_class_id` = '" . (int)$data['weight_class_id'] . "', `length` = '" . (float)$data['length'] . "', `width` = '" . (float)$data['width'] . "', `height` = '" . (float)$data['height'] . "', `length_class_id` = '" . (int)$data['length_class_id'] . "', `status` = '" . (bool)($data['status'] ?? 0) . "', `tax_class_id` = '" . (int)$data['tax_class_id'] . "', `sort_order` = '" . (int)$data['sort_order'] . "', `date_modified` = NOW(), `custom_field` = '" . $this->db->escape((string)$data['custom_field']) . "' WHERE `product_id` = '" . (int)$product_id . "'");

4. In the getProduct function, after:

   $product_data['override'] = $product_data['override'] ? json_decode($product_data['override'], true) : [];

   Add:

   $product_data['custom_field'] = $product_data['custom_field'] ?? '';

   This ensures custom_field is a string, not an array (avoiding issues like your previous custom_desc problem).

File 2: Update the Admin Controller

The controller passes data to the form. Open admin/controller/catalog/product.php.

1. In the getForm function, after:

   $data['price'] = $product_info['price'] ?? '';

   Add:

   $data['custom_field'] = $product_info['custom_field'] ?? '';

2. In the save function (or add/edit if separate), find the $required array, after:

   'sort_order' => 0,

   Add:

   'custom_field' => $data['custom_field'] ?? '',

File 3: Add Language String

We need a label for the custom field. Open admin/language/en-gb/catalog/product.php.

1. After:

   $_['entry_subscription'] = 'Subscription Plan';

   Add:

   $_['entry_custom_field'] = 'Custom Field';

File 4: Update the Admin Form

Add a text box for custom_field in the admin product form. Open admin/view/template/catalog/product_form.twig.

1. Find the meta_title block:

   <div class="row mb-3 required">
       <label for="input-meta-title-{{ language.language_id }}" class="col-sm-2 col-form-label">{{ entry_meta_title }}</label>

2. Before it, add:

   <div class="row mb-3">
       <label for="input-custom-field" class="col-sm-2 col-form-label">{{ entry_custom_field }}</label>
       <div class="col-sm-10">
           <input type="text" name="custom_field" value="{{ custom_field|default('') }}" placeholder="{{ entry_custom_field }}" id="input-custom-field" class="form-control"/>
       </div>
   </div>

File 5: Update the Frontend Model

To show custom_field on the product page, update catalog/model/catalog/product.php.

1. In the getProduct function, after:

   $product_data['price'] = (float)($query->row['discount'] ?: $query->row['price']);

   Add:

   $product_data['custom_field'] = $query->row['custom_field'] ?? '';

Step 3: Clear OpenCart Caches

OpenCart uses caches to speed up your store, but they can hide your changes. Clear them:

1. Go to Admin > Dashboard, click the Gear Icon, and refresh Theme and Sass caches.
2. Go to Extensions > Modifications, click Refresh.
3. In XAMPP, delete cache files:

   del /s /q C:\xampp\htdocs\your_opencart\system\storage\cache\cache.*

Step 4: Test Your Changes

Let’s make sure everything works:

1. Go to Admin > Catalog > Products, edit a product (e.g., ID 1).
2. In the Data tab, find the Custom Field text box. Enter “Eco-Friendly” and save.
3. Check the database:

   SELECT product_id, custom_field FROM oc_product WHERE product_id = 1;

   Should show custom_field = 'Eco-Friendly'.
4. Visit the product page on the frontend (e.g., index.php?route=product/product&product_id=1). You should see “Custom Info: Eco-Friendly”.

Troubleshooting Tips

• Text Box Empty? Check admin/model/catalog/product.php. Ensure $product_data['custom_field'] = $product_data['custom_field'] ?? ''; is correct (no json_decode).

Multi-Language Support

If your store supports multiple languages, you might want custom_field to be language-specific (e.g., “Eco-Friendly” in English, “Écologique” in French). Instead of adding custom_field to oc_product, add it to oc_product_description:

ALTER TABLE `oc_product_description` ADD `custom_field` VARCHAR(200) DEFAULT '';

Update admin/model/catalog/product.php’s getProductDescriptions and editProduct to handle it, similar to description. This makes your store more global-friendly!

Final Thoughts

Adding a custom field in OpenCart is a simple way to make your store unique. Whether it’s a product badge, warranty info, or dietary details, custom_field gives you flexibility. Always test changes in a local XAMPP setup (like C:\xampp\htdocs\your_opencart) and back up your files.

To show our custom_field on the store's front page, Check out our next tutorial to display it on the Product Detail and Compare pages!

Let us know in the comments how you used your custom field!