Raccourcis : Contenu - rubriques - sous rubriques
EN FR
Guide du développeur
Jelix 1.2.13

Section: drivers pour jDb

« drivers pour jAuth ^ Développer et utiliser des plugins plugins de templates »
Changer de langue : EN

− Table des matières

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 trois 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..
  • une classe pour construire des requêtes, pour jDao, héritant de jDaoGenerator.

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
  • exemple.daobuilder.php pour la classe pou jdao

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

  • exempleDbConnection
  • exempleDbResultSet
  • exempleDbSchema et exempleTableSchema
  • exempleDbTools
  • exempleDaoBuilder

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 et _doLimitQuery 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 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.

Classe génératrice de requêtes SQL

Cette classe est utilisée par jDao. En effet, jDao génère des classes PHP avec des requêtes "en dur" dans leurs méthodes. Ces requêtes pouvant être différentes d'une base à une autre (au niveau de la syntaxe), il est possible de les définir dans le driver.

La classe doit hériter de jDaoGenerator et redéfinir une ou plusieurs de ces méthodes :

  • genSelectPattern()
  • _encloseName()
  • genUpdateAutoIncrementPK()
  • $propertiesListForInsert
  • $trueValue, $falseValue
  • _getAutoIncrementPKField()

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

Exemples

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

« drivers pour jAuth ^ Développer et utiliser des plugins plugins de templates »
Changer de langue : EN
Ce manuel est distribué selon les termes de la licence Creative Commons by-nc-sa 3.0. Vous pouvez donc reproduire, modifier, distribuer et communiquer ce manuel au public en respectant les conditions suivantes : Paternité, Pas d'Utilisation Commerciale, Partage des Conditions Initiales à l'Identique.