Table of content

...

DB class best practices

Most of the time, creating a module or overriding PrestaShop means using or inserting data in the database. Knowing how to properly use the DB core class is therefore mandatory for developers. Besides providing you with an abstraction for other potential database system, the DB class offers several tools to make your life easier.

...

• The Db class, which can found in the /classes/db/Db.php, and is abstracted.
• A subclass which extends the Db class. Currently, three class abstractions are supported as subclasses: MySQL, MySQLi and PDO.
  PDF PDO is used by default; however, if the PDF PDO extension is not installed on the server, the MySQLi extension is used instead. And if MySQLi is not installed either, then MySQL is used.

DB is a pseudo-singleton, as it can still be manually instantiated, because its constructor is public. However, within PrestaShop, it is recommended to instantiate it this way:

$db = Db::getInstance();

In some cases, you might encounter this alternative:

$db = Db::getInstance(_PS_USE_SQL_SLAVE_);

...

Fictitious example:

$target = Tools::getValue('id');
$name = Tools::getValue('name');
Db::getInstance()->insert('target_table', array(
	'id_target'	=> (int)$target,
	'name'		=> pSQL($name),
));

Triggering this code generates the following SQL query:

INSERT INTO `prefix_target_table` (`id_target`, `name`) VALUES (10, 'myName')

...

The $limit parameter enables you to limit the number of records to that you wish to delete. The other advantage of this method is that it will be used by PrestaShop's SQL queries cache system, and will therefore delete the affected queries in cache, unles the $use_cache is false.

Example:

Db::getInstance()->delete(‘target'target_table’table', ‘myField'myField < 15’15', 3);

...will generate the following query:

DELETE FROM `prefix_target_table` WHERE myField < 15 LIMIT 3

...

Method signature: execute($sql, $use_cache = 1).

This method executes the given SQL query. Cette méthode exécute la requête SQL donnée. Elle n’est à utiliser que pour les requêtes en écriture It should only be used for 'write' queries (INSERT, UPDATE, DELETE, TRUNCATE…) car elle supprime de plus le cache de requêtes (sauf si l’argument $use_cache vaut TRUNCATE, etc.), because it also deletes the query cache (unles $use_cache is set to false).

Exemple Example:

$sql = ‘DELETE'DELETE FROM ‘'._DB_PREFIX_.’product'product WHERE active = 0’0';
if (!Db::getInstance()->execute($sql))
	die(‘Erreur'Erreur etc.)’';

La méthode query($sql,)

Toutes les méthodes de la classe exécutant des requêtes SQL utilisent cette méthode de plus bas niveau. Elle fait la même chose que la méthode execute() à deux exceptions prêt :

1. Aucune gestion du cache dans cette méthode
2. Elle ne retournera non pas un boolean mais une ressource que vous pourrez exploiter avec d’autres méthodes comme nextRow()

...

query()

Method signature: query($sql).

All the method of the DB classes that make SQL query use the query() as the common, low-level method. It does the same as the execute() method, with two exceptions:

• No cache control management.
• Will not return a boolean; instead returns a database resource that you can use with other DB class methods, such as nextRow().

executeS()

Method signature: executeS($sql, $array = true, $use_cache = 1)

...

Cette méthode exécute la requête SQL donnée et charge l’ensemble des résultats qu’elle retourne dans un tableau multidimensionnel. Elle n’est à utiliser que pour les requêtes en lecture .

This method executes a given SQL query, and makes that whole resulting data available through a multidimensional array. It should only be used for 'read' queries (SELECT, SHOW, etc.). Les résultats de cette requête seront mis en cache, sauf si l’argument The query's results are cached, unless the $use_cache vaut parameter is set to false. Le The second argument $array est déprécié et ne doit plus être utilisé, laissez-le à parameter, $array(), is deprecated and should not be used, leave it as true.

Exemple Example:

$sql = ‘SELECT'SELECT * FROM ‘'._DB_PREFIX_.’shop’'shop';
if ($results = Db::getInstance()->ExecuteS($sql))
    	foreach ($results as $row)
        		echo $row[‘id'id_shop’shop'].’' :: ‘'.$row[‘name’'name'].’<br'<br />’>';

...

getRow()

Method signature: getRow($sql, $use_cache = 1)

...

Cette méthode exécute la requête SQL donnée et récupère la première ligne de résultats. Elle n’est à utiliser que pour les requêtes en lecture .

This method executes a given SQL query and retrieves the first row of results. It should only be used with 'read' queries (SELECT, SHOW, etc.). Les résultats de cette requête seront mis en cache, sauf si l’argument The query's results are cached, unless the $use_cache vaut parameter is set to false.

Attention : cette méthode ajoute automatiquement une clause LIMIT à la requête. Veillez à ne pas en ajouter une vous-même manuellement.

...

Example:

$sql = ‘SELECT'SELECT * FROM ‘'._DB_PREFIX_.’shop
    'shop
	WHERE id_shop = 42’;
if ($row = Db::getInstance()->getRow($sql))
    	echo $row[‘id'id_shop’shop'].’' :: ‘'.$row[‘name’'name'];

...

getValue()

Method signature: getValue($sql, $use_cache = 1)

...

Cette méthode exécute la requête SQL donnée et récupère uniquement le premier résultat de la première ligne. Elle n’est à utiliser que pour les requêtes en lecture .

This method executes a given SQL query and retrieves the first value of the first row of results. It should only be used with 'read' queries (SELECT, SHOW, etc.). Les résultats de cette requête seront mis en cache, sauf si l’argument The query's results are cached, unless the $use_cache vaut parameter is set to false.

...

Example:

$sql = ‘SELECT'SELECT COUNT(*) FROM ‘'._DB_PREFIX_.’shop’'shop';
$totalShop = Db::getInstance()->getValue($sql);

La méthode NumRows()

Cette méthode met en cache et retourne le nombre de résultats de la dernière requête SQL.
Attention : cette méthode n’est pas dépréciée mais il est fortement déconseillé de l’utiliser pour des raisons de bonnes pratiques. En effet, il vaut mieux récupérer le nombre de résultats via une requête de type SELECT COUNT au préalable.

...

NumRows()

This method caches and returns the number of results from the most recent SQL query;

A few other methods

• Insert_ID(): retourne l’identifiant créé de la dernière requête INSERT exécutéereturns the ID created during the latest INSERT query.
• Affected_Rows(): retourne le nombre de lignes concernées par la dernière requête UPDATE ou DELETE exécutéereturns the number of lines impacted by the latest UPDATE or DELETE query.
• getMsgError(): retourne le dernier message d’erreur si une requête a échouéreturns the latest error message, if the query has failed.
• getNumberError(): retourne le dernier numéro d’erreur si une requête a échoué

...

• returns the latest error number, if the query has failed.

Changes between PrestaShop 1.4 and 1.5

• Les méthodes The autoExecute() et and autoExecuteWithNullValues() sont dépréciées au profit de are deprecated. You should replace them with insert() et and update()Le préfixe des tables n’est plus obligatoire pour la méthode , respectively.
• The table prefix is no longer mandatory for the delete() method.
• La méthode The execute() ne retourne plus une ressource mais un boolean, utilisez query() pour obtenir une ressourceSupport de PDO et MySQLi method does not return a SQL resource but a boolean value. Use query() to get a resource.
• PDO and MySQLi support.