Rewrite locker api (#6)

Author: antonkomarev

README.md

@@ -34,18 +34,17 @@ composer require cybercog/php-db-locker
 ```php
 $dbConnection = new PDO($dsn, $username, $password);
 
-$postgresLocker = new \Cog\DbLocker\Locker\PostgresAdvisoryLocker();
-$postgresLockId = \Cog\DbLocker\LockId\PostgresLockId::fromKeyValue('user', '4');
+$locker = new \Cog\DbLocker\Postgres\PostgresAdvisoryLocker();
+$lockId = \Cog\DbLocker\Postgres\PostgresLockKey::create('user', '4');
 
 $dbConnection->beginTransaction();
-$isLockAcquired = $postgresLocker->acquireLock(
+$lock = $locker->acquireSessionLevelLockHandler(
     $dbConnection,
-    $postgresLockId,
-    \Cog\DbLocker\Locker\PostgresAdvisoryLockScopeEnum::Transaction,
-    \Cog\DbLocker\Locker\PostgresAdvisoryLockTypeEnum::NonBlocking,
-    \Cog\DbLocker\Locker\PostgresLockModeEnum::Exclusive,
+    $lockId,
+    \Cog\DbLocker\Postgres\Enum\PostgresLockWaitModeEnum::NonBlocking,
+    \Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum::Exclusive,
 );
-if ($isLockAcquired) {
+if ($lock->wasAcquired) {
     // Execute logic if lock was successful
 } else {
     // Execute logic if lock acquisition has been failed
@@ -58,22 +57,24 @@ $dbConnection->commit();
 ```php
 $dbConnection = new PDO($dsn, $username, $password);
 
-$postgresLocker = new \Cog\DbLocker\Locker\PostgresAdvisoryLocker();
-$postgresLockId = \Cog\DbLocker\LockId\PostgresLockId::fromKeyValue('user', '4');
-
-$isLockAcquired = $postgresLocker->acquireLock(
-    $dbConnection,
-    $postgresLockId,
-    \Cog\DbLocker\Locker\PostgresAdvisoryLockScopeEnum::Session,
-    \Cog\DbLocker\Locker\PostgresAdvisoryLockTypeEnum::NonBlocking,
-    \Cog\DbLocker\Locker\PostgresLockModeEnum::Exclusive,
-);
-if ($isLockAcquired) {
-    // Execute logic if lock was successful
-} else {
-    // Execute logic if lock acquisition has been failed
+$locker = new \Cog\DbLocker\Postgres\PostgresAdvisoryLocker();
+$lockId = \Cog\DbLocker\Postgres\PostgresLockKey::create('user', '4');
+
+try {
+    $lock = $locker->acquireSessionLevelLockHandler(
+        $dbConnection,
+        $lockId,
+        \Cog\DbLocker\Postgres\Enum\PostgresLockWaitModeEnum::NonBlocking,
+        \Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum::Exclusive,
+    );
+    if ($lock->wasAcquired) {
+        // Execute logic if lock was successful
+    } else {
+        // Execute logic if lock acquisition has been failed
+    }
+} finally {
+    $lock->release();
 }
-$postgresLocker->releaseLock($dbConnection, $postgresLockId);
 ```
 
 ## Changelog

src/LockId/LockId.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cog\DbLocker\Postgres\Enum;
+
+/**
+ * PostgresLockAccessModeEnum defines the access mode of advisory lock acquisition.
+ *
+ * TODO: Need string values only for tests, should add match to tests instead.
+ */
+enum PostgresLockAccessModeEnum: string
+{
+    case Exclusive = 'ExclusiveLock';
+    case Share = 'ShareLock';
+}

src/Locker/PostgresAdvisoryLocker.php

@@ -2,10 +2,10 @@
 
 declare(strict_types=1);
 
-namespace Cog\DbLocker\Locker;
+namespace Cog\DbLocker\Postgres\Enum;
 
 /**
- * PostgresAdvisoryLockScopeEnum defines the scope of advisory lock acquisition.
+ * PostgresLockLevelEnum defines the level of advisory lock acquisition.
  *
  * - Session. Session-level advisory lock (without _XACT_):
  *      - PG_ADVISORY_LOCK
@@ -18,7 +18,7 @@
  *      - PG_TRY_ADVISORY_XACT_LOCK
  *      - PG_TRY_ADVISORY_XACT_LOCK_SHARED
  */
-enum PostgresAdvisoryLockScopeEnum
+enum PostgresLockLevelEnum
 {
     case Session;
     case Transaction;

src/Locker/PostgresLockModeEnum.php

@@ -2,10 +2,10 @@
 
 declare(strict_types=1);
 
-namespace Cog\DbLocker\Locker;
+namespace Cog\DbLocker\Postgres\Enum;
 
 /**
- * PostgresAdvisoryLockTypeEnum defines the type of advisory lock acquisition.
+ * PostgresLockWaitModeEnum defines the type of advisory lock acquisition.
  *
  * - NonBlocking. Attempt to acquire the lock without blocking (with _TRY_):
  *      - PG_TRY_ADVISORY_LOCK
@@ -18,8 +18,8 @@
  *      - PG_ADVISORY_XACT_LOCK
  *      - PG_ADVISORY_XACT_LOCK_SHARED
  */
-enum PostgresAdvisoryLockTypeEnum
+enum PostgresLockWaitModeEnum
 {
-    case NonBlocking;
     case Blocking;
+    case NonBlocking;
 }

src/Postgres/Enum/PostgresLockAccessModeEnum.php

@@ -0,0 +1,70 @@
+<?php
+
+/*
+ * This file is part of PHP DB Locker.
+ *
+ * (c) Anton Komarev <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Cog\DbLocker\Postgres\LockHandle;
+
+use Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum;
+use Cog\DbLocker\Postgres\PostgresAdvisoryLocker;
+use Cog\DbLocker\Postgres\PostgresLockKey;
+use PDO;
+
+/**
+ * @internal
+ */
+final class SessionLevelLockHandle
+{
+    private bool $isReleased = false;
+
+    public function __construct(
+        private readonly PDO $dbConnection,
+        private readonly PostgresAdvisoryLocker $locker,
+        public readonly PostgresLockKey $lockId,
+        public readonly PostgresLockAccessModeEnum $accessMode,
+        public readonly bool $wasAcquired,
+    ) {}
+
+    /**
+     * Explicitly release the lock if it was acquired and not yet released.
+     *
+     * @return bool True if the lock was released, false if it wasn't acquired or already released
+     */
+    public function release(): bool
+    {
+        /**
+         * This code is mimicking the behavior of DB lock release.
+         */
+        if (!$this->wasAcquired || $this->isReleased) {
+            return false;
+        }
+
+        $wasReleased = $this->locker->releaseSessionLevelLock(
+            $this->dbConnection,
+            $this->lockId,
+        );
+
+        if ($wasReleased) {
+            $this->isReleased = true;
+        }
+
+        return $wasReleased;
+    }
+
+    /**
+     * Automatically release the lock when the handle is destroyed.
+     */
+    public function __destruct()
+    {
+        // TODO: Do we need to
+        $this->release();
+    }
+}