• About
• Compatibility Guarantee
• System Requirements
• Installation
• Upgrade
• Uninstallation: How to Revert to OpenCart 4.1.0.3
• Local Development with Docker
  • Using Make
  • Using Docker CLI
  • Docker Environment
  • SSL Configuration
  • Disabling SSL
  • Profiling with XDebug
• Code Quality
• Credits & Sources
• License

This project is a collection of improvements and fixes, based on OpenCart 4.1.0.3.
The CHANGELOG file contains a comprehensive list of all modifications, including direct links to original sources, pull requests, and issue reports.

To provide a stable, production-ready environment by backporting essential fixes while strictly avoiding the breaking changes found in the official development branches. This ensures a robust, production-ready core that remains a drop-in replacement for any 4.1.0.3-compatible environment.

This project are strictly developed to maintain full backward compatibility with OpenCart 4.1.0.3. All included fixes and improvements have been extensively tested on live production sites. They are fully compatible with major frameworks and heavy-duty extensions, including Journal 3.2.10 and MazaEngine 1.13.10 (Poco Theme).

If your extension worked on clean OpenCart 4.1.0.3, it should work on OC+. However, since several libraries (including jQuery) have been updated, some legacy extensions might require updates or replacements.

Most importantly, the error.log on these production environments has remained clean for a long period, confirming the stability and reliability of this build.

For a real-world example in action, you can visit small multilanguage website: https://isoap.ge

• Core: OC+ from this repository.
• Framework: Running flawlessly on Journal v.3.2.10.
• Stability: Zero errors in the logs.

• Web Server: Apache 2.x.x.
  While operation on Nginx + PHP-FPM is theoretically possible, it has not been tested yet.
• Database Server: Current versions of MariaDB or MySQL.
  OC+ has not been tested with PostgreSQL, and compatibility is not guaranteed.
• PHP: 8.2 – 8.5 (PHP 8.4 is recommended).
• PHP Settings:
  • max_execution_time = 150
  • max_input_time = 180
  • memory_limit = 256M (at least 384M recommended for developers)
• Required PHP Extensions: the following extensions are required. Most of these are likely already enabled on your server: fileinfo, mysqli, openssl, simplexml, zip, json, ctype, curl, dom, gd, iconv, intl, mbstring, session, tokenizer, xml, xmlwriter.

1. Check Requirements: Ensure your server environment meets all the system requirements listed above.
2. Prepare the Database (MariaDB or MySQL):
   • Create a new empty database.
   • Assign (or create) a database user with full privileges (CREATE, DROP, etc.) for this database.
   • Note down your database credentials: Hostname (or IP), Username, Password, and Database Name.
3. Upload Files: Extract the downloaded oc_xxx.zip archive into the root directory of your virtual web host (the folder accessible via the Internet at your domain address).
4. Run Installer: Open your web browser and navigate to https://your-domain.com.
5. Follow Instructions: The web installer will launch automatically; follow the on-screen steps to complete the setup.
6. Post-Installation: Once the installation is finished, manually delete the /install folder for security reasons.

1. Version Compatibility: This upgrade package is designed strictly for OpenCart 4.1.0.3.
2. Unsupported Versions: upgrade package is incompatible with any other versions of OpenCart, including the official master branch or any other 4.x.x.x releases.
3. Pre-requisite: If you are running an older version of OpenCart, you must first upgrade to version 4.1.0.3 before applying this upgrade package.
4. Extension Compatibility: this upgrade package has been tested with various extensions, including major frameworks like Journal and MazaEngine, and no issues were found. If it worked on clean OpenCart 4.1.0.3, it should work on this. However, since several libraries (including jQuery) have been updated, some legacy extensions might require updates or replacements.

1. Extract Core Files: Unpack the upgrade.xxx.zip archive directly into your web host's root directory, overwriting all existing OpenCart 4.1.0.3 files.
2. Handle Storage/Vendor Files: Since OpenCart 4 requires moving the /system/storage folder after the initial installation, the updated vendor libraries are provided as a separate part of the package.
3. Update Vendor Directory: Locate your current /storage folder (wherever you moved it during setup). Extract the contents of the upgrade_vendor.xxx.zip archive into this folder, ensuring all files within the existing /vendor directory are overwritten.
4. Clear Caches: Log in to your Admin Panel. Go to Dashboard -> Developer Settings (the gear icon in the top right corner) and refresh/clear: System Cache, Image Cache, and SASS.
5. Verification: Check both the storefront and the Admin Panel. If the steps were followed correctly, everything should be fully functional.

Note on Database: The database structure remains unchanged and is fully compatible with OpenCart 4.1.0.3. No update scripts are required—simply replace the files, and you are ready to go.

Troubleshooting: If critical issues occur (e.g., the site becomes inaccessible) and you cannot identify the cause, restore your site using the backup you created before starting the upgrade.

OC+ does not make any changes to the database structure.
Because of this, reverting back to stock OpenCart 4.1.0.3 is entirely risk-free and straightforward: simply replace all the files in your website's root directory with the files from the official OpenCart 4.1.0.3 distribution, and you are good to go.

• Start all services

  make up

• Stop all services

  make down

• Dump database: the dump will be saved to .docker/db-import/dump.sql

  make db-dump

• Restore a saved database dump

  make db-restore

• Start all services

  docker-compose up -d

The project environment will be available at the following addresses:

• Storefront: https://localhost
  • Login: customer@example.com
  • Password: testuser
• Administration: https://localhost/admin
  • Login: admin
  • Password: admin
  • Email: admin@example.com
• Mailpit (Email Testing): http://localhost:8025
• Database (MariaDB):
  • Host: mysql
  • Username: root
  • Password: root
  • Database Name: opencart
• Logs: all service logs (Web server, PHP, etc.) are accessible in the .docker/log directory for easy debugging.

The project is configured to use SSL (HTTPS) by default. To prevent browser connection errors, please choose one of the following options:

• Install CA Certificate (recommended): Import the CA certificate located at .docker/web/ssl/ca.crt into your operating system's trusted store.
• Or use Custom Certificates: Replace the existing .docker/web/ssl/localhost.crt and .docker/web/ssl/localhost.key with your own generated certificates for localhost.

If you prefer to use standard HTTP, you can disable SSL by modifying the following configuration files:

• www/config.php: change https to http on line 6.
• www/admin/config.php: change https to http on lines 6 and 7.

After these changes, the store will be accessible via http://localhost and http://localhost/admin.

You can perform detailed profiling using XDebug to analyze the performance of all subsystems and identify bottlenecks.

1. Enable XDebug
   • uncomment all lines in the configuration file .docker/web/config/xdebug.ini
   • rebuild container: run the following command:

     make down && make build && make up

2. Sequentially open in your browser all the necessary pages on which you want to analyze performance
   (e.g., Homepage: https://localhost).
3. Disable XDebug
   • comment all lines (by ;) in the configuration file .docker/web/config/xdebug.ini
   • rebuild container: run the following command:

     make down && make build && make up

4. Done: the detailed profiling log will be available at:
   .docker/log/xdebug/cachegrind.out.XX.gz
   You can now open this file in your preferred analysis tool to inspect the performance data.

To maintain high code quality and prevent hidden regressions, we use PHPStan for static analysis and PHP-CS-Fixer for coding standards enforcement. It is highly recommended to run these Full Check before submitting any changes.

• PHP 8.1 – 8.5
• Composer

You can run the full suite or individual checks using the following commands:

• Full Check (Runs both CS and Static Analysis):

  composer check

• Coding Standards Check:

  composer cs-check

• Coding Standards Check with DIFF display:

  composer cs-check-diff

• Coding Standards Fix (Automatically fixes formatting issues):

  composer cs-fix

• Static Analysis (Runs PHPStan):

  composer static-analysis

To ensure transparency and acknowledge the work of the community, direct links to original sources or discussions are provided in the CHANGELOG for any borrowed or ported code.

Modifications without a specific link were developed within this repository.

GNU General Public License v.3