OsCommerce v.4.0 Code Guide

From osCommerce Wiki
Revision as of 19:06, 24 February 2023 by Admin (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


In this guide we would like to review the structure and show the basics of using osCommerce v.4.0.


The minimum requirement by this project is that your Web server supports PHP 7.0.

Structure overview

First of all the access points to the different web applications are worth highlighting. In spite of the fact that the code of the different web applications will almost completely be in the directory lib, the directories are used to access the different system parts. It visually allows to divide alias for system users.

.. - is the frontend launcher folder. This part is used by default.

admin/ - backend launcher folder. The path will be as follows: your.site/admin/

Also you can face the other similar directories, for example: pos, rest

The general peculiarity that makes them different is the presence of index.php and the traffic redirect to this file.

The web application names are conditional and can be renamed.

Note: The creation of pages matching the folder names may cause their inoperability. For example, the product and the category with SEO name "admin"

Each application has its own resource folders:

assets – this directory has the cache results, styles and js scripts, compiled and ready for using.

images – the images related to the application but independent from the theme.

includes – the outdated code part, the notable thing is placing the configuration file in the subfolder local.

themes – the interface parts, they include css, fonts, images and javascript.

Note: Images for products and categories are placed in the main web application but are used by all the applications.

lib/ - The main code part is included in this directory. The contents are divided according to the content:

common/ - the general functional part. It has the code that is used by the different web applications equally.

api/ contains high-level models that allow to perform the data import/export in different formats

classes/ contains the classes used in both backend and frontend

components/ the user components

config/ contains the configuration files

extensions/ the different extensions extending the basic version possibilities. See the chapter Extensions below.

forms/ allow to enter and display the data providing the interaction between a user and the database via models

heplers/ the set of classes, that are logically divided and contain the static functions

models/ contains the model classes used in both backend and frontend. See the chapter Models below.

modules/ includes the implementations of the different parts interaction with a user and the outside world, such as the payment systems and the shipping. See the chapter Modules below.

services/ the code fragments with the logic general for different controllers are extracted into the separate classes called the application level services

widgets/ allow to create the HTML Bootstrap components quickly

The functional part of the remaining web applications is placed on the directory level in the following folders:

backend/ admin part

frontend/ default web application

pos/ additional web application

rest/ additional web application

All of them have the same type internal structure. The part of folders is similar with the general functional part:






as well as some folders extending the functionality of the web applications

assets/ contains application assets such as JavaScript and CSS

config/ configuration extended files

design/ blocks representing the extended widgets

controllers/ contains the controller classes

web/ contains the entry script

views/ contains the default view files for application, this functionality is overridden by themes/

themes/ extension for views, allowing to divide the application templates into a few themes

runtime/ contains the temporary files created during the command execution (logging, caching)

The console application plays the separate role: console/

config/ configuration console files

controllers/ contains controllers executing the role of commands

migrations/ database migrations

models/ console-specific model classes

runtime/ contains the temporary files created during the command execution (logging, caching)

vendor/ - The main part of the external libraries, includes framework, these are the main ones:

yiisoft/ framework Yii2 – is the highly productive component PHP framework designed for the quick development of the modern web applications osCommerce v.4.0 is based on.

smarty/ template engine used by the system

imagine/ image manipulation library

mobiledetect/ Mobile Detect is a lightweight PHP class for detecting mobile devices (including tablets)

eazyang/ HTML Purifier

phpoffice/ library written in pure PHP offers a set of classes that allows you to read and write various spreadsheet file formats such as Excel and LibreOffice Calc.

tecnickcom/ library for generating PDF documents on-the-fly.

Note: It is not recommended to change the folder vendor contents on your own.

The principle of using MVC structure

Model-View-Controller – is the scheme of dividing the application data and the managing logic into 3 separate components: model, view and controller – in such a way that each component modification can be done independently.

Controller interprets the user actions informing the model about the change necessity.

Each controller will have a number of actions. You should stick to the naming rule: all the controller classes should end with Controller, all the deprecated functions should start with action.

Due to the URL Router the queries in the browser will be interpreted in the call of the specific event.

For example, yoursite/account/login-me will be interpreted as the call of the actionLoginMe function from the controller AccountController of the default web application [/lib/frontend/controllers].

The controller and the event have the default state index that will be executed if their instructions are absent.

Note: Avoid the thick controllers and doubling the code. It will ease the development in the future.

Model represents the data and reacts to the controller commands changing its state. It is the model that provides the interaction with the database.

The model classes are created via extending the basic class yii\base\Model. The data read from the database is converted into the attributes and can be accessible as the usual object properties or the array elements.

Wherein the data extraction from the database will look like the object initialization:

$customer = \common\models\Customers::findOne(1);

by changing the object value it is possible to save the data in the database:


We will review the models in more detail in the separate chapter.

Note: In the code you can come across the function calls like "tep_db_" that are deprecated and not recommended for using.

View is responsible for displaying the model data to the user, reacting to the model changes. In our case as the handler the template engine Smarty replacing the standard one is used.

Where should the template file be placed? It is quite simple. By requesting the file render from the function actionLoginMe in the controller AccountController mentioned in the sample above:


we should place the file with the name index.tpl in the corresponding folder [/lib/frontend/themes/basic/account] where account is the name indicator of our controller.


Model is the basic class extended from Active Record and it provides the working data in the attributes. Each attribute represents the publicly accessible model property.

In order to make the new model file work it is enough to have the corresponding table in the database. The model name is usually given in the camel form. Thus the table address_book will have the class AddressBook. With proper inheritance from ActiveRecord the minimum requirement for the class will be the presence of the function tableName, returning the actual table name in the database.

The model location can be anywhere but according to the accepted architecture the publicly accessible classes are located in the corresponding subsection of the common folder [/lib/common/models].

If the table is the specific one for using only in one web application this table should be placed in the models folder of this application.

It is allowed to use your own models for Extensions. In this case the local models can be located in the models subfolder.


Modules are divided into a few types and also divided according to the subcategories. Let us review the key subtypes:

label/ this model type is intended for shipping and tracking orders, the interaction or its absence with the chosen shipping option is done in the settings. Altogether you can use the same shipping option regardless of the method.

OrderPayment/ is intended for executing the user payments. It can be both formal (offline) and complete implementation of the payment system

orderShipping/ shipping methods provided to a user. In fact they represent the shipping cost calculation.

orderTotal/ this type makes the cost calculation settings more flexible and manageable. For example, if the shipping module total is switched off it removes the shipping calculation from the calculation.


The extension structure is not strictly regulated but the general concept is to stick to the web application structure. In the first place these are the following elements:

classes/ contains classes

helpers/ classes including the static functions

models/ contains model classes

views/ templates used by the application

Bootstrap.php if the module supports its own controllers it will be shown in this file

And the main class file whose name should match the module directory name.