Add DbConnection adapters

Author: antonkomarev

.github/workflows/php.yml

@@ -8,7 +8,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Docker compose up
         run: docker compose up -d

composer.json

@@ -34,7 +34,12 @@
         "ext-pdo": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^10.0"
+        "doctrine/dbal": "4.*",
+        "phpstan/phpstan": "2.1.22",
+        "phpunit/phpunit": "^10.3"
+    },
+    "conflict": {
+        "doctrine/dbal": "<4.0 || >=5.0"
     },
     "autoload": {
         "psr-4": {

phpstan.neon

@@ -0,0 +1,7 @@
+parameters:
+    level: 10
+    checkUninitializedProperties: true
+    paths:
+        - src
+    excludePaths:
+        - vendor

src/DbConnection/DoctrineDbConnection.php

@@ -2,23 +2,31 @@
 
 declare(strict_types=1);
 
-namespace Cog\DbLocker\DbConnection;
+namespace Cog\DbLocker\DbConnectionAdapter;
 
-interface DbConnectionInterface
+interface DbConnectionAdapterInterface
 {
+    public const PLATFORM_MYSQL = 'mysql';
+    public const PLATFORM_POSTGRESQL = 'postgresql';
+
     /**
      * Execute a SQL query and return the first column of the first row.
      *
      * @param string $sql The SQL query to execute
      * @param array<string, mixed> $parameters Parameters to bind to the query
      * @return mixed The value from the first column of the first row
      */
-    public function executeAndFetchColumn(string $sql, array $parameters = []): mixed;
+    public function executeAndFetchColumn(
+        string $sql,
+        array $parameters = [],
+    ): mixed;
 
     /**
      * Check if the connection is currently inside a transaction.
      *
      * @return bool True if inside a transaction, false otherwise
      */
     public function isInTransaction(): bool;
+
+    public function getPlatformName(): string;
 }

src/DbConnection/DbConnectionInterface.php renamed to src/DbConnectionAdapter/DbConnectionAdapterInterface.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cog\DbLocker\DbConnectionAdapter;
+
+use Cog\DbLocker\DbConnectionAdapter\Exception\UncheckedDoctrineDbalException;
+use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception as DbalException;
+use Doctrine\DBAL\Platforms\MySQLPlatform;
+use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
+use RuntimeException;
+
+/**
+ * Doctrine DBAL adapter for unified database connection interface.
+ *
+ * This adapter wraps a Doctrine DBAL Connection instance and provides
+ * a consistent interface for database operations across different database drivers.
+ */
+final class DoctrineDbConnectionAdapter implements
+    DbConnectionAdapterInterface
+{
+    public function __construct(
+        private readonly Connection $dbConnection,
+    ) {}
+
+    /**
+     * @inheritDoc
+     */
+    public function executeAndFetchColumn(
+        string $sql,
+        array $parameters = [],
+    ): mixed {
+        try {
+            return $this->dbConnection->fetchOne($sql, $parameters);
+        } catch (Exception $e) {
+            throw new RuntimeException(
+                sprintf(
+                    'Doctrine DBAL error while executing SQL query: %s. Error: %s',
+                    $sql,
+                    $e->getMessage(),
+                ),
+                previous: $e,
+            );
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function isInTransaction(): bool
+    {
+        return $this->dbConnection->isTransactionActive();
+    }
+
+    public function getPlatformName(): string
+    {
+        try {
+            return match (true) {
+                $this->dbConnection->getDatabasePlatform() instanceof MySqlPlatform => self::PLATFORM_MYSQL,
+                $this->dbConnection->getDatabasePlatform() instanceof PostgreSqlPlatform => self::PLATFORM_POSTGRESQL,
+                default => gettype($this->dbConnection->getDatabasePlatform()),
+            };
+        } catch (DbalException $exception) {
+            throw UncheckedDoctrineDbalException::ofDbalException($exception);
+        }
+    }
+}

src/DbConnectionAdapter/DoctrineDbConnectionAdapter.php

@@ -2,9 +2,11 @@
 
 declare(strict_types=1);
 
-namespace Cog\DbLocker\DbConnection;
+namespace Cog\DbLocker\DbConnectionAdapter;
 
 use Illuminate\Database\Connection;
+use Illuminate\Database\MySqlConnection;
+use Illuminate\Database\PostgresConnection;
 use Illuminate\Database\QueryException;
 use RuntimeException;
 
@@ -14,23 +16,25 @@
  * This adapter wraps an Illuminate\Database\Connection instance and provides
  * a consistent interface for database operations across different database drivers.
  */
-final class EloquentDbConnection implements
-    DbConnectionInterface
+final class EloquentDbConnectionAdapter implements
+    DbConnectionAdapterInterface
 {
     public function __construct(
-        private Connection $connection,
+        private readonly Connection $dbConnection,
     ) {}
 
     /**
      * @inheritDoc
      */
-    public function executeAndFetchColumn(string $sql, array $parameters = []): mixed
-    {
+    public function executeAndFetchColumn(
+        string $sql,
+        array $parameters = [],
+    ): mixed {
         try {
             // Convert named parameters to positional parameters for Eloquent
             $bindings = array_values($parameters);
 
-            $result = $this->connection->selectOne($sql, $bindings);
+            $result = $this->dbConnection->selectOne($sql, $bindings);
 
             if ($result === null) {
                 return null;
@@ -57,6 +61,15 @@ public function executeAndFetchColumn(string $sql, array $parameters = []): mixe
      */
     public function isInTransaction(): bool
     {
-        return $this->connection->transactionLevel() > 0;
+        return $this->dbConnection->transactionLevel() > 0;
+    }
+
+    public function getPlatformName(): string
+    {
+        return match (true) {
+            $this->dbConnection instanceof MySqlConnection => self::PLATFORM_MYSQL,
+            $this->dbConnection instanceof PostgresConnection => self::PLATFORM_POSTGRESQL,
+            default => gettype($this->dbConnection),
+        };
     }
 }

src/DbConnection/EloquentDbConnection.php renamed to src/DbConnectionAdapter/EloquentDbConnectionAdapter.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cog\DbLocker\DbConnectionAdapter\Exception;
+
+use Doctrine\DBAL\Exception as DoctrineDbalException;
+use RuntimeException;
+
+final class UncheckedDoctrineDbalException extends RuntimeException
+{
+    public static function ofDbalException(
+        DoctrineDbalException $exception,
+    ): self {
+        return new self(
+            $exception->getMessage(),
+            $exception->getCode(),
+            $exception,
+        );
+    }
+}

src/DbConnectionAdapter/Exception/UncheckedDoctrineDbalException.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Cog\DbLocker\DbConnection;
+namespace Cog\DbLocker\DbConnectionAdapter;
 
 use PDO;
 use PDOStatement;
@@ -14,18 +14,20 @@
  * This adapter wraps a PDO instance and provides a consistent interface
  * for database operations across different database drivers.
  */
-final class PdoDbConnection implements
-    DbConnectionInterface
+final class PdoDbConnectionAdapter implements
+    DbConnectionAdapterInterface
 {
     public function __construct(
-        private PDO $pdo,
+        private readonly PDO $pdo,
     ) {}
 
     /**
      * @inheritDoc
      */
-    public function executeAndFetchColumn(string $sql, array $parameters = []): mixed
-    {
+    public function executeAndFetchColumn(
+        string $sql,
+        array $parameters = [],
+    ): mixed {
         $statement = $this->prepareAndExecute($sql, $parameters);
 
         $result = $statement->fetchColumn(0);
@@ -96,4 +98,13 @@ private function prepareAndExecute(string $sql, array $parameters): PDOStatement
             );
         }
     }
+
+    public function getPlatformName(): string
+    {
+        return match ($this->pdo->getAttribute(PDO::ATTR_DRIVER_NAME)) {
+            'mysql' => self::PLATFORM_MYSQL,
+            'pgsql' => self::PLATFORM_POSTGRESQL,
+            default => $this->pdo->getAttribute(PDO::ATTR_DRIVER_NAME),
+        };
+    }
 }

src/DbConnection/PdoDbConnection.php renamed to src/DbConnectionAdapter/PdoDbConnectionAdapter.php

@@ -48,7 +48,7 @@ classId: self::convertStringToSignedInt32($namespace),
             objectId: self::convertStringToSignedInt32($value),
             // TODO: Do we need to sanitize it?
             // TODO: Do we need to omit ":" on end if no value is passed
-            humanReadableValue: "$namespace:$value",
+            humanReadableValue: "$namespace|$value",
         );
     }