Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 27 ยท Getting started

Setting Up a Development Store

Set up a local OpenCart 4 store with Docker, XAMPP or Herd, understand the two config.php files, move storage out of the web root and turn on developer settings.

You cannot learn extension development by reading alone. You need a store you can break, with errors visible, caches that do not hide your changes, and a database you can reset in a minute. This lesson shows how to build that store on your own computer and explains the two configuration files that every OpenCart developer ends up editing.

Because the real installer cannot run on this website, the setup steps are read-only commands and file listings. The runnable examples are stand-ins: a parser for the define() lines in a config file and a resolver that works out where OpenCart keeps things on disk. Both are useful tools in their own right.

What you need

OpenCart 4 is a PHP and MySQL (or MariaDB) application. For development you need:

  • A recent PHP version supported by your OpenCart release, with the usual extensions (mysqli, gd, curl, zip, mbstring, openssl). The release notes of the version you download list exact requirements.
  • MySQL or MariaDB.
  • A web server (Apache or Nginx) that serves the OpenCart folder.
  • A way to unzip and edit files, plus a code editor.

Any of the common local stacks work. Pick the one you know:

Option Good for Notes
XAMPP Windows beginners Apache, PHP and MariaDB in one installer
Laravel Herd Windows or macOS users who like fast PHP switching Serves a folder as name.test; add a database server separately
Docker Compose Repeatable, disposable setups One file defines PHP, web server and database

Whatever you choose, match PHP to the version your target customers use. Many shops still run older PHP releases, and an extension that needs a brand new PHP feature will not install for them.

Installing OpenCart 4

The release archive contains a folder named upload. Everything inside upload is what you serve. The usual routine looks like this:

Terminal
# 1. Download a release zip from the official GitHub releases page and unzip it
unzip opencart-4.0.2.3.zip -d oc-src

# 2. Copy the contents of upload/ into the web root of your site
cp -r oc-src/upload/* /var/www/shop/

# 3. Create the two config files from their templates
cd /var/www/shop
cp config-dist.php config.php
cp admin/config-dist.php admin/config.php

# 4. Create an empty database and a user for it
mysql -u root -p -e "CREATE DATABASE opencart CHARACTER SET utf8mb4;"

Then open the site in a browser. It redirects you to /install, a short wizard that checks requirements, asks for the database connection and an admin account, and writes the real values into both config.php files. When it finishes, delete the install folder, because leaving it online is a security hole.

Version numbers above are examples. Download the release you want to build against, and check its own instructions, since small details of the installer change between 4.x releases.

A Docker Compose file for the same job might look like the sketch below. It is an outline, not a tested recipe: image names and versions change, so check them before use.

YAML
services:
  web:
    image: php:8.2-apache
    volumes:
      - ./upload:/var/www/html
    ports:
      - "8081:80"
  db:
    image: mariadb:11
    environment:
      MARIADB_DATABASE: opencart
      MARIADB_USER: oc
      MARIADB_PASSWORD: change-me
      MARIADB_ROOT_PASSWORD: change-me-too

The stock PHP image lacks some extensions OpenCart needs (gd, zip, mysqli), so a real setup adds a short Dockerfile that installs them.

The two config.php files

OpenCart has one configuration file per application: config.php in the root for the storefront, and admin/config.php for the back office. Both are plain PHP files full of define() calls. The ones you will meet most often are:

PHP
<?php
// config.php (storefront), abridged
define('HTTP_SERVER', 'http://shop.test/');
define('DIR_OPENCART', '/var/www/shop/');
define('DIR_APPLICATION', DIR_OPENCART . 'catalog/');
define('DIR_EXTENSION', DIR_OPENCART . 'extension/');
define('DIR_IMAGE', DIR_OPENCART . 'image/');
define('DIR_SYSTEM', DIR_OPENCART . 'system/');
define('DIR_STORAGE', DIR_SYSTEM . 'storage/');
define('DIR_LANGUAGE', DIR_APPLICATION . 'language/');
define('DIR_TEMPLATE', DIR_APPLICATION . 'view/template/');
define('DIR_CONFIG', DIR_SYSTEM . 'config/');
define('DIR_CACHE', DIR_STORAGE . 'cache/');
define('DIR_LOGS', DIR_STORAGE . 'logs/');

define('DB_DRIVER', 'mysqli');
define('DB_HOSTNAME', 'localhost');
define('DB_USERNAME', 'oc');
define('DB_PASSWORD', '...');
define('DB_DATABASE', 'opencart');
define('DB_PORT', '3306');
define('DB_PREFIX', 'oc_');

The admin file is similar but its DIR_APPLICATION points at admin/, and it also defines HTTP_CATALOG so the back office can link to the storefront. Learn these names; extension code uses them constantly. DB_PREFIX matters most: every table name in a query is written as DB_PREFIX . 'product', never as a bare product, because the shop owner may have chosen a different prefix.

Reading these files by hand is fine, but a small tool that parses them is handy when you juggle several test stores. The stand-in below does exactly that for the simplest define() forms and resolves constants that are built from other constants.

PHP Parse a config file and resolve paths

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The pattern is a deliberate simplification: it only understands quoted strings joined with constant names, and it would not cope with function calls or escaped quotes. That is a good reminder that real PHP files should be loaded by PHP, not parsed with a pattern. Our tool exists to show how the constants chain together.

Move storage outside the web root

DIR_STORAGE points at a folder that holds logs, cache, sessions, uploads, downloads and the marketplace files used by the extension installer. By default it sits under system/storage/ inside the web root, which means a mis-configured server might serve log files or session data to the public. OpenCart's own advice is to move it somewhere the web server cannot reach, for instance a sibling of the web root:

TEXT
/var/www/
  shop/             web root (what the server shows)
  shop-storage/     moved storage, not reachable by URL
    cache/  logs/  session/  upload/  download/  vendor/  marketplace/

Move the folder, then change the one line in both config files:

PHP
define('DIR_STORAGE', '/var/www/shop-storage/');

The installer can offer to do this for you. Either way, make sure the web server user can write to the new location, and verify that visiting a URL such as /system/storage/logs/error.log returns a 404 or 403. Never put database passwords in a folder that the web server can serve.

PHP Where do things live?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Developer settings and error display

Out of the box, OpenCart caches compiled Twig templates and SASS output so pages are fast. While developing, that cache can make your edits seem to do nothing. Two places control the behaviour:

  1. Developer settings in the admin: the dashboard offers a button (a cog) that opens a dialog with switches for the theme (template) cache and the SASS cache, and buttons to clear them. Turn the caches off in development, and clear them whenever a change seems ignored.
  2. System > Settings > edit your store > Server tab: here you can choose to display errors, log errors and name the log file.

Switch on Display errors and Log errors in development. Turn display off on a live store: visitors should never see a PHP stack trace. The log is written to the logs folder of your storage, usually as error.log, and you can open it from the admin under System > Maintenance > Error Logs. When something fails silently, the log is the first place to look.

For fast feedback also keep PHP's own settings in line while developing:

INI
display_errors = On
error_reporting = E_ALL

Finally, put the whole project under version control, but keep the real config.php files and the storage folder out of it, because they contain passwords. Many teams commit config-dist.php only.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder of the release archive do you copy into your web root?

    The release zip holds a folder named upload; its contents are the application.
  2. 2. Why are table names written as DB_PREFIX . 'product' in queries?

    The prefix is configurable. Hard-coding oc_ would break shops that chose another prefix.
  3. 3. What is the main reason to move DIR_STORAGE outside the web root?

    Storage holds logs, sessions and uploaded files. Keeping it unreachable by URL protects them.
  4. 4. After the install wizard finishes, what should you do with the install folder?

    A left-over installer is a security risk. Remove it as soon as installation succeeds.

Summary

  • Serve the contents of the upload folder; run the /install wizard; delete install afterwards.
  • There are two config files, config.php and admin/config.php, made of define() constants. Use DB_PREFIX in every query.
  • Move DIR_STORAGE outside the web root and update both files.
  • In development, turn off the theme and SASS caches in the developer settings, and turn on error display and logging.
  • Never display errors on a live store, and keep real config files out of version control.

Next: Anatomy of an Extension