Sommaire :

• Présentation d'EasySQL
• (en cours de lecture) Comment utiliser EasySQL
• Documentation d'EasySQL

Deuxième partie de la série d'article dédiés à EasySQL.

Cette fois, nous allons voir comment utiliser le module sur votre site à travers quelques exemples plus ou moins concrets.

Téléchargement

Première étape, télécharger la classe EasySQL.
Le premier fichier (EasySQL.php) contient la classe en elle-même. C'est lui qu'il faudra inclure dans vos scripts.
Le second fichier (EasySQLHelper.php) contient les éléments de représentation HTML : par exemple, il indique comment faire un formulaire. Normalement, vous n'avez pas à vous en servir.
Le troisième fichier (EasySQLCheckCompat.php) est facultatif (mais fortement recommandé) : il permet de tester la compatibilité d'une table avec EasySQL en affichant toutes les informations importantes. Vous pouvez ne l'inclure qu'au début, effectuer le test, puis le supprimer.

Prêts ? En route !

⇒ Téléchargement de la classe

Utilisation

Bon, ça peut paraitre évident, mais il faut uploader les trois fichiers après les avoir extraits.

Ensuite, il faut spécifier une constante qui définira à quelles tables EasySQL aura accès : EASYSQL_PREFIXE.
Enfin, inclure la classe EasySQL.php :

 
//Le préfixe des tables.
//Toutes les tables commençant par 'Blog_' seront manipulables par EasySQL.
define('EASYSQL_PREFIXE','Blog_');
 
include('chemin/vers/EasySQL.php');
 

La première fois

Pour la première utilisation, il peut être intéressant d'utiliser la fonction EasySQL::checkCompatibility(). Cette fonction prend en paramètre un nom de table, et teste une bonne partie de ce qui pourrait empêcher l'utilisation d'EasySQL. Une liste est renvoyée sur l'écran, si aucun élément n'est indiqué comme FATAL, c'est que la table semble compatible avec EasySQL.

 
define('EASYSQL_PREFIXE','Blog_');
include('chemin/vers/EasySQL.php');
 
EasySQL::checkCompatibility('Articles');
 

Dans notre cas, voici le retour de la fonction :

• Clé étrangère détectée.
  Origine : Articles.Auteur
  Destination : Auteurs.ID
• Cette table semble utilisable avec EasySQL.

Autrement dit, la clé étrangère est correcte et fonctionnelle, et le schéma de la table est correct (clés primary, ...) : rien ne s'oppose à l'administration de la table avec le module !

Le reste du temps

Si votre table est compatible, vous pouvez afficher en quelques lignes une interface d'administration fonctionnelle avec la fonction EasySQL::getAdminInterface() qui fait la plupart des opérations pour vous :

 
define('EASYSQL_PREFIXE','Blog_');
include('chemin/vers/EasySQL.php');
 
//Affiche une interface d'administration permettant les opération UPDATE et DELETE.
//Il suffit de rajouter INSERT dans le tableau d'options pour avoir un formulaire d'insertion aussi...
echo EasySQL::getAdminInterface(EASYSQL_WORKTABLE,array('UPDATE','DELETE'));
 

Si vous préférez pouvoir personnaliser un peu, vous pouvez utiliser la version longue :

 
<?php
define('EASYSQL_PREFIXE','Blog_');
include('chemin/vers/EasySQL.php');
 
//Un formulaire a été envoyé pour une insertion
if(isset($_POST['ajout']) && EasySQL::commitInsert($_GET['Table'],$_POST))
  echo 'Enregistré.';
 
//Un formulaire a été envoyé pour une mise à jour
if(isset($_POST['update']) && EasySQL::commitUpdate($_GET['Table'],$_POST))
  echo 'Modifié.';
 
//Un formulaire a été envoyé pour des suppressions.
if(isset($_POST['retrait']))
  echo 'Enregistrements supprimés : ' . EasySQL::commitDelete($_GET['Table'],$_POST);
 
//Un formulaire a été envoyé pour sélectionner un enregistrement à mettre à jour
if(isset($_POST['editValue']))
{
  echo '<h2>Modification de données</h2>';
  EasySQL::getFormUpdate($_GET['Table'],$_POST['editValue'],'update');
}
 
//Afficher le formulaire d'insertion
echo '<h2>Ajout de données</h2>';
EasySQL::getFormInsert($_GET['Table'],'ajout');
 
//Afficher le formulaire de mise à jour
echo '<h2>Édition de données</h2>';
EasySQL::getFormPreUpdate($_GET['Table']);
 
//Afficher le formulaire de suppression
echo '<h2>Suppression de données</h2>';
EasySQL::getFormDelete($_GET['Table'],'retrait');
 

Et voilà pour la base ! Rien de bien compliqué, comme vous voyez.

Un peu plus loin...

On a vu avec la fonction EasySQL::checkCompatibility() qu'une clé étrangère était placée sur la table des articles vers les auteurs. Malheureusement, il s'agit d'un numéro d'ID peu explicite pour l'utilisateur !
EasySQL permet justement de spécifier des étiquettes de clés étrangères : à chaque fois qu'une colonne étrangère doit être affichée, son contenu est remplacé par l'étiquette spécifiée.

Ce n'est pas clair ? Voici le formulaire par défaut :

Déroulez le champ Auteur : comment savoir qui est l'utilisateur n°2 ? Avec une étiquette de clé étrangère ! On va indiquer à EasySQL que la colonne lisible pour un humain est Auteurs.Auteur à l'aide de la fonction EasySQL::setMeta() :

 
define('EASYSQL_PREFIXE','Blog_');
include('chemin/vers/EasySQL.php');
 
//Utiliser une étiquette de clé étrangère pour la table Articles : la colonne IDAuteur (un entier) doit être remplacé lors des affichages par le nom de l'auteur dans la table Auteurs.
EasySQL::setMeta('FKCAPTION',array('Articles'=>array('IDAuteur'=>'Auteurs.Auteur')));
 
//Afficher une interface d'administration complète, dans laquelle :
// * Pour les INSERT, le champ de sélection d'un auteur sera une liste déroulante avec le nom des auteurs (plus explicites que l'ID !)
// * Pour les UPDATE et DELETE, le tableau récapitulatif affichera le nom et pas le numéro.
echo EasySQL::getAdminInterface(EASYSQL_WORKTABLE,array('INSERT','UPDATE','DELETE'));
 

Et voici le nouveau formulaire d'insertion (notez que seul l'affichage change, les valeurs derrière sont automatiquement gérées) :

On entre maintenant dans les cas plus complexes, lecture facultative ;)

Encore plus loin !

Progressons dans la complexité et examinons le cas suivant :

• La première colonne de la table Articles ne se nomme pas ID, mais IDArticle (vous aurez une erreur "FATAL" si vous lancez EasySQL::checkCompatibility()) : il va falloir définir la constante EASYSQL_ID, qui était à "ID" par défaut, pour indiquer le changement.
• Vous avez une colonne qui s'appelle Nb.Vues qui contient le nombre de vues de l'article, et qui est automatiquement détectée (de façon incorrecte) comme une clé étrangère vers la table NB, colonne Vues : il va falloir bloquer ce comportement en désactivant la clé étrangère implicite automatique.
• Vous avez une colonne Categorie, clé étrangère vers la table Categories, mais non signalée comme clé étrangère pour des raisons qui ne regardent que vous (par exemple, table en MyIsam) : il va falloir indiquer manuellement qu'il s'agit d'une clé étrangère. Notez que vous pouvez aussi renommer la colonne, par exemple en Categorie.ID, pour rendre la référence implicite.

Voici le code qui solutionne ces trois problèmes :

 
define('EASYSQL_PREFIXE','Blog_');
define('EASYSQL_ID','IDArticle');//PROBLÈME #1 : réglé.
include('chemin/vers/EasySQL.php');
 
//Cf. exemple précédent
EasySQL::setMeta('FKCAPTION',array('Articles'=>array('Auteur'=>'Auteurs.Auteur','Categorie'=>'Categories.NomCategorie')));
 
//Désactiver la clé étrangère sur la table Articles, colonne Nb.Vues
EasySQL::setMeta('DISABLEFKON',array('Articles'=>array('Nb.Vues'=>true)));//PROBLÈME #2 : réglé.
 
//Signaler la colonne Categorie comme clé étrangère
EasySQL::setMeta('FKON',array('Articles'=>array('Categorie'=>'Categories.ID')));//PROBLÈME #3 : réglé.
 
//Afficher une interface d'administration complète et fonctionnelle
echo EasySQL::getAdminInterface(EASYSQL_WORKTABLE,array('INSERT','UPDATE','DELETE'));
 

Le cas des tables MyISAM

Dans certains cas, vous serez forcés d'avoir des tables en MyISAM, moteur non relationnel.
Il faudra donc signaler manuellement les clés étrangères, soit par nommage implicite des colonnes, soit par l'utilisation de EasySQL::setMeta('FKON').

• Déclaration implicite par le nom des colonnes : cela consiste à donner à votre colonne un nom explicite ; par exemple "Auteur.ID". Malheureusement, MySQL gère bizarrement les colonnes avec des points dedans, et il vaut mieux utiliser un autre symbole, comme le "_". Pensez à signaler ce symbole à EasySQL avec la constante EASYSQL_FOREIGN.
• Déclaration explicite par méta-information : cela consiste à indiquer manuellement quelle colonne fait référence à quoi. Cette solution est plus facile à mettre en œuvre, mais aussi plus difficile à entretenir. Voir l'exemple précédent et l'utilisation de setMeta avec l'option 'FKON'.

Note pour les tables en MyISAM : EasySQL ne gère absolument pas les contraintes, il se contente d'effectuer bêtement les opérations demandées. Autrement dit, si vous supprimez un tuple de la table maître, la table fille ne sera pas affectée, mais les relations seront bancales.

Le prochain article sera consacré à la documentation d'EasySQL.