EasySQL : documentation de la classe

    Details
    Category: Articles du blog

    Sommaire :

    Cet article documente l'utilisation d'EasySQL. Il est préférable d'avoir lu les deux articles précédents qui présentaient EasySQL avec des exemples et des cas concrets.

    Table des matières :

    1. class EasySQL
    2. public static function checkCompatibility($Table,$Verbose=true)
    3. public static function getFormTable($Action='',$Valeur='')
    4. public static function getAdminInterface($Table,array $Options)
    5. public static function getFormInsert($Table,$FormName='',$Action='')
    6. public static function getFormUpdate($Table,$ID,$FormName='',$Action='')
    7. public static function getFormPreUpdate($Table,$OrderBy=null)
    8. public static function getFormDelete($Table,$FormName='',$Action='')
    9. public static function getFormDeleteAndUpdate($Table,$FormName='',$Action='')
    10. public static function commitInsert($Table,array &$_POST,$estSecurise=true)
    11. public static function commitUpdate($Table,array &$_POST,$estSecurise=true)
    12. public static function commitDelete($Table,array &$_POST)
    13. public static function getColumns($Table)
    14. private static function getAll($Table,$OrderBy=null)
    15. public static function SQL($SQL)
    16. public static function Fail($Msg)
    17. public static function setMeta($Name,array $Valeur)
    18. public static function getTableAndField($String)
    19. Constante EASYSQL_PREFIXE
    20. Constante EASYSQL_MAXLENGTH
    21. Constante EASYSQL_FOREIGN
    22. Constante EASYSQL_ID

    class EasySQL

    Description

    EasySQL
    La documentation mise en forme se trouve sur cette page.

    PRÉSENTATION

    Cette classe permet l'administration facile des données d'une table MySQL 5,0 ou supérieur.
    Contrairement à PhpMyAdmin, aucun outil de modification de schéma n'est fourni : EasySQL se focalise uniquement sur le contenu des tables.
    Les trois opérations principales de manipulation sont gérées : insertion, mise à jour, suppression.
    À côté de cela, une gestion avancée des clés étrangères est proposée pour faciliter au maximum la manipulation ; EasySQL est d'ailleurs conçu pour une utilisation avec le moteur relationnel InnoDB.

    SÉCURITÉ

    EasySQL offre un accès complet à toutes les tables portant le préfixe défini dans la constante EASYSQL_PREFIXE.
    Pour un accès complet à la base de données, utilisez donc la commande define('EASYSQL_PREFIXE','')

    POUR COMMENCER

    Avant l'utilisation d'une table avec MySQL, il est recommandé d'appeler la fonction EasySQL : : checkCompatibility() pour vérifier que son utilisation est possible.

    Exemples d'utilisation

    //Cet exemple simule l'administration d'une table d'articles nommée Blog_Articles.
define('EASYSQL_PREFIXE','Blog_');
define('EASYSQL_WORKTABLE','Articles');//Ce define n'est pas obligatoire, il permet juste de ne pas se trimballer une variable $Table dans tout le script
include('chemin/vers/EasySQL.php');
//Tester la compatibilité de la table :
EasySQL::checkCompatibility(EASYSQL_WORKTABLE);
//Afficher l'interface d'adminisatration le plus rapidement possible. Possibilités : insérer une ligne, éditer une ligne (pas de DELETE ici)
echo EasySQL::getAdminInterface(EASYSQL_WORKTABLE,array('INSERT','UPDATE'));

    public static function checkCompatibility($Table,$Verbose=true)

    Description

    Tester la compatibilité de $Table pour son utilisation avec EasySQL.
    Les erreurs fatales sont signalées par le préfixe *FATAL !*.
    Une seule erreur fatale suffit à l'invalidation de la table.
    Les autres lignes peuvent être des informations utiles ou des commentaires pour améliorer l'utilisation de la classe.
    La fonction liste aussi toutes les clés étrangères détectées, que ce soit via information_schema, la syntaxe de la colonne, ou les méta données spécifiées dans le script par EasySQL : : setMeta().

    Paramètres d'appel

    1. $Table : la table à analyser.
    2. $Verbose : si le résultat de l'analyse doit être affiché à l'écran (oui par défaut)

    Valeur de retour

    • le nombre d'erreurs fatales, 0 indiquant la compatibilité (prévue) de la table avec EasySQL.

    public static function getFormTable($Action='',$Valeur='')

    Description

    Afficher dans un combo box la liste des tables modificables par l'utilisateur.
    Le contenu est restreint par EASYSQL_PREFIXE qui empêche l'utilisateur de modifier n'importe quelle table.

    Paramètres d'appel

    1. $Action : la page vers laquelle l'utilisateur doit être redirigé une fois le formulaire validé (action du formulaire)
    2. $Valeur : la table à sélectionner par défaut. Si rien n'est précisé, la première table dans l'ordre alphabétique est sélectionnée.

    public static function getAdminInterface($Table,array $Options)

    Description

    Récupérer d'un seul coup toutes les composantes de l'administration d'une table.
    Permet de réaliser très rapidement une interface propre.

    • NOTE : cette fonction doit être appelée une fois pour afficher les formulaires, et réappellée au chargement de la page pour effectuer les modifications.
    • NOTE : cette fonction ne peut être utilisée qu'UNE SEULE FOIS par page, il n'est pas possible d'afficher l'interface d'administration de plusieurs tables en même temps. Pour cela, il faudra passer par la méthode longue en appelant manuellement EasySQL : : getFormInsert(), EasySQL : : getFormPreUpdate(), EasySQL : : getFormUpdate() et EasySQL : : getFormDelete(), ainsi que les fonctions commit associées.

    Paramètres d'appel

    1. $Table : le nom de la table pour laquelle on souhaite afficher l'interface d'administration.
    2. $Options : les options offertes à l'utilisateur sous forme d'un tableau. Les options valides sont INSERT, UPDATE, DELETE. Les autres valeurs sont ignorées.

    Valeur de retour

    • Renvoie un message si une action a été effectuée sur la table.

    Exemples d'utilisation

    echo EasySQL::getAdminInterface('NomTable',array('UPDATE','DELETE'));

    public static function getFormInsert($Table,$FormName='',$Action='')

    Description

    Récupérer un formulaire permettant l'insertion de données dans la table $Table.
    Les champs du formulaire sont calculés automatiquement en fonction du type de la colonne. En cas de clés étrangères, un combobox est affiché avec la liste des valeurs référencables.

    • NOTE : Les valeurs nulles sont gérables de façon basique.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer l'insertion
    2. $FormName : le nom du formulaire, pour pouvoir le distinguer d'autres formulaires. Si différent de '', un input de type hidden est créé avec le nom du formulaire
    3. $Action : la page vers laquelle l'utilisateur doit être redirigé une fois le formulaire validé (action du formulaire)

    public static function getFormUpdate($Table,$ID,$FormName='',$Action='')

    Description

    Récupérer un formulaire permettant la modification de données dans la table $Table.
    L'enregistrement à modifier est désigné par son identifiant $ID (normalement clé primaire, si plusieurs enregistrements, seul le premier est récupéré et traité)
    Les champs du formulaire sont calculés automatiquement en fonction du type de la colonne. En cas de clés étrangères, un combobox est affiché avec la liste des valeurs référençables.
    Les valeurs nulles sont gérables de façon basique.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer l'insertion
    2. $ID : l'identifiant de l'enregistrement à mettre à jour
    3. $FormName : le nom du formulaire, pour pouvoir le distinguer d'autres formulaires. Si différent de '', un input de type hidden est créé avec le nom du formulaire.
    4. $Action : la page vers laquelle l'utilisateur doit être redirigé une fois le formulaire validé (action du formulaire)

    public static function getFormPreUpdate($Table,$OrderBy=null)

    Description

    Récupérer un tableau permettant de sélectionner un enregistrement à modifier. Fonction de convénience qui devient inadaptée si la table contient trop de lignes.

    • NOTE : L'affichage de chaque colonne est tronqué à EASYSQL_MAXLENGTH caractères pour faciliter la lecture.

    Paramètres d'appel

    1. $Table : la table pour laquelle on doit afficher le tableau de pré-mise à jour
    2. $OrderBy : la clé sur laquelle trier, l'ID décroissant par défaut.

    public static function getFormDelete($Table,$FormName='',$Action='')

    Description

    Récupérer un formulaire permettant la suppression de données dans la table $Table.
    La suppression est immédiate et définitive, à utiliser avec précaution.

    • NOTE : L'affichage de chaque colonne est tronqué à EASYSQL_MAXLENGTH caractères pour faciliter la lecture.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer la suppression
    2. $FormName : le nom du formulaire, pour pouvoir le distinguer d'autres formulaires. Si différent de '', un input de type hidden est créé avec le nom du formulaire.
    3. $Action : la page vers laquelle l'utilisateur doit être redirigé une fois le formulaire validé (action du formulaire)

    public static function getFormDeleteAndUpdate($Table,$FormName='',$Action='')

    Description

    Combine en une seule fonction les possibilités de EasySQL : : getFormDelete() et EasySQL : : getFormPreUpdate() : affiche un seul tableau avec des options pour modifier une ligne ou la supprimer.
    La suppression est immédiate et définitive, à utiliser avec précaution.

    • NOTE : L'affichage de chaque colonne est tronqué à EASYSQL_MAXLENGTH caractères pour faciliter la lecture.
    • NOTE : Les valeurs sont triées par numéro d'ID décroissant.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer la mise à jour / suppression
    2. $FormName : le nom du formulaire, pour pouvoir le distinguer d'autres formulaires. Si différent de '', un input de type hidden est créé avec le nom du formulaire.
    3. $Action : la page vers laquelle l'utilisateur doit être redirigé une fois le formularie validé (action du formulaire)

    public static function commitInsert($Table,array &$_POST,$estSecurise=true)

    Description

    Cette fonction effectue l'insertion à partir des données récupérées sur un formulaire généré avec la méthode EasySQL : : getFormInsert(). Vous pouvez aussi lui passer en paramètre un tableau de votre composition.

    • NOTE : Les valeurs '' spécifiées sur une colonne null correspondent à NULL
    • NOTE : Les valeurs appartenant à des colonnes de type INT (tinyint, bigint, … ) sont automatiquement passées à la fonction intval().
    • NOTE : Les colonnes nommées Password voient leur contenu hashé avec l'algorithme sha1() sauf si elles sont déjà encodées (taille de 40 caractères). Attention, ceci peut amener un bug : les mots de passe de taille 40 caractères ne sont pas hashés.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer l'insertion des données
    2. $_POST : le tableau contenant les données à insérer ; normalement généré par getFormInsert() dans $_POST : mais vous pouvez le créer vous-même si nécessaire.
    3. $estSecurise : : indique si le tableau passé en paramètre a été sécurisé pour l'insertion en BDD. Si false, les données sont modifiées avec mysql_real_escape_string() pour éviter les injections.

    Exemples d'utilisation

    define('EASYSQL_WORKTABLE','MaTable');

//Au premier chargement, $_POST est vide et la condition est fausse.
if(isset($_POST['ajout']) && EasySQL::commitInsert(EASYSQL_WORKTABLE,$_POST))
	echo 'Enregistré.';

//Afficher le formulaire d'insertion :
EasySQL::getFormInsert(EASYSQL_WORKTABLE,'ajout');

    public static function commitUpdate($Table,array &$_POST,$estSecurise=true)

    Description

    Cette fonction effectue la mise à jour d'un tuple à partir des données récupérées sur un formulaire généré avec la méthode EasySQL : : getFormUpdate(). Pour sélectionner un enregistrement à modifier, utilisez EasySQL : : getFormPreUpdate().

    • NOTE : Les valeurs '' spécifiées sur une colonne null correspondent à NULL
    • NOTE : Les valeurs appartenant à des colonnes de type INT (tinyint, bigint, … ) sont automatiquement passées à la fonction intval().
    • NOTE : Les colonnes nommées Password voient leur contenu hashé avec l'algorithme sha1() sauf si elles sont déjà encodées (taille de 40 caractères). Attention, ceci peut amener un bug : les mots de passe de taille 40 caractères ne sont pas hashés.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer la mise à jour des données
    2. $_POST : le tableau contenant les données à modifier ; normalement généré par getFormUpdate() dans $_POST : mais vous pouvez le créer vous-même si nécessaire.
    3. $estSecurise : : indique si le tableau passé en paramètre a été sécurisé pour l'insertion en BDD. Si false, les données sont modifiées pour éviter les injections.

    Exemples d'utilisation

    define('EASYSQL_WORKTABLE','MaTable');
//Dans une application réelle, $IdAModifier serait récupéré avec la fonction getFormPreUpdate().
$IdAModifier = 1;

//Au premier chargement, $_POST est vide et la condition est fausse.
if(isset($_POST['update']) && EasySQL::commitUpdate(EASYSQL_WORKTABLE,$_POST))
	echo 'Modifié.';

Afficher le formulaire de mise à jour :
EasySQL::getFormUpdate(EASYSQL_WORKTABLE,$IdAModifier,'update');

    public static function commitDelete($Table,array &$_POST)

    Description

    Cette fonction effectue la suppression d'un ou plusieurs tuples à partir des données récupérées sur un formulaire généré avec la méthode EasySQL : : getFormDelete(). Vous pouvez aussi construire ce tableau depuis le script si nécessaire.
    Attention, cette fonction supprime sans se poser de questions : une mauvaise utilisation videra la table sans avertissement.
    Pensez aussi aux contraintes de type ON DELETE CASCADE sur vos clés étrangères qui peuvent supprimer plusieurs lignes sur plusieurs tables différentes quand vous pensez n'en détruire qu'une seule.

    Paramètres d'appel

    1. $Table : la table sur laquelle effectuer la suppression des données
    2. $_POST : le tableau contenant les données à modifier ; normalement généré par getFormDelete() dans $_POST : mais vous pouvez le créer vous-même si nécessaire.

    Valeur de retour

    • Le nombre d'enregistrements supprimés.

    Exemples d'utilisation

    if(isset($_POST['retrait']))
	echo 'Enregistrements supprimés : ' . EasySQL::commitDelete(EASYSQL_WORKTABLE,$_POST);
EasySQL::getFormDelete(EASYSQL_WORKTABLE,'retrait');

    public static function getColumns($Table)

    Description

    Renvoie la liste des colonnes de la table $Table passée en paramètre.
    Les résultats de cette fonction sont mis en cache pour la durée d'exécution du script afin de décharger le serveur.
    Le tableau de retour contient pour chaque clé un tableau de type Info Colonnes, soit les informations suivantes (entre parenthèses, un exemple de retour) :

    • Field, le nom du champ (ID)
    • Type, son type (int(20))
    • Collation la collation si type text (latin1_german2_ci)
    • Null, yes or no si NOT NULL (YES)
    • Key, si la clé est primaire / unique / index (PRI ou MUL ou UNI)
    • Default, valeur par défaut du champ (NULL)
    • Extra, les informations supplémentaires (auto_increment)
    • Privileges, les privilèges que l'utilisateur courant a sur la colonne (select, insert, update, references),
    • Comment, le commentaire de la colonne. Si non spécifié, EasySQL émule un commentaire identique au nom de la colonne.
    • [optionnel] FKON, (abréviation de ForeignKeyOn) la clé de jointure de la colonne sous la forme NomTable(EASYSQL_FOREIGN)Colonne, EASYSQL_FOREIGN étant le séparateur utilisé [« . » par défaut] (Articles. ID)
    • [optionnel] FKCAPTION (abréviation de ForeignKeyCaption) l'étiquette « user-friendly » à afficher à l'utilisateur de l'application en lieu et place du FKON. Si non défini (avec la méthode EasySQL : : setMeta()), EasySQL l'émule à la même valeur que FKON. (Articles.Titre)

    Paramètres d'appel

    1. $Table : la table dont on souhaite récupérer les informations de colonnes.

    Valeur de retour

    • Le tableau renvoyé est de la forme NomClé=>array(Infos Colonnes).

    private static function getAll($Table,$OrderBy=null)

    Description

    Fonction permettant de récupérer l'intégralité des données dans la table $Table.
    Cette fonction agit de façon intelligente en transformant les clés étrangères numériques par leur étiquette associée si FKCAPTION a été défini avec la fonction EasySQL : : setMeta().

    Paramètres d'appel

    1. $Table : la table dont on veut récupérer les données
    2. $OrderBy : l'ordre de tri, par défaut la clé primaire décroissante.

    public static function SQL($SQL)

    Description

    Procédure utilisée par toutes les fonctions d'EasySQL pour réaliser une requête au serveur SQL.
    En cas d'erreur, affiche la fonction SQL ayant échouée et la pile d'appel grâce à la fonction EasySQL : : Fail().
    Cette fonction est publique et peut donc être appelée depuis vos scripts.

    Paramètres d'appel

    1. $SQL : requête SQL à exécuter

    public static function Fail($Msg)

    Description

    Fonction arrêtant le script en cas d'erreur fatale ; quelques exemples :

    • Requête SQL incorrecte ;
    • Requête SQL violant une contrainte d'intégrité ;
    • Table inexistante ;
    • Demande de mise à jour d'une table sans spécifier l'ID à modifier ;
    • Définitions de méta paramètres incorrects.

    En plus d'un message d'erreur identifiant le problème, la pile d'appel des fonctions ayant mené au problème sera affichée avec les paramètres d'appels pour chaque fonction. Le script s'arrête automatiquement après.

    • NOTE : EasySQL est conçu pour être utilisé avec des gens fiables. Dans un environnement de production, vous devriez faire en sorte que le résultat de cette fonction s'enregistre dans un fichier de log avant de terminer le script sur une erreur générique.

    Paramètres d'appel

    1. $Msg : le message à afficher

    public static function setMeta($Name,array $Valeur)

    Description

    Permet l'introduction de méta données dans EasySQL.
    L'utilisation principale sera de spécifier des étiquettes de clés étrangères à afficher en lieu et place de la colonne étrangère : plutot que d'afficher un numéro d'identifiant peu lisible, on peut choisir une colonne associée (par exemple, le nom de l'auteur) qui remplacera l'identifiant pour chaque sortie sur l'écran. Voir l'exemple avec 'FKCAPTION'.
    Vous pouvez aussi ajouter des clés étrangères qui n'auraient pas été détectées automatiquement. Voir l'exemple avec 'FKON'.
    Enfin, vous pouvez désactiver (virtuellement) des contraintes. Notez que cela ne modifie pas le schéma de la table, juste le comportement d'EasySQL. Voir l'exemple avec 'DISABLEFKON'.

    Paramètres d'appel

    1. $Name : le nom de la méta instruction à enregistrer. Valeurs supportées : 'FKON', 'DISABLEFKON', et 'FKCAPTION'.
    2. $Valeur : un tableau avec les options. Les clés du tableau sont les tables, les valeurs sont un autre tableau dont les clés sont les colonnes et les valeurs les options.

    Exemples d'utilisation

    //Cette commande indiquera à EasySQL que la colonne Groupe est une clé étrangère liant vers la table Groupes, colonne ID.
EasySQL::setMeta('FKON',array('Joueurs'=>array('Groupe'=>'Groupes.ID')));
//Il est inutile de préciser ces valeurs si la clé étrangère existe réellement dans votre table (avec innoDB et et ADD FOREIGN KEY).
//Il est inutile de préciser ces valeurs si votre colonne respecte la convention NomColonne = NomTableEtrangere . EASYSQL_FOREIGN . NomColonneEtrangere
//Ici, il est donc possible de renommer la colonne Groupes en Groupes_ID (si EASYSQL_FOREIGN est défini comme '_', ce qui n'est pas le cas par défaut) pour éviter l'appel à setMeta().
    //Cette commande désactivera la détection des clés étrangères sur les colonnes Nb_Niveau et Last_Connexion de la table Joueurs (note : cette détection n'aurait lieu que si EASYSQL_FOREIGN était défini sur '_', ce qui n'est pas le comportement par défaut !)
EasySQL::setMeta('DISABLEFKON',array('Articles'=>array('Nb_Vues'=>true,'Last_Connexion'=>true)));
// Cette commande sert principalement si votre nommage des colonnes interfère avec la détection automatique des clés étrangères.
//En cas de conflits avec 'FKON', les valeurs indiquées par 'DISABLEFKON' sont prioritaires.
    //Cette commande indiquera que dans la table Propositions, la colonne AjoutPar est une étiquette de clé étrangère sur la table Auteurs, colonne Auteur. Notez qu'il ne s'agit PAS de la valeur contenue dans la table (il s'agit de FKCAPTION et non FKON) mais de la valeur qui sera affichée à l'utilisateur lors des sorties écrans.
EasySQL::setMeta('FKCAPTION',array('Propositions'=>array('AjoutPar'=>'Auteurs.Auteur'));
//Si AjoutPar était une clé étrangère numérique (probablement sur Auteurs_ID), tous ses affichages à l'écran se feront avec le Auteurs.Auteur correspondant à l'Auteurs.ID.

    public static function getTableAndField($String)

    Description

    Fonction séparant en deux composantes l'identifiant $String fourni : la table et la colonne.
    Si le délimiteur n'est pas trouvé, une erreur fatale est lancée.

    Paramètres d'appel

    1. $String : l'identifiant à découper.

    Valeur de retour

    • Un tableau sous la forme array('Table'=>'NomTable','Cle'=>'NomCle')

    Exemples d'utilisation

    define('EASYSQL_FOREIGN','.');//Normalement effectué dès le début du script, présent pour l'exemple.
print_r(EasySQL::getTableAndField('Auteurs.ID'));
//Renvoie array('Table'=>'Auteurs','Cle'=>'ID').

    Constante EASYSQL_PREFIXE

    Description

    Le préfixe des tables.

    • Défaut : AUCUN, si non spécifié le script s'arrête.

    Permet de limiter les accès d'un utilisateur d'EasySQL aux tables commencant par ce préfixe.

    • NOTE : Pour donner un accès complet à toutes les tables de la base, vous devez spécifier explicitement define(EASYSQL_PREFIXE,'')
    • NOTE : Implicitement, chaque table manipulée par EasySQL se voit ajouter le préfixe EASYSQL_PREFIXE. Pour ajouter une ligne sur la table Blog_Articles, il faudra donc appeler la fonction EasySQL::getFormInsert('Articles'), avec EASYSQL_PREFIXE défini comme 'Blog_'.
    • NOTE : Attention, cette constante n'est pas protégée. C'est à vous de la remplir, ne laissez pas l'utilisateur la manipuler.

    Exemples d'utilisation

    //Définir les autorisations sur toutes les tables commençant par 'Blog_' :
define(EASYSQL_PREFIXE,'Blog_');
include('chemin/vers/EasySQL.php');

//Afficher la liste des tables utilisables avec EasySQL dans une menu déroulant :
//Affichera les tables Blog_Articles, Blog_Auteurs, Blog_Commentaires mais pas AutreTable ou Site_Sessions.
//Dans le menu déroulant, le préfixe sera ôté (transparent pour l'utilisateur) : il verra donc les tables Articles, Auteurs, Commentaires.
EasySQL::getFormTable();
    define(EASYSQL_PREFIXE,'Blog_');
include('chemin/vers/EasySQL.php');

//Afficher une interface d'administration
EasySQL::getAdminInterface('Articles',array('UPDATE','DELETE'));

    Constante EASYSQL_MAXLENGTH

    Description

    La taille maximum (en caractères) à afficher dans les aperçus.

    • Défaut : 200

    Constante EASYSQL_FOREIGN

    Description

    Le caractère qui permet de séparer une clé étrangère de sa table.

    • Défaut : '. '

    Par exemple, un nom de colonne Articles.ID est interprété comme une clé étrangère vers la table Articles, colonne ID.

    • NOTE : Cette constante ne devrait pas être modifiée si vos tables sont en InnoDB, car la détection des clés étrangères est alors automatique.
    • NOTE : Attention, cette constante n'est pas protégée. C'est à vous de la remplir, ne laissez pas l'utilisateur la manipuler.

    Constante EASYSQL_ID

    Description

    Le nom de la première colonne des tables.

    • Défaut : ID

    Malheureusement, EasySQL ne gère pas des noms d'ID différents selon les tables (IDArticles, IDAuteurs) : si c'est le cas dans votre application, il faudra manier les tables une à une en modifiant le define('EASYSQL_ID','IDTable') à chaque fois.

    • NOTE : Attention, cette constante n'est pas protégée. C'est à vous de la remplir, ne laissez pas l'utilisateur la manipuler.