Une fois le fichier de configuration écrit, vous pouvez accéder aux bases de données.

La première chose à faire est de récupérer un objet jDbConnection :

  $cnx = jDb::getConnection();

La méthode getConnection() permet de récupérer un objet de type jDbConnection (ou jDbPDOConnection héritant de PDO, si vous utilisez PDO, ils ont toutefois la même API). Cette méthode accepte un paramètre facultatif : le nom du profil à utiliser. s'il n'est pas indiqué, celui déclaré par défaut sera utilisé.

Pour construire les requêtes, vous avez une méthode importante à connaître : quote(), qui permet d'échapper certains caractères dans les valeurs que vous voulez insérer dans vos requêtes. Elle évite dans une certaine mesure les problèmes comme l'injection SQL. Un autre ami de quote() est quote2() utilisé sur les colonnes binaires et s'utilise de la même façon que quote()

  $sql = "INSERT INTO users (nom,prenom) VALUES";
  $sql .=" (". $cnx->quote("de l'ombre") .",".$cnx->quote('robert').")";

Notez que la méthode quote() encadre la valeur avec des quotes.

Pour exécuter des requêtes, il y a principalement deux méthodes, exec et query.

exec ¶

  $cnx = jDb::getConnection();

  $cnx->exec("INSERT INTO users (nom,prenom) VALUES('dupont','toto')");

query ¶

  $cnx = jDb::getConnection();

  $rs = $cnx->query('SELECT nom, prenom FROM users');
  $result='';
  while($record = $rs->fetch()){
     $result.='nom = '.$record->nom.' prenom='.$record->prenom."\n";
  } 

limitQuery ¶

  $cnx = jDb::getConnection();

  $rs = $cnx->limitQuery('SELECT nom, prenom FROM users', 5,10);
  $result='';
  while($record = $rs->fetch()){
     $result.='nom = '.$record->nom.' prenom='.$record->prenom."\n";
  }

jDbResultSet est l'objet que vous récupérez après avoir fait un SELECT (query ou limitQuery).

Sa méthode fetch() vous permet de récupérer un à un les enregistrements. À noter que jDbResultSet renvoie toujours un enregistrement sous forme d'objet.

Sa méthode fetchAll() permet de récupérer tout d'un coup dans un tableau PHP.

jDbResultSet implémente l'interface Iterator. De ce fait, vous pouvez utiliser cet objet dans certaines boucles, comme les foreach :

  $cnx = jDb::getConnection();

  $rs = $cnx->query('SELECT nom, prenom FROM users');
  $result='';
  foreach( $rs as $record){
     $result.='nom = '.$record->nom.' prenom='.$record->prenom."\n";
  } 

Les objets contenant les enregistrements sont des objets "anonymes" (ils n'ont pas de classe précise). Si vous voulez que ce soient des objets d'une certaine classe, vous devez l'indiquer via setFetchMode :

  class User {
    ...
  }

  $cnx = jDb::getConnection();

  $rs = $cnx->query('SELECT nom, prenom FROM users');
  $rs->setFetchMode($rs->FETCH_CLASS , 'User');
  $result='';
  foreach( $rs as $record){
     // $record est ici un objet de type User
     $result.='nom = '.$record->nom.' prenom='.$record->prenom."\n";
  } 

Pour le reste des méthodes, voyez la documentation de référence.

Utilisation dans un template ¶

  $cnx = jDb::getConnection();

  $rs = $cnx->query('SELECT nom, prenom FROM users');

  $template->assign('resultats', $rs);

  <table>
    <tr> <th>nom</th> <th>prenom</th></tr>
  {foreach $resultats as $user}
    <tr> 
       <td>{$user->nom|escxml}</td>
       <td>{$user->prenom|escxml}</td>
    </tr>
  {/foreach}
   </table>

jDb permet de faire des transactions. Bien sûr, il faut que le driver utilisé supporte les transactions.

Pour marquer le début d'une transaction, vous appellerez la méthode beginTransaction (). Ensuite vous lancerez les requêtes, Puis après avoir fait vos requêtes, vous pourrez valider la transaction en appelant la méthode commit(). Pour annuler une transaction, il suffit d'appeler rollback().

   $cnx = jDb::getConnection();

   $cnx->beginTransaction();

   $cnx->exec(...);
   $cnx->query(...);
   //....
   
   if($ok)
     $cnx->commit();
   else
     $cnx->rollback();