FluxBB propose un ensemble de fonctions pour manipuler la base de données, de manière à éviter tout problème de compatibilité entre les différents SGBD. Ces fonctions sont à utiliser lorsque vous créez une mod pour FluxBB, mais vous pouvez également les utiliser sur votre site.

Nous allons les lister et expliquer brièvement comment les utiliser, et quels sont les paramètres à leur fournir.

Vous souhaitez lire des données de la base de données en utilisant les fonctions de FluxBB mais ne savez pas comment faire ? Il n'y a rien de plus de simple une fois les bases expliquées.

Supposons que nous souhaitons récupérer la liste des membres actuellement en ligne. Pour se faire, nous allons chercher dans la table “online” tous les enregistrements correspondant à des membres connectés, donc dont l'id est différent de “1”.

$result = $db->query('SELECT user_id, ident FROM '.$db->prefix.'online WHERE user_id > 1 ORDER BY ident') or error('Impossible de récupérer la liste des membres connectés', __FILE__, __LINE__, $db->error());

Quelques explications :

• $result : variable dans laquelle sont enregistrés les résultats de la requête
• $db→prefix : variable contenant le préfixe utilisée par FluxBB sur votre installation. Son utilisation permet de rendre les requêtes compatibles avec toutes les installations de FluxBB.

Maintenant que vous avez récupéré l'ensemble des informations dont vous aviez besoin dans la base de données, vous souhaitez les utiliser, pour les afficher par exemple. Il vous faut pour cela parcourir les résultats à l'aide d'une autre fonction FluxBB :

while($cur_user = $db->fetch_assoc($result))
{
    echo '<p>'.$cur_user['user_id'].' : '.$cur_user['ident'].'</p>';
}

La première ligne permet, à chaque itération, de créer un tableau de valeur contenant le résultat courant de la requête. Dans notre cas, nous enregistrons ce tableau dans le tableau PHP $cur_user. Les clés de ce tableau sont les noms des champs spécifiés dans la requête.

$db->add_field($table_name, $field_name, $field_type, $allow_null, $default_value, $after_field, $no_prefix);

Exemple : pour ajouter le champ country à la table flux_users, après le champ location.

$table_name = "users"; // Le préfixe n'est pas spécifié car il s'agit de celui de FluxBB, et il peut changer d'une installation à l'autre.
$field_name = "country"; // Le champ s'appellera "country"
$field_type = "VARCHAR(100)"; // Le champ pourra contenir une chaîne de caractères de 100 caractères au maximum
$allow_null = TRUE; // Le champ acceptera la valeur nulle
$default_value = NULL; // Le champ aura la valeur nulle par défaut
$after_field = "location" // Le champ sera ajouté après le champ location;
$no_prefix = NULL; // Le table utilise le préfixe de FluxBB
$db->add_field($table_name, $field_name, $field_type, $allow_null, $default_value, $after_field, $no_prefix);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si l'action a été réalisée avec succès, FALSE si l'action n'a pas pu être réalisée.

$db->alter_field($table_name, $field_name, $field_type, $allow_null, $default_value, $after_field, $no_prefix);

Exemple : pour modifier le champ country de la table flux_users, afin d'accepter des chaîne de plus de 100 caractères.

$table_name = "users";
$field_name = "country";
$field_type = "VARCHAR(255)";
$allow_null = TRUE;
$default_value = NULL;
$after_field = NULL; // Nous ne voulons pas changer le champ de place dans la table
$no_prefix = NULL;
$db->alter_field($table_name, $field_name, $field_type, $allow_null, $default_value, $after_field, $no_prefix);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si l'action a été réalisée avec succès, FALSE si l'action n'a pas pu être réalisée.

$db->drop_field($table_name, $field_name, $no_prefix);

Exemple : pour supprimer le country de la table fluxbb_users.

$table_name = "users";
$field_name = "country";
$no_prefix = NULL;
$db->drop_field($table_name, $field_name, $no_prefix);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si l'action a été réalisée avec succès, FALSE si l'action n'a pas pu être réalisée.

$db->field_exists($table_name, $field_name, $no_prefix);

Exemple : pour tester l'existence du champ country dans la table fluxbb_users

$db->field_exists("users", "country", NULL);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si le champ existe, FALSE si le champ n'existe pas.

$db->create_table($table_name, $schema, $no_prefix);

Exemple : pour créer la table flux_commentaires contenant les 3 champs suivants :

• id : numérique auto-incrémenté
• user_id : id du membre, champ indexé
• message : texte du commentaire

$table_name = "commentaires";
$schema = array(
	'FIELDS' => array(
			'id'	=> array(
				'datatype'	=> 'SERIAL',
				'allow_null'	=> false
				),
			'user_id' => array(
				'datatype'	=> 'INT(10) UNSIGNED',
				'allow_null'	=> false,
				'default'	=> '0'
				),
			'message' => array(
				'datatype'	=> 'VARCHAR(255)',
				'allow_null'	=> true
				)
			),
	'PRIMARY KEY' => array('id'),
	'INDEXES' => array(
		'user_id_idx'	=> array('user_id')
		)
	);
$no_prefix = NULL;
$db->create_table($table_name, $schema, $no_prefix);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si l'action a été réalisée avec succès, FALSE si l'action n'a pas pu être réalisée.

$db->drop_table($table_name, $no_prefix);

Exemple : pour supprimer la table table_a_supprimer, il faut utiliser la fonction suivante :

$db->drop_table("table_a_supprimer", TRUE);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si l'action a été réalisée avec succès, FALSE si l'action n'a pas pu être réalisée.

$db->truncate_table($table_name, $no_prefix);

Exemple : pour vider la table table_a_vider de tout son contenu, il faut utiliser la fonction suivante :

$db->truncate_table("table_a_vider", TRUE);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si l'action a été réalisée avec succès, FALSE si l'action n'a pas pu être réalisée.

table_exists($table_name, $no_prefix);

Exemple : pour tester l'existence de la table table_a_tester, il faut utiliser la fonction suivante :

table_exists("table_a_vider", TRUE);

Cette fonction peut renvoyer deux valeurs comme résultat : TRUE si la table existe, FALSE si elle n'existe pas.

Les différentes fonctions utilisent un certain nombre de paramètres que nous allons vous détailler.

Ce paramètre vous permet de spécifier après quel champ de la table vous souhaitez ajouter le nouveau champ. Le nouveau champ sera placé en toute fin de table si vous indiquez NULL. Dans le cas de la modification d'un type de champ, la valeur NULL permet de le conserver à la même place dans la table.

Ce paramètre vous permet d'indiquer si le champ que vous créez acceptera les valeurs nulles :

• si le champ acceptera les valeurs nulles, le paramètre doit être à TRUE
• si le champ n'acceptera pas les valeurs nulles, le paramètre doit être à FALSE

Ce paramètre vous permet de spécifier la valeur qui sera utilisée par défaut pour ce champ.

Ce paramètre vous permet d'indiquer le nom du champ sur lequel vous allez travailler.

Ce paramètre vous permet d'indiquer le type du champ (voir la section “Type de champ” un peu plus bas pour plus de détails).

Le paramètre $no_prefix, présent dans l'ensemble des fonctions, vous permet de spécifier si la table sur laquelle vous aller travailler fait partie de FluxBB, ou s'il s'agit d'une table externe, pour votre site par exemple. Il permet à la fonction de savoir s'il faut ajouter le préfixe de FluxBB devant le nom de la table, ou s'il faut le laisser tel que spécifié dans un autre paramètre.

• si la table sur laquelle vous allez travailler utilise le préfixe de FluxBB, le paramètre doit être à TRUE
• si la table sur laquelle vous allez travailler n'utilise pas le préfixe de FluxBB, le paramètre doit être à FALSE

Ce paramètre vous permet de spécifier la structure complète de la table que vous souhaitez créer. Il s'agit d'un tableau contenant plusieurs tableaux. En voici les clés des différents niveaux, et ce qu'ils peuvent contenir :

Pour les différents champs de la table, sous la forme d'un tableau de tableaux. La façon la plus simple d'expliquer son utilisation est l'exemple. Le code suivant explicite la structure d'une table de deux champs : group_id et forum_id :

array(
	'group_id'	=> array(
			'datatype'	=> 'INT(10)',
			'allow_null'	=> false,
			'default'	=> '0'
		),
	'forum_id'	=> array(
			'datatype'	=> 'INT(10)',
			'allow_null'	=> false,
			'default'	=> '0'
		)
	)

Les “sous-tableaux” peuvent avoir les clés suivantes :

• allow_null : autoriser la valeur nulle
• collation : collation du champ
• datatype : type de champ
• default : valeur par défaut

Pour la clé primaire de la table, si elle existe, sous la forme d'un tableau de valeurs. Quelques exemples :

• array('id') : clé primaire simple, sur le champ id
• array('group_id', 'forum_id') : clé primaire multiple, sur les champs group_id et forum_id

Pour les index uniques de la table, s'il en existe, sous la forme d'un tableau de valeur dont la clé est le nom de l'index. Par exemple :

• array('nom_index' ⇒ 'id') : index unique sur le champ id
• array('nom_index' ⇒ array('group_id', 'forum_id')) : index unique sur les champs group_id et forum_id

Le nom final de l'index sera de la forme : “nom de la table” + “nom de l'index”

Pour les index normaux de la table, s'il en existe, sous la forme d'un tableau de valeur dont la clé est le nom de l'index. Par exemple :

• array('nom_index' ⇒ 'id') : index sur le champ id
• array('nom_index' ⇒ array('group_id', 'forum_id')) : index sur les champs group_id et forum_id

Le nom final de l'index sera de la forme : “nom de la table” + “nom de l'index”

Pour le moteur de base de données à utiliser. S'il n'est pas renseigné, la valeur MyISAM sera utilisée par défaut.

Ce paramètre vous permet d'indiquer le nom de la table sur laquelle vous allez travailler, sans préciser le préfixe de FluxBB. Le fonction l'ajoutera d'elle même en fonction du paramètre $no_prefix.