[sync] Update embedded LibDB from standalone

Author: ImperaZim

src/imperazim/db/DBManager.php

@@ -5,34 +5,49 @@
 namespace imperazim\db;
 
 use imperazim\db\exception\DatabaseException;
+use Exception;
 
 /**
-* Class DBManager
-* @package imperazim\db
+* Factory for creating database connections.
+*
+* Usage:
+*   $db = DBManager::connect('sqlite', ['database' => '/path/to/mydb']);
+*   $db = DBManager::connect('mysql', [
+*       'host' => 'localhost',
+*       'username' => 'root',
+*       'password' => '',
+*       'database' => 'mydb'
+*   ]);
 */
 final class DBManager {
 
-  /**
-  * Connects to the specified database using the provided configuration.
-  * @param string $type The type of database (e.g., 'mysql', 'sqlite').
-  * @param array $config The configuration array for the database connection.
-  * @return mixed The database instance.
-  * @throws DatabaseException If the connection fails or the configuration is invalid.
-  */
-  public static function connect(string $type, array $config): mixed {
-    try {
-      switch (strtolower($type)) {
-        case 'mysql':
-          return Mysql::connect($config['host'], $config['username'], $config['password'], $config['database']);
-        case 'sqlite':
-          $directory = dirname($config['database']);
-          $fileName = pathinfo($config['database'], PATHINFO_FILENAME);
-          return new Sqlite3($directory, $fileName);
-        default:
-          throw new DatabaseException("Unsupported database type: $type");
-      }
-    } catch (\Exception $e) {
-      throw new DatabaseException("Failed to connect to the database: " . $e->getMessage(), 0, $e);
+    /**
+    * Connects to the specified database.
+    *
+    * @param string $type Database type: 'mysql' or 'sqlite'
+    * @param array $config Connection configuration
+    * @return Database Database instance
+    * @throws DatabaseException If connection fails or type unsupported
+    */
+    public static function connect(string $type, array $config): Database {
+        try {
+            return match (strtolower($type)) {
+                'mysql' => Mysql::connect(
+                    $config['host'],
+                    $config['username'],
+                    $config['password'],
+                    $config['database']
+                ),
+                'sqlite' => new Sqlite3(
+                    dirname($config['database']),
+                    pathinfo($config['database'], PATHINFO_FILENAME)
+                ),
+                default => throw new DatabaseException("Unsupported database type: $type"),
+            };
+        } catch (DatabaseException $e) {
+            throw $e;
+        } catch (Exception $e) {
+            throw new DatabaseException("Failed to connect to the database: " . $e->getMessage(), 0, $e);
+        }
     }
-  }
 }

src/imperazim/db/Database.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace imperazim\db;
+
+/**
+* Common base class for database drivers.
+*
+* Both Mysql and Sqlite3 extend this class, providing
+* a consistent API for CRUD operations.
+*/
+abstract class Database {
+
+    /**
+    * Creates tables if they do not exist.
+    *
+    * @param array $tables Associative array: table name => column definitions array
+    */
+    abstract public function createTableIfNotExists(array $tables): void;
+
+    /**
+    * Inserts a row into a table.
+    *
+    * @param string $table Table name
+    * @param array $data Column => value pairs
+    */
+    abstract public function insert(string $table, array $data): void;
+
+    /**
+    * Selects rows from a table.
+    *
+    * @param string $table Table name
+    * @param string $columns Column(s) to select (e.g. "*", "name, age")
+    * @param array $filters Where conditions: [["col" => "val"], ...]
+    * @return array Result rows
+    */
+    abstract public function select(string $table, string $columns, array $filters = []): array;
+
+    /**
+    * Updates rows in a table.
+    *
+    * @param string $table Table name
+    * @param string $column Column to update
+    * @param mixed $value New value
+    * @param array $filters Where conditions
+    * @return bool Whether any rows were affected
+    */
+    abstract public function update(string $table, string $column, mixed $value, array $filters = []): bool;
+
+    /**
+    * Deletes rows from a table.
+    *
+    * @param string $table Table name
+    * @param array $filters Where conditions (required — no empty deletes)
+    * @return int Number of deleted rows
+    */
+    abstract public function delete(string $table, array $filters): int;
+
+    /**
+    * Checks if a record exists in a table.
+    *
+    * @param string $table Table name
+    * @param array $conditions Where conditions
+    * @return bool Whether matching record exists
+    */
+    abstract public function exists(string $table, array $conditions): bool;
+
+    /**
+    * Executes a raw query with parameter binding.
+    *
+    * @param string $sql SQL with placeholders (?)
+    * @param array $params Bound parameter values
+    * @return array Result rows (empty for non-SELECT)
+    */
+    abstract public function query(string $sql, array $params = []): array;
+
+    /**
+    * Closes the database connection.
+    */
+    abstract public function close(): void;
+}