Initial commit

Author: kansatech

.gitignore

@@ -0,0 +1,11 @@
+# Composer dependencies
+/vendor/
+
+# Composer lock file (optional—commit if you want reproducible builds)
+/composer.lock
+
+# PHPStorm settings
+.idea/
+
+# Log files
+*.log

changelog.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to **comphp/database** will be documented in this file.
+
+## [0.1.0] - 2025-03-16
+
+### Added
+- **Initial Release** of the `comphp/database` library.
+- **DatabaseManager** providing centralized connection management.
+- **MySQL Driver** (`MysqlDatabaseDriver`) with essential operations (fetch, insert, update, etc.).
+- **Alias Database Driver** enabling alias-based connection references.
+- **Transaction Support** allowing atomic multi-query operations.
+- **PSR-3 Logging** integration for query actions and exceptions.
+- **PSR-14 Events** (`ConnectedEvent`, `QueryExecutedEvent`) for event-driven usage.
+- **Extensibility** through `comphp/extensible` (register new drivers, manage them via attributes).
+- **Query Profiling** to log query execution duration and errors.
+

code_of_conduct.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+- Using welcoming and inclusive language.
+- Being respectful of differing viewpoints and experiences.
+- Gracefully accepting constructive criticism.
+- Focusing on what is best for the community.
+
+Examples of unacceptable behavior by participants include:
+- Harassment, intimidation, or discriminatory comments.
+- Trolling, insulting, or derogatory comments.
+- Unwelcome sexual attention or advances.
+- Deliberate intimidation or stalking.
+
+## Reporting and Enforcement
+
+If you experience or witness any behavior that violates this Code of Conduct, please report it by emailing [conduct@commonphp.org](mailto:conduct@commonphp.org). All complaints will be reviewed promptly and confidentially by the project maintainers.
+
+Project maintainers are responsible for enforcing this code throughout the project and community. They have the right to remove, edit, or reject any contributions or comments that do not align with this Code of Conduct.
+
+By participating in this project, you agree to abide by these guidelines and help create a positive environment for everyone.

composer.json

@@ -0,0 +1,24 @@
+{
+  "name": "comphp/database",
+  "license": "MIT",
+  "autoload": {
+    "psr-4": {
+      "Neuron\\Database\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "NeuronTests\\Database\\": "test/"
+    }
+  },
+  "require": {
+    "php": "^8.4",
+    "psr/log": "^3.0",
+    "comphp/extensible": "^0.1",
+    "comphp/events": "^0.2",
+    "ext-pdo": "*"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^12.0"
+  }
+}

contributing.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Thank you for considering contributing to this project! Your help is essential in making this library better for everyone.
+
+## How to Report Bugs
+- Before opening a new issue, please search the issue tracker for similar reports.
+- When reporting a bug, include a clear and descriptive title, a detailed explanation, and steps to reproduce the issue.
+
+## How to Request Features
+- Check the existing issues to ensure your feature hasn’t already been requested.
+- Provide a clear description of the feature, its benefits, and any potential implementation ideas.
+
+## Pull Request Guidelines
+- Fork the repository and create your branch from `master`.
+- Follow the coding style guidelines (PSR standards).
+- Write clear commit messages that explain the rationale behind your changes.
+- Ensure all tests pass before submitting your pull request.
+- Include relevant documentation updates if necessary.
+
+## Additional Guidelines
+- Respect the existing code style and architecture.
+- Be open to feedback and constructive criticism.
+- Engage in discussions on issues and pull requests respectfully.
+
+Thank you for your contributions!

examples/alias-driver-usage.php

@@ -0,0 +1,35 @@
+<?php
+
+use Neuron\Database\DatabaseManager;
+use Neuron\Database\Drivers\AliasDatabaseDriver;
+use Neuron\Database\Drivers\MysqlDatabaseDriver;
+use Neuron\Extensibility\ExtensionStore;
+use Neuron\Extensibility\InstantiatorInterface;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use Psr\Log\LoggerInterface;
+
+/** @var LoggerInterface $logger */
+/** @var InstantiatorInterface $instantiator */
+/** @var EventDispatcherInterface $eventDispatcher */
+
+$extensions = new ExtensionStore($instantiator, $logger, $eventDispatcher);
+$database = new DatabaseManager($logger, $extensions, $eventDispatcher);
+
+// Register primary database connection
+$database->connect('primary', MysqlDatabaseDriver::class, [
+    'database' => 'primary_db',
+    'host' => 'localhost',
+    'username' => 'user',
+    'password' => 'password',
+]);
+
+// Register an alias connection pointing to primary
+$database->connect('secondary', AliasDatabaseDriver::class, [
+    'database' => $database,
+    'target' => 'primary'
+]);
+
+// Using the alias connection transparently
+$result = $database->fetchOne('SELECT COUNT(*) AS total FROM users', [], 'secondary');
+
+echo "Total users: " . $result['total'] . "\n";

examples/basic-usage.php

@@ -0,0 +1,35 @@
+<?php
+
+use Neuron\Database\DatabaseManager;
+use Neuron\Database\Drivers\MysqlDatabaseDriver;
+use Neuron\Database\FetchMode;
+use Neuron\Extensibility\ExtensionStore;
+use Neuron\Extensibility\InstantiatorInterface;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use Psr\Log\LoggerInterface;
+
+// Assume these instances are created or injected via your application's DI container
+/** @var LoggerInterface $logger */
+/** @var InstantiatorInterface $instantiator */
+/** @var EventDispatcherInterface $eventDispatcher */
+
+// Setup extensibility
+$extensions = new ExtensionStore($instantiator, $logger, $eventDispatcher);
+
+// Create a new database manager
+$database = new DatabaseManager($logger, $extensions, $eventDispatcher);
+
+// Connect to the database using MysqlDatabaseDriver
+$database->connect('_default_', MysqlDatabaseDriver::class, [
+    'database' => 'my_database',
+    'host' => 'localhost',
+    'username' => 'user',
+    'password' => 'password',
+]);
+
+// Execute a basic query
+$result = $database->fetchAll('SELECT * FROM users LIMIT 5');
+
+foreach ($result as $user) {
+    echo "User ID: {$user['id']}, Name: {$user['name']}\n";
+}

examples/error-handling.php

@@ -0,0 +1,29 @@
+<?php
+
+use Neuron\Database\DatabaseException;
+use Neuron\Database\DatabaseManager;
+use Neuron\Database\Drivers\MysqlDatabaseDriver;
+use Neuron\Extensibility\ExtensionStore;
+use Neuron\Extensibility\InstantiatorInterface;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use Psr\Log\LoggerInterface;
+
+/** @var LoggerInterface $logger */
+/** @var InstantiatorInterface $instantiator */
+/** @var EventDispatcherInterface $eventDispatcher */
+
+$extensions = new ExtensionStore($instantiator, $logger, $eventDispatcher);
+$database = new DatabaseManager($logger, $extensions, $eventDispatcher);
+
+$database->connect('_default_', MysqlDatabaseDriver::class, [
+    'database' => 'nonexistent_db', // Intentional wrong DB name
+    'host' => 'localhost',
+    'username' => 'user',
+    'password' => 'wrongpassword',
+]);
+
+try {
+    $database->execute('SELECT * FROM users');
+} catch (DatabaseException $e) {
+    echo "Database error: " . $e->getMessage();
+}

examples/query-profiling.php

@@ -0,0 +1,41 @@
+<?php
+
+use Neuron\Database\DatabaseManager;
+use Neuron\Database\Drivers\MysqlDatabaseDriver;
+use Neuron\Extensibility\ExtensionStore;
+use Neuron\Extensibility\InstantiatorInterface;
+use Neuron\Database\Events\QueryExecutedEvent;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use Psr\Log\LoggerInterface;
+
+/** @var LoggerInterface $logger */
+/** @var InstantiatorInterface $instantiator */
+/** @var EventDispatcherInterface $eventDispatcher */
+
+$extensions = new ExtensionStore($instantiator, $logger, $eventDispatcher);
+$database = new DatabaseManager($logger, $extensions, $eventDispatcher);
+
+// Connect to your database
+$database->connect('_default_', MysqlDatabaseDriver::class, [
+    'database' => 'my_database',
+    'host' => 'localhost',
+    'username' => 'user',
+    'password' => 'password',
+]);
+
+// Enable profiling
+$database->enableProfiling();
+
+// Listen to query executed events for profiling output
+$eventDispatcher->listen(QueryExecutedEvent::class, function (QueryExecutedEvent $event) {
+    echo sprintf(
+        "[%s] Query executed: %s | Duration: %.4f seconds\n",
+        strtoupper($event->action),
+        $event->query,
+        $event->duration
+    );
+});
+
+// Execute queries
+$database->fetchAll('SELECT * FROM users LIMIT 10');
+$database->execute('UPDATE users SET last_login = NOW() WHERE id = ?', [1]);

examples/transaction-usage.php

@@ -0,0 +1,33 @@
+<?php
+
+use Neuron\Database\DatabaseManager;
+use Neuron\Database\Drivers\MysqlDatabaseDriver;
+use Neuron\Extensibility\ExtensionStore;
+use Neuron\Extensibility\InstantiatorInterface;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use Psr\Log\LoggerInterface;
+
+/** @var LoggerInterface $logger */
+/** @var InstantiatorInterface $instantiator */
+/** @var EventDispatcherInterface $eventDispatcher */
+
+$extensions = new ExtensionStore($instantiator, $logger, $eventDispatcher);
+$database = new DatabaseManager($logger, $extensions, $eventDispatcher);
+
+$database->connect('_default_', MysqlDatabaseDriver::class, [
+    'database' => 'my_database',
+    'host' => 'localhost',
+    'username' => 'user',
+    'password' => 'password',
+]);
+
+try {
+    $database->transaction(function ($db) {
+        $db->execute('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Checking', 500]);
+        $db->execute('INSERT INTO transactions (account_id, amount) VALUES (?, ?)', [1, 500]);
+    });
+
+    echo "Transaction completed successfully.\n";
+} catch (Throwable $e) {
+    echo "Transaction failed: " . $e->getMessage();
+}