README

Package de gestion de base de données pour NilsFramework.
Supporte MySQL, MariaDB, PostgreSQL et SQLite via une API statique simple et cohérente.

📋 Table des matières

• Installation
• Configuration
• Config
• Database
  • SELECT
  • INSERT
  • UPDATE
  • DELETE
  • Transactions
• Exceptions

Installation

composer require nilsframework/nils-database

Configuration

Créez un fichier Configuration/config.json à la racine de votre projet :

{
    "mysql": {
        "driver": "mysql",
        "host": "127.0.0.1",
        "username": "root",
        "password": "secret",
        "database": "ma_base"
    },
    "mariadb": {
        "driver": "mariadb",
        "host": "",
        "username": "",
        "password": "",
        "database": ""
    },
    "sqlite": {
        "driver": "sqlite",
        "database": "/chemin/vers/base.db"
    },
    "postgresql": {
        "driver": "postgresql",
        "host": "",
        "username": "",
        "password": "",
        "database": ""
    }
}

⚠️ Le driver actif est détecté automatiquement — c'est le premier bloc avec host et database non vides qui est utilisé. Pour SQLite, seul database est requis.

⚠️ Ne commitez jamais config.json — ajoutez-le à votre .gitignore.

Config

Config::charger()

Charge le fichier de configuration JSON. Appelé automatiquement si nécessaire.

use Configuration\Config;

// Chargement explicite (optionnel)
Config::charger('Configuration/config.json');

// Chargement automatique — appelé implicitement par toutes les autres méthodes
Config::get('debug');

Config::get()

Retourne la valeur d'une clé de premier niveau.

$debug   = Config::get('debug');
$appName = Config::get('app_name', 'Mon App'); // valeur par défaut si absente

Config::getSection()

Retourne une section entière du fichier de configuration.

$mysql = Config::getSection('mysql');
// [
//   'driver'   => 'mysql',
//   'host'     => '127.0.0.1',
//   'username' => 'root',
//   'password' => 'secret',
//   'database' => 'ma_base',
// ]

Config::getDatabaseConfig()

Retourne la configuration du driver de base de données actif (détection automatique).

$config = Config::getDatabaseConfig();
// Retourne la config du premier driver avec host + database non vides

Config::reinitialiser()

Réinitialise la configuration chargée. Utile pour les tests.

Config::reinitialiser();
Config::charger('Configuration/config.test.json');

Config::cheminFichier()

Retourne le chemin absolu du fichier de configuration chargé.

$chemin = Config::cheminFichier();
// /var/www/html/Configuration/config.json

Database

La classe Database fournit une API statique complète pour interagir avec la base de données.
La connexion est établie automatiquement à la première requête.

SELECT

Database::fetchAll()

Retourne toutes les lignes correspondant à la requête.

use Configuration\Database;

// Sans paramètres
$users = Database::fetchAll("SELECT * FROM utilisateurs");

// Avec paramètres nommés
$admins = Database::fetchAll(
    "SELECT * FROM utilisateurs WHERE role = :role AND actif = :actif",
    ['role' => 'admin', 'actif' => true]
);

// Avec paramètres positionnels
$users = Database::fetchAll(
    "SELECT * FROM utilisateurs WHERE age > ?",
    [18]
);

// Résultat
// [
//   ['id' => 1, 'nom' => 'Traore', 'role' => 'admin'],
//   ['id' => 2, 'nom' => 'Diallo', 'role' => 'admin'],
// ]

Database::fetchOne()

Retourne une seule ligne ou null si aucun résultat.

// Par ID
$user = Database::fetchOne(
    "SELECT * FROM utilisateurs WHERE id = :id",
    ['id' => 1]
);

if (!$user) {
    // Aucun résultat
}

// Par email
$user = Database::fetchOne(
    "SELECT * FROM utilisateurs WHERE email = :email",
    ['email' => 'traore@example.com']
);

// Résultat
// ['id' => 1, 'nom' => 'Traore', 'email' => 'traore@example.com']

INSERT

Database::insert()

Exécute un INSERT et retourne l'ID de la ligne insérée.

$id = Database::insert(
    "INSERT INTO utilisateurs (nom, email, password) VALUES (:nom, :email, :password)",
    [
        'nom'      => 'Traore',
        'email'    => 'traore@example.com',
        'password' => password_hash('secret', PASSWORD_DEFAULT),
    ]
);

echo $id; // 42

UPDATE

Database::update()

Exécute un UPDATE et retourne le nombre de lignes modifiées.

$nbLignes = Database::update(
    "UPDATE utilisateurs SET nom = :nom WHERE id = :id",
    ['nom' => 'Nouveau Nom', 'id' => 1]
);

echo $nbLignes; // 1

DELETE

Database::delete()

Exécute un DELETE et retourne le nombre de lignes supprimées.

$nbLignes = Database::delete(
    "DELETE FROM utilisateurs WHERE id = :id",
    ['id' => 1]
);

echo $nbLignes; // 1

// Supprimer plusieurs lignes
$nbLignes = Database::delete(
    "DELETE FROM sessions WHERE expire_at < :now",
    ['now' => date('Y-m-d H:i:s')]
);

Transactions

Les transactions permettent de grouper plusieurs opérations en une seule unité atomique.
Si une opération échoue, toutes les modifications sont annulées.

Database::debut()

Démarre une transaction.

Database::valider()

Valide et applique toutes les opérations de la transaction.

Database::annuler()

Annule toutes les opérations de la transaction en cours.

try {
    Database::debut();

    // Créer le cycle
    $cycleId = Database::insert(
        "INSERT INTO tnt_cycles (groupe_id, numero) VALUES (:groupe_id, :numero)",
        ['groupe_id' => 1, 'numero' => 3]
    );

    // Créer les cotisations pour chaque membre
    foreach ($participations as $participation) {
        Database::insert(
            "INSERT INTO tnt_cotisations (cycle_id, participation_id, montant) 
             VALUES (:cycle_id, :participation_id, :montant)",
            [
                'cycle_id'         => $cycleId,
                'participation_id' => $participation['id'],
                'montant'          => 5000,
            ]
        );
    }

    Database::valider();

} catch (\Throwable $e) {
    Database::annuler();
    throw $e;
}

Typage des paramètres

Le package infère automatiquement le type PDO selon la valeur PHP :

Vous pouvez forcer le type via le troisième paramètre :

Database::fetchAll(
    "SELECT * FROM users WHERE actif = :actif AND age > :age",
    ['actif' => 1,  'age' => 18],
    ['actif' => 'b', 'age' => 'i'] // b = bool, i = int, s = string, d = float
);

Drivers supportés

Exceptions

Toutes les erreurs lèvent une DatabaseException qui étend HttpException (code 500) :

use Exception\DatabaseException;

try {
    $user = Database::fetchOne("SELECT * FROM utilisateurs WHERE id = :id", ['id' => 1]);
} catch (DatabaseException $e) {
    echo $e->getMessage();      // Message technique
    echo $e->getUserMessage();  // "Erreur interne du serveur."
    echo $e->getStatusCode();   // 500
}

Fermer la connexion

Database::fermer();

Licence

MIT — © NilsFramework