Child pages
  • Diving into PrestaShop Core development

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Table of contents

Table of Contents
maxLevel3

Diving into PrestaShop Core development

Accessing the database

The database structure

PrestaShop's database tables start with the ps_ prefix. Note that this can be customized during installation

All table names are in lowercase, and words are separated with an underscore character ("_").

When a table establishes the links between two entities, the names of both entities are mentioned in the table's name. For instance, ps_category_product links products to their category.

A few details to note:

  • Use the id_lang field to store the language associated with a record.
  • Use the id_shop field to store the store associated with a record.
  • Tables which contain translations must end with the _lang suffix. For instance, ps_product_lang contains all the translations for the ps_product table.
  • Tables which contain the records linking to a specific shop must end with the _shop suffix. For instance, ps_category_shop contains the position of each category depending on the store.

The ObjectModel class

This is the main object of PrestaShop's object model. It can be overridden with precaution.

It is an Active Record kind of class (see: http://en.wikipedia.org/wiki/Active_record_pattern). PrestaShop's database table attributes or view attributes are encapsulated in the class. Therefore, the class is tied to a database record. After the object has been instantiated, a new record is added to the database. Each object retrieves its data from the database; when an object is updated, the record to which it is tied is updated as well. The class implements accessors for each attribute.

Defining the model

You must use the $definition static variable in order to define the model.

For instance:

Code Block
/**
* Example from the CMS model (CMSCore) 
*/
public static $definition = array(
  'table' => 'cms',
  'primary' => 'id_cms',
  'multilang' => true,
  'fields' => array(
    'id_cms_category'  => array('type' => self::TYPE_INT, 'validate' => 'isUnsignedInt'),
    'position'         => array('type' => self::TYPE_INT),
    'active'           => array('type' => self::TYPE_BOOL),
    // Lang fields
    'meta_description' => 
        array('type' => self::TYPE_STRING, 'lang' => true, 'validate' => 'isGenericName', 'size' => 255),
    'meta_keywords'    => 
        array('type' => self::TYPE_STRING, 'lang' => true, 'validate' => 'isGenericName', 'size' => 255),
    'meta_title'       => 
        array('type' => self::TYPE_STRING, 'lang' => true, 'validate' => 'isGenericName', 'required' => true, 'size' => 128),
    'link_rewrite'     =>
        array('type' => self::TYPE_STRING, 'lang' => true, 'validate' => 'isLinkRewrite', 'required' => true, 'size' => 128),
    'content'          => 
        array('type' => self::TYPE_HTML,   'lang' => true, 'validate' => 'isString', 'size' => 3999999999999),
  ),
);

A model for many stores and/or languages

In order to have an object in many languages:

Code Block
'multilang' => true

In order to have an object depending on the current store

Code Block
'multishop' => true

In order to have an object which depends on the current store, and in many languages:

Code Block
'multilang_shop' => true

The main methods

Any overriding of the ObjectModel methods is bound to influence how all the other classes and methods act. Use with care.

Method name and parametersDescription

__construct($id = NULL, $id_lang = NULL)

Build object.

add($autodate = true, $nullValues = false)

Save current object to database (add or update).

associateTo(integer|array $id_shops)

Associate an item to its context.

delete()

Delete current object from database.

deleteImage(mixed $force_delete = false)

Delete images associated with the object.

deleteSelection($selection)

Delete several objects from database.

getFields()

Prepare fields for ObjectModel class (add, update).

getValidationRules($className = _CLASS_)

Return object validation rules (field validity).

save($nullValues = false, $autodate = true)

Save current object to database (add or update).

toggleStatus()

Toggle object's status in database.

update($nullValues = false)

Update current object to database.

validateFields($die = true, $errorReturn = false)

Check for field validity before database interaction.

The DBQuery class

The DBQuery class is a query builder which helps you create SQL queries. For instance:

Code Block
$sql = new DbQuery();
$sql->select('*');
$sql->from('cms', 'c');
$sql->innerJoin('cms_lang', 'l', 'c.id_cms = l.id_cms AND l.id_lang = '.(int)$id_lang);
$sql->where('c.active = 1');
$sql->orderBy('position');
return Db::getInstance()->executeS($sql

Here are some of the methods from this class:

Method name and parametersDescription
__toString()Generate and get the query.
build()Generate and get the query (return a string).
from(string $table, mixed $alias = null)Set table for FROM clause.
groupBy(string $fields)Add a GROUP BY restriction.
having(string $restriction)

Add a restriction in the HAVING clause (each restriction will be separated by an AND statement).

innerJoin(string $table, string $alias = null, string $on = null)

Add INNER JOIN clause, E.g. $this->innerJoin('product p ON ...').

join(string $join)

Add JOIN clause, E.g. $this->join('RIGHT JOIN'._DB_PREFIX_.'product p ON ...');.

leftJoin(string $table, string $alias = null, string $on = null)Add LEFT JOIN clause.
leftOuterJoin(string $table, string $alias = null, string $on = null)

Add LEFT OUTER JOIN clause.

limit(string $limit, mixed $offset = 0)Limit results in query.
naturalJoin(string $table, string $alias = null)Add NATURAL JOIN clause.
orderBy(string $fields)Add an ORDER B restriction.
select(string $fields)Add fields in query selection.
where(string $restriction)

Add a restriction in WHERE clause (each restriction will be separated by an AND statement).

The Dispatcher

The Dispatcher is one of the main technical features of v1.5. It handles URL redirections. Instead of using multiple files in the root folder like product.php, order.php or category.php, only one file is used: index.php. From now on, internal URL will look like index.php?controller=category, index.php?controller=product, etc.

Additionally, the Dispatcher is built to support URL rewriting. Therefore, when URL-rewriting is off, PrestaShop will use the following URL form:

Code Block
http://myprestashop.com/index.php?controller=category&id_category=3&id_lang=1
http://myprestashop.com/index.php?controller=product&id_product=1&id_lang=2

...and when URL-rewriting is on (or "Friendly URLs"), PrestaShop's Dispatcher will correctly support this URL form:

Code Block
http://myprestashop.com/en/3-music-ipods
http://myprestashop.com/fr/1-ipod-nano.html

There are several advantages for this system:

  • It is easier to add a controller.
  • You can use custom routes to change your friendly URLs (which is really better for SEO!)
  • There is only one single entry point into the software, which improves PrestaShop's reliability, and facilitates future developments.

The Dispatcher makes use of three new 1.5 abstract classes: Controller, FrontController and AdminController (the last two inheriting from the first one).

New routes can be created by overriding the loadRoutes() method.
The store administrator can change a controller's URL using the "SEO & URLs" page in the back-office's "Preferences" menu.

Controllers

In the MVC architecture, a Controller manages the synchronization events between the View and the Model, and keeps them up to date. It receives all the user events and triggers the actions to perform.
If an action needs data to be changed, the Controller will "ask" the Model to change the data, and in turn the Model will notify the View that the data has been changed, so that the View can update itself.

All of PrestaShop's controllers actually override the Controller class through another inheriting class, such as AdminController, ModuleAdminController, FrontController, ModuleFrontController, etc.

The FrontController class

Some of the class' properties:

PropertyDescription
$templateTemplate name for page content.
$css_filesArray list of CSS files.
$js_filesArray list of JavaScript files.
$errorsArray of errors that have occurred.
$guestAllowedWhether a customer who has signed out can access the page.
$initializedWhether the init() function has been called.
$isoThe ISO code of the currently selected language.
$nThe number of items per page.
$orderByThe field used to sort.
$orderWayWhether to sort is ascending or descending ("ASC" or "DESC").
$pThe current page number.
$ajaxIf the ajax parameter is detected in request, set this flag to true.

Execution order of the controller's functions

  1. __contruct(): Sets all the controller's member variables.
  2. init(): Initializes the controller.
  3. setMedia() or setMobileMedia(): Adds all JavaScript and CSS specifics to the page so that they can be combined, compressed and cached (see PrestaShop's CCC tool, in the back-office "Performance" page, under the "Advanced preferences" menu).
  4. postProcess(): Handles ajaxProcess.
  5. initHeader(): Called before initContent().
  6. initContent(): Initializes the content.
  7. initFooter(): Called after initContent().
  8. display() or displayAjax(): Displays the content.

Existing controllers

Controller's filenameDescription
AddressController.phpUsed by address.php to edit a customer's address.
AddressesController.phpUsed by addresses.php to get customer's addresses.
AuthController.phpUsed by authentication.php for customer login.
BestSalesController.phpUsed by best-sales.php to get best-sellers.
CartController.phpUsed by cart.php to manage the customer's cart.
CategoryControllerUsed by category.php to get product categories.
CMSController.phpUsed by cms.php to get a CMS page.
CompareController.phpUsed by products-comparison.php to compare products.
ContactController.phpUsed by contact-form.php to send messages.
DiscountController.phpUsed by discount.php to get a customer's vouchers.
GuestTrackingController.phpUsed by guest-tracking.php to manage guest orders.
HistoryController.phpUsed by history.php to get a customer's orders.
IdentityController.phpUsed by identity.php for customer's personal info.
IndexController.phpUsed by index.php to display the homepage.
ManufacturerController.phpUsed by manufacturer.php to get manufacturers.
MyAccountController.phpUsed by my-account.php to manage customer account.
NewProductsController.phpUsed by new-products.php to get new products.
OrderConfirmationController.phpUsed by order-confirmation.php for order confirmation.
OrderController.phpUsed by order.php to manage the five-step checkout.
OrderDetailController.phpUsed by order-detail.php to get a customer order.
OrderFollowController.phpUsed by order-follow.php to get a customer's returns.
OrderOpcController.phpUsed by order-opc.php to manage one-page checkout.
OrderReturnController.phpUsed by order-return.php to get a merchandise return.
OrderSlipController.phpUsed by order-slip.php to get a customer's credit slips.
PageNotFoundController.phpUsed by 404.php to manage the "Page not found" page.
ParentOrderController.phpManages shared order code.
PasswordController.phpUsed by password.php to reset a lost password.
PricesDropController.phpUsed by prices-drop.php to get discounted products.
ProductController.phpUsed by product.php to get a product.
SearchController.phpUsed by search.php to get search results.
SitemapController.phpUsed by sitemap.php to get the sitemap.
StoresController.phpUsed by stores.php to get store information.
SupplierController.phpUsed by supplier.php to get suppliers.

Overriding a controller

Thanks to object inheritance, you can change a controller's behaviors, or add new ones.

PrestaShop's controllers are all stored in the /controllers folder, and use the "Core" suffix.

For instance, when working with the Category controller:

  • File: /controllers/CategoryController.php
  • Class: CategoryControllerCore

In order to override a controller, you must first create a new class without the "Core" suffix, and place its file in the /override/controllers folder.

For instance, when overriding the Category controller:

  • File: /override/controllers/front/CategoryController.php
  • Class: CategoryController

Views

PrestaShop uses the Smarty template engine to generate its views: http://www.smarty.net/

The views are stored in .tpl files.

A view name is generally the same as the name for the code using it. For instance, 404.php uses 404.tpl.

Info
titleView overriding

As there is no inheritance, there is no way to override a view.

In order to change a view, you must rewrite the template file, and place it in your theme's folder.

Cookies

PrestaShop uses encrypted cookies to store all the session information, for visitors/clients as well as for employees/administrators.

The Cookie class (/classes/Cookie.php) is used to read and write cookies.

In order to access the cookies from within PrestaShop code, you can use this:

Code Block
$this->context->cookie;

All the information stored within a cookie is available using this code:

Code Block
$this->context->cookie->variable;

If you need to access the PrestaShop cookie from non-PrestaShop code, you can use this code:

Code Block
include_once('path_to_prestashop/config/config.inc.php');
include_once('path_to_prestashop/config/settings.inc.php');
include_once('path_to_prestashop/classes/Cookie.php');
$cookie = new Cookie('ps'); // Use "psAdmin" to read an employee's cookie.

Data stored in a visitor/client's cookie

TokenDescription
date_addThe date and time the cookie was created (in YYYY-MM-DD HH:MM:SS format).
id_langThe ID of the selected language.
id_currencyThe ID of the selected currency.
last_visited_categoryThe ID of the last visited category of product listings.
ajax_blockcart_displayWhether the cart block is "expanded" or "collapsed".
viewedThe IDs of recently viewed products as a comma-separated list.
id_wishlistThe ID of the current wishlist displayed in the wishlist block.
checkedTOSWhether the "Terms of service" checkbox has been ticked (1 if it has and 0 if it hasn't)
id_guestThe guest ID of the visitor when not logged in.
id_connectionsThe connection ID of the visitor's current session.
id_customerThe customer ID of the visitor when logged in.
customer_lastnameThe last name of the customer.
customer_firstnameThe first name of the customer.
loggedWhether the customer is logged in.
passwdThe MD5 hash of the _COOKIE_KEY_ in config/settings.inc.php and the password the customer used to log in.
emailThe email address that the customer used to log in.
id_cartThe ID of the current cart displayed in the cart block.
checksumThe Blowfish checksum used to determine whether the cookie has been modified by a third party.
The customer will be logged out and the cookie deleted if the checksum doesn't match.

Data stored in an employee/administrator's cookie

TokenDescription
date_addThe date and time the cookie was created (in YYYY-MM-DD HH:MM:SS format).
id_langThe ID of the selected language.
id_employeeThe ID of the employee.
lastnameThe last name of the employee.
firstnameThe first name of the employee.
emailThe email address the employee used to log in.
profileThe ID of the profile that determines which tabs the employee can access.
passwdThe MD5 hash of the _COOKIE_KEY_ in config/settings.inc.php and the password the employee used to log in.
checksumThe Blowfish checksum used to determine whether the cookie has been modified by a third party.
If the checksum doesn't match, the customer will be logged out and the cookie is deleted .

Hooks

Hooks are a way to associate your code to some specific PrestaShop events.

Most of the time, they are used to insert content in a page.

For instance, the PrestaShop default theme's home page has the following hooks:

Hook nameDescription
displayHeaderDisplays the content in the page's header area.
displayTopDisplays the content in the page's top area.
displayLeftColumnDisplays the content in the page's left column.
displayHomeDisplays the content in the page's central area.
displayRightColumnDisplays the content in the page's right column.
displayFooter

Displays the content in the page's footer area.

Hooks can also be used to perform specific actions under certain circumstances (i.e. sending an e-mail to the client).

You can get a full list of the hooks available in PrestaShop 1.5 in the "Hooks in PrestaShop 1.5" chapter of the Developer Guide.

Using hooks

...in a controller

It is easy to call a hook from within a controller: you simply have to use its name with the hookExec() method: Module::hookExec('NameOfHook');

For instance:

Code Block
$this->context->smarty->assign('HOOK_LEFT_COLUMN', Module::hookExec('displayLeftColumn'));

...in a module

In order to attach your code to a hook, you must create a non-static public method, starting with the "hook" keyword followed by either "display" or "action", and the name of the hook you want to use.

This method receives one (and only one) argument: an array of the contextual information sent to the hook.

Code Block
public function hookDisplayNameOfHook($params)
{
    // Your code.
}

In order for a module to respond to a hook call, the hook must be registered within PrestaShop. Hook registration is done using the registerHook() method. Registration is usually done during the module's installation.

Code Block
public function install()
{
    return parent::install() && $this->registerHook('NameOfHook');
}

...in a theme

It is easy to call a hook from within a template file (.tpl): you simply have to use its name with the hook function. You can add the name of a module that you want the hook execute.

For instance:

Code Block
{hook h='displayLeftColumn' mod='blockcart'}

Creating your own hook

You can create new PrestaShop hooks by adding a new record in the ps_hook table in your MySQL database. You could do it the hard way:

Code Block
INSERT INTO `ps_hook` (`name`, `title`, `description`) VALUES ('nameOfHook', 'The name of your hook', 'This is a custom hook!');

...but PrestaShop enables you to do it the easy way:

Code Block
$this->registerHook('NameOfHook');

If the hook "NameOfHook" doesn't exist, PrestaShop will create it for you. No need to do the SQL query anymore.