aDB PDO like database abstraction: Database abstraction layer similar to PDO

aDB PACKAGE 
@version 20070524

Ce package est un package d'abstraction de base de données.

Il se compose des classes suivantes :

/**
* gestion des exceptions
*/
class aDBException extends Exception
class aDBExceptionIllegalClass extends aDBException 
class aDBExceptionTypesError extends aDBException
class aDBExceptionInvalidClassCalls extends aDBException
class aDBExceptionDbConnectorErrors extends aDBException

/**
* Itérateur
*/
class sqlIterator implements Iterator, SeekableIterator, Countable

/**
* Usinage
*/
class aDBFactory

/**
* DB abstraction
*/
abstract class aDB
class mssql extends aDB
class mysql extends aDB

Ce package permet de passer facilement d'un type de base de données à un autre, d'une connexion à une autre, en gardant le minimum
d'instances possible, grâce à l'usinage. Il permet une gestion des erreurs poussée via les différents types d'exceptions. Les méthodes 
propres à la couche d'abstraction permettent, outre les fonctionnalités habituelles, de gérer les transactions, la préparation 
de requêtes, la personnalisation des jeux de résultat renvoyés etc.

Voir le code pour une documentation des différentes méthodes et propriétés.
Ce document-ci va se contenter d'expliquer comment se servir du package du point de vue utilisateur.
Des exemples poussés se trouvent dans le fichier index.php.

/************
INSTANCIATION

$aDB = aDBFactory::getInstance (string $type, [array $aConfConf, [array $aOptions]]);

Le principe est ici que si une instance de $type a déjà été crée, l'usine va vérifier si il y a une nouvelle configuration de configuration 
$aConfCon. 
Si oui, elle va utiliser l'instance récupérée et la reconnecter en utilisant cette nouvelle configuration.
Sinon, elle ne fait que récupérer l'instance existante (avec donc son ancien lien de connexion).
Ensuite, elle fait de même avec les options $aOptions.
Puis elle retourne l'instance.

Si aucune instance n'est trouvée, elle en crée une et la retourne.

Si aucune classe de type $type n'est trouvée, une exception de type aDBExceptionIllegalClass sera lancée (voir le fichier du
package pour trouver toutes les exceptions et leurs codes, afin de les gérer au mieux).

/**********
UTILISATION

METHODES UTILES :

aDB::connect ($aConConf)
Nécessite un tableau de paramètres pour la connexion, de la form HOST, LOGIN, PWD et en option DB.
Connecte l'objet au serveur de db demandé.
Un lien de connexion est alors stocké au niveau de l'objet.


aDB::select_db ([$sDbName])
Sélectionne la db $sDbName si fournie, à DB de aDB::aConConf sinon.


aDB::query ($sQuery, [$bOverWriteQry = true])
Execute la requête $sQuery.
Si $bOverWriteQry est égal à true, alors la propriété privée aDB::sQuery prend la valeur de $sQuery, sinon non.
Retourne la ressource créée.


aDB::set_limit ([$iOffset = 0, [$iCount = null]])
Initialise une limitation sur les jeux de résultat.
$iOffset est la position de départ dans le jeu de résultat retourné par la requête.
$iCount est le nombre de lignes à retourner.
A noter que ces paramètres sont conserver par la classe, donc pour les remettre à leur valeur par défaut, il faut faire un appel à
cette méthode sans paramètre.
Cette initialisation fonctionnera pour toutes les récupérations de jeux de résultats demandées.


aDB::next_limit ()
Mets à jour la limitation précédemment initialisée dans aDB::set_limit.
Le nombre de lignes à récupérer reste le même.
Mais la position de départ est égale à l'ancienne position de départ + le nombre de lignes.


aDB::fetchColumn ([$iColumn = 0, [$rQry = null, [$bIsSeekable = true]]])
Va chercher la valeur d'une colonne de position $iColumn dans la requête et la renvoie directement.


aDB::fetchAll ([$aDB_MODE = aDB::BOTH, [$rQry = null, [$bIsSeekable = true]]])
Va récupérer les jeux de résultats de la requête et retourne un tableau avec tous ces jeux de résultat.
La forme du tableau dépend de $aDB_MODE.
Le mode par défaut est aDB::BOTH.


aDB::count ($rQry = null)
Renvoie un entier représentant le nombre de ligne total que devrait renvoyer la requête (sans tenir compte d'une éventuelle limitation
imposée par aDB::set_limit()).


aDB::prepare ($sQuery)
Prépare une requête en vue de l'utilisation de bindings, puis de l'exécution de la requête.
Va notamment échapper les caractères dangereux (en fonction du type du serveur de db évidemment).


aDB::bindValue ($sNeedle, $mValue, [$cType = null])
Ne peut fonctionner que si une requête a été préparée via aDB::prepare ().
Va chercher $sNeedle dans la requête, le remplacer par $mValue, et préparer à nouveau la requête pour recevoir $mValue en 
tant que $cType. 
$cType est un type attendu par la base de données; par exemple aDB::PARAM_INT.
Si $cType n'est pas fourni, alors le type est automatiquement celui détecté sur $mValue.
Voir la description des propriétés pour voir les types possible.
Exemple :
si $sQuery = 'SELECT * FROM table WHERE id= :iID'
et que je fais :
$aDB -> prepare ($sQuery);
$aDB -> bindValue (':iID', 10, aDB::PARAM_INT);
$sQuery sera alors égal à 'SELECT * FROM table WHERE id= 10'


aDB::execute ()
Exécute une requête préparée.


aDB::escape ($sString)
Echappe les caractères dangereux dans $sString.
retourne $sString échappée.


aDB::startTransaction ()
Débute une transaction.


aDB::commitTransaction ()
Fait un commit sur la transaction en cours.


aDB::rollbackTransaction ()
Fait un rollback sur la transaction en cours.


aDB::savePoint ($sSavePoint)
Crée un point de sauvegarde $sSavePoint.


aDB::rollbackToSavePoint ($sSavePoint)
Fait un rollback jusqu'au point de sauvegarde $sSavePoint.


aDB::releaseSavePoint ($sSavePoint)
Libère le point de sauvegarde $sSavePoint.


aDB::lastInsertId ()
Retourne le dernier ID inséré.


aDB::server_info ([$$rLink = null])
Renvoie les informations sur le serveur de DB.


aDB::setOption ($sOption, $mValue)
Fixe l'option $sOption à la valeur $mValue.


PROPRIETES UTILES :

**Propriétés récupérables : 

aDB::QUERY:
Ne peut pas être initialisée par ce biais. 
Renvoie la requête courante.
echo $aDB -> QUERY;


aDB::ERRORS
Ne peut pas être initialisée par ce biais. 
Renvoie le tableau d'erreurs si l'option EXCEPTION_ON_ERROR est inactive.


aDB::LAST_ERROR:
Ne peut pas être initialisée par ce biais. 
Renvoie la dernière erreur relevée si l'option EXCEPTION_ON_ERROR est inactive.


**Options :

AUTOCONNECT:
true si on doit se connecter à l'instanciation de l'objet.
false sinon.
par défaut : true.


EXCEPTION_ON_ERROR:
true si on doit lever des Exceptions dès qu'une erreur est détectée.
False sinon.
par défaut : true.


**Constantes :
Modes FETCH :

aDB::BOTH = 0;
Le jeu de résultat se présente sous la forme d'un tableau indexé numériquement ET associativement.


aDB::FETCH_ASSOC = 1;
Le jeu de résultat se présente sous la forme d'un tableau indexé associativement.


aDB::FETCH_NUM = 2;
Le jeu de résultat se présente sous la forme d'un tableau indexé numériquement.


aDB::FETCH_GROUP = 4;
Le jeu de résultat se présente sous la forme d'un tableau du type 
array (valeur_colonne_0 => array (valeurs_autres_colonnes)) indexé en fonction de son association avec 
aDB::BOTH, aDB::FETCH_NUM, aDB::FETCH_ASSOC.
Par défaut, il est associé avec aDB::BOTH


aDB::FETCH_EXTRACT = 8;
Le jeu de résultat est renvoyé dans des variables ayant pour noms le nom des colonnes.
Exemple :
SELECT user_id, user_nom FROM users
Renverra les valeurs dans $user_id et $user_nom, pour chaque tour de bocle sur les jeux de résultats retournés.
Utilisable uniquement avec la méthode aDB::fetch().


Types attendus par aDB::bindValue() :
aDB::PARAM_STR = 1000;
Type chaîne


aDB::PARAM_INT = 1001;
Type entier