Raccourcis : Contenu - rubriques - sous rubriques
EN FR

jDb, la couche d'abstraction d'accès aux bases de données, a un système de plugin, ou "drivers". Un driver permet d'accéder à un type de base de données spécifique.

Activation

Pour savoir comment activer un driver pour jDb, voyez le chapitre sur jDb.

Création d'un driver

Un driver pour jDb est constitué de plusieurs classes :

  • une classe pour la connexion à la base de données et l'exécution des requêtes, héritant de jDbConnection
  • une classe pour récupérer les résultats, héritant de jDbResultSet
  • des classes pour interroger et modifier le schéma d'une base de donnée. Elles héritent de jDbSchema et jDbTable.
  • une classe utilitaire héritant de jDbTools, permettant de faire les conversions de type SQL en type unifié jDb, d'exécuter des scripts SQL..

Fichiers et nommages

Un driver possède un nom identifiant. Prenons le nom "exemple" pour la suite.

Les fichiers du driver doivent se trouver dans un répertoire db/exemple/ dans un dépôt de plugins.

Les noms des fichiers doivent suivre ce nommage :

  • exemple.dbconnection.php pour la classe de connexion
  • exemple.dbresultset.php pour la classe de resultset
  • exemple.dbschema.php pour les classes de manipulation de schemas
  • exemple.dbtools.php pour la classe utilitaire

Et dans chacun de ces fichiers, les classes doivent respectivement avoir le nommage suivant :

  • exempleDbConnection
  • exempleDbResultSet
  • exempleDbSchema et exempleTableSchema
  • exempleDbTools

Classe de connexion

Elle doit hériter de jDbConnection qui contient quelques méthodes abstraites qu'il faut définir. Son rôle est de se connecter/déconnecter à la base de donnée. Elle est chargée aussi d'initier les transactions et de les confirmer ou annuler. Enfin, elle exécute ou prépare les requêtes, en renvoyant un objet résultat.

Pour ce faire, elle doit redéfinir les méthodes suivantes :

  • le constructeur s'il y a besoin de faire des choses à l'instanciation du driver. Typiquement, vérifier que les fonctions PHP nécessaires sont bien là.
  • _connect() et _disconnect(), pour la connexion et la déconnexion à la base de données
  • _quote, pour échapper une chaîne de caractère avant que celle-ci soit utilisée dans une requête
  • _doQuery et _doLimitQuery, pour lancer des requêtes qui ramènent des enregistrements (SELECT ou procédures stockées). Elles doivent renvoyer un objet exempleDbResultSet ou false si la requête a échoué
  • _doExec, pour lancer des requêtes ne renvoyant pas d'enregistrements (UPDATE, DELETE, INSERT...). Doit renvoyer le nombre d'enregistrements affectés, ou false si la requête a échoué
  • la méthode prepare(), pour préparer les requêtes.
  • beginTransaction(), commit(), rollback(), pour les transactions
  • errorInfo() et errorCode() renvoyant l'intitulé et le code de la dernière erreur
  • lastInsertId(), permettant de récupérer la dernière valeur du dernier id autoincrémenté généré.
  • _autoCommitNotify()

Si le driver ne prend pas en charge certaines fonctionnalités, il doit générer une exception.

Voir la référence de jDbConnection pour plus de détails.

Classe de résultat

Elle doit hériter de jDbResultSet qui contient quelques méthodes abstraites qu'il faut définir. Un objet de cette classe est normalement renvoyé par les méthodes prepare, _doQuery, _doLimitQuery et prepare() de la classe exempleDbConnection.

Vous devez notament redéfinir les méthodes suivantes :

  • _fetch(), qui doit récupérer l'enregistrement suivant dans la liste des résultats. Elle doit tenir compte de la propriété _fetchMode. Dans la propriété _idResult, vous trouverez l'identifiant de la ressource liée aux résultats.
  • _free(), pour libérer la ressource liée aux résultats (_idResult)
  • _rewind(), pour revenir au début des résultats
  • rowCount, pour retourner le nombre de résultats
  • bindColumn, bindParam, bindValue, columnCount et execute pour les requêtes préparées.

Voir la référence de jDbResultSet pour plus de détails.

Classe pour le schema

Une classe héritant de jDbSchema doit permettre de récupérer la liste des tables et leurs propriétés, champs... Voir l'API de jDbSchema.

Classe utilitaire

Elle doit hériter de jDbTools. Cette classe permet de récupérer des informations sur la base de donnée, sur une table etc. Utilisée notamment par les scripts jelix-scripts.

Vous redéfinirez en particulier les méthodes et propriétés suivantes :

  • $typesInfo, un tableau contenant la correspondance entre les types sql et les types unifiés de jDb.
  • execSQLScript() si vous voulez redéfinir la manière dont est parsé et exécuté un ensemble de requêtes SQL présentes dans un script.

Voir la référence de jDbTools pour plus de détails.

Exemples

Voir les drivers pour mysql, postgresql etc dans le répertoire lib/jelix/plugins/db/.