Ce sujet décrit l'utilisation du DBAL (DataBase Abstraction Layer) de phpBB3 Le DBAL est le module d'abstraction qui permet de ne pas se préoccuper du type de la base lors de l'envoi de requètes.
Pour utiliser les fonction de la classe DBAL, vous devez appeler une instance de la classe DBAL et créer une connexion. Ensuite, vous devez inclure le bon pilote pour le SGBD utilisé depuis /includes/db/
Important: la variable $dbms doit être initialisée avec le nom du pilote du SGBD utilisé. Cette variable est requise dans /includes/db/dbal.php pour initialiser $sqldb_
Note: Si vous utilisez la variable $dbms depuis config.php, vous pouvez utiliser $sql_db pour créer l'instance de la classe.
Note: Si vous utilisez le fichier common.php le DBAL est automatiquement initialisé et une instance est créée, donc vous n'avez pas besoin de faire ceci. L'objet créé est appelé $db.
Après avoir inclus tous les fichiers requis, vous pouvez créer la nouvelle connexion. Tout d'abord vous devez créer une instance de la classe en créant un objet ($db = new $sql_db();. Ensuite, vous pouvez l'initialiser avec $sql_db, ou avec dbal_DRIVER_NAME. Ensuite, vous pourrez appeler sql_connect pour créer la connexion.
Dans cet exemple, le fichier config.php n'est pas utilisé, toutes les données sont données directement à sql_connect pour illustrer le fonctionnement.
<?php
/**
*
* @package phpBB3
* @version $Id: v3_dbal.xml 44 2007-07-25 11:06:55Z smithy_dll $
* @copyright (c) 2005 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
$dbms = 'mysql';
include($phpbb_root_path . 'includes/db/' . $dbms . '.' . $phpEx);
$db = new $sql_db();
// Nous utilisons bertie et bertiezilla comme exemple d'utilisateur et mot de passe. Vous devez les remplacer par les vôtres ;D
$db->sql_connect('localhost', 'bertie', 'bertiezilla', 'phpbb', '', false, false);
?>
Premier paramètre, hôte : L'hôte qui héberge la base de donnée. Si vous utilisez le fichier config.php vous devriez utiliser $dbhost à la place.
Second paramètre, utilisateur de la base : L'utilisateur utilisé pour se connecter à la base. Si vous utilisez le fichier config.php vous devriez utiliser $dbuser à la place.
Troisième paramètre, mot de passe de la base : Le mot de passe utilisé pour se connecter à la base. Si vous utilisez le fichier config.php vous devriez utiliser $dbpasswd à la place.
Quatrième paramètre, nom de la base : Le nom de la base de la base de donnée où sont situées les tables de phpBB. Si vous utilisez le fichier config.php vous devriez utiliser $dbname à la place.
Cinquième paramètre, port de la base : Le port utilisé par le serveur qui héberge la base de donnée. Laissez vide pour utiliser le port par défaut. Si vous utilisez le fichier config.php vous devriez utiliser $dbport à la place.
Sixième paramètre, persistance de la connexion : Utiliser une connexion persistante. Valeur facultative, fausse par défaut.
Septième paramètre, nouvelle connexion : Forcer l'utilisation d'une nouvelle connexion. Valeur facultative, fausse par défaut.
Ce second exemple utilise le fichier config.php pour envoyer les bons paramètres à la fonction sql_connect. Les paramètres sont les mêmes que ceux décris ci dessus. L'utilisation du unset($dbpasswd); nous assure que cette variable ne risque pas d'être volée plus loin dans le script.
<?php
/**
*
* @package phpBB3
* @version $Id: v3_dbal.xml 44 2007-07-25 11:06:55Z smithy_dll $
* @copyright (c) 2005 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'config.' . $phpEx);
include($phpbb_root_path . 'includes/db/' . $dbms . '.' . $phpEx);
$db = new $sql_db();
$db->sql_connect($dbhost, $dbuser, $dbpasswd, $dbname, $dbport, false, false);
// We do not need this any longer, unset for safety purposes
unset($dbpasswd);
?>
Pour sélectionner des donnée depuis la base de données, la fonction sql_query() est suffisante. Si vous voulez utiliser une variable dans votre requête, vous devrez utiliser (si c'est un entier) $db->sql_escape() pour vous assurer que les données sont sûres.
Dans cet exemple il y a deux variables, un entier et une chaîne avec un apostrophe dans la chaîne. La variable $integer est castée pour s'assurer que il s'agit bien d'un entier. La chaîne est passée à $db->sql_escape() pour s'assurer que la chaîne est correctement échappée. La fonction $db->escape est différente pour chaque SGBD et écris spécialement pour celui utilisé, pour vous assurer que tous les caractères sont bien échappés. $db->sql_query retourne un identifiant de résultat.
<?php
/**
*
* @package phpBB3
* @version $Id: v3_dbal.xml 44 2007-07-25 11:06:55Z smithy_dll $
* @copyright (c) 2005 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'common.' . $phpEx);
$integer = 0;
$data = "This is ' some data";
$sql = 'SELECT *
FROM ' . POSTS_TABLE . '
WHERE post_id = ' . (int) $integer . "
AND post_text = '" . $db->sql_escape($data) . "'";
$result = $db->sql_query($sql);
?>
Note : Si vous souhaitez utilisez la fonction native de cache, vous devrez utiliser le second paramètre de $db->sql_query. Il s'agit du temps (en secondes) pour que les données de la requête restent dans le cache. Vous ne pouvez l'utiliser uniquement pour les requêtes SELECT.
Note: Si vous souhaitez utiliser LIMIT dans une requête, vous devriez utiliser $db->sql_query_limit à la place de $db->sql_query. Voir l'exemple.
<?php
/**
*
* @package phpBB3
* @version $Id: v3_dbal.xml 44 2007-07-25 11:06:55Z smithy_dll $
* @copyright (c) 2005 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'common.' . $phpEx);
$integer = 0;
$data = "This is ' some data";
// Variable for query_limit
// Start with item 10
$start = 10;
// Select 5 rows
$number = 5
$sql = 'SELECT *
FROM ' . POSTS_TABLE . '
WHERE post_id = ' . (int) $integer . "
AND post_text = '" . $db->sql_escape($data) . "'";
$result = $db->sql_query_limit($sql, $number, $start);
?>
Note : Pour utiliser le cache avec $db->sqlquerylimit, vous devez spécifier la durée de vie du cache en quatrième paramètre.
PhpBB 3 offre de puissantes fonctions pour assembler les requêtes de manière fiable, réutilisable et multi-SGBD. Cette section vous introduit l'une des plus importantes.
sql_build_arrayLa fonction $db->sql_build_array peut facilement créer des requêtes UPDATE, INSERT, MULTIINSERT, INSERTSELECT et SELECT à partir d'un tableau.
<?php
/**
*
* @package phpBB3
* @version $Id: v3_dbal.xml 44 2007-07-25 11:06:55Z smithy_dll $
* @copyright (c) 2005 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'common.' . $phpEx);
//Array with the data to insert
$data = array(
'username' => 'Bertie',
'email' => 'bertie@bertie.com',
);
// First doing a select with this data.
// Note: By using the SELECT type, it uses always AND in the query.
$sql = 'SELECT user_password
FROM ' . USERS_TABLE . '
WHERE ' . $db->sql_build_array('SELECT', $data);
$result = $db->sql_query($sql);
// And doing an update query: (Using the same data as for SELECT)
$sql = 'UPDATE ' . USERS_TABLE . ' SET ' . $db->sql_build_array('UPDATE', $data);
$db->sql_query($sql);
// And as last, a insert query
$sql = 'INSERT INTO ' . USERS_TABLE . ' ' . $db->sql_build_array('INSERT', $data);
$db->sql_query($sql);
?>
Important : Veuillez à n'utiliser MULTIINSERT qu'avec $db->sql_multi_insert(). Pour plus d'informations, voir la partie à propos de @@sql_multi_insert@. _
Le premier paramètre pour sql_build_array est le type de requête (UPDATE, INSERT, MULTIINSERT, INSERTSELECT or SELECT). Le second paramètre est un tableau associatif avec la liste des éléments nécessaires à la requête. Les clefs du tableau sont les noms des champs, la valeur associée est la value pour le champ.
Important : Si vous désirez utiliser une valeur entière, vous devrez au préalabler la caster en une valeur entière explicite.
Important : Lorsque vous utilisez $db->sql_build_array() pour les requêtes SELECT, veuillez noter que ces dernières n'utiliseront que des AND dans la clause WHERE de la requête, donc la requête de l'exemple ressemblera à ça: SELECT user_password FROM phpbb_users WHERE username = 'Bertie' AND email = 'bertie@bertie.com'
Note : Si vous voulez créer des requêtes SELECT avec JOINS ou SELECT DISTINCT, vous devriez utiliser $db->sql_build_query() à la place.