Leave only *Handler API

Author: antonkomarev

src/Postgres/PostgresAdvisoryLocker.php

@@ -81,19 +81,16 @@ public function acquireSessionLevelLock(
      * ⚠️ Transaction-level advisory locks are strongly preferred whenever possible,
      * as they are automatically released at the end of a transaction and are less error-prone.
      * Use session-level locks only when transactional context is not available.
+     * @see acquireTransactionLevelLock() for preferred locking strategy.
+     *
+     * @template TReturn
      *
      * @param PDO $dbConnection Active database connection.
      * @param PostgresLockKey $key Lock key to be acquired.
      * @param callable(SessionLevelLockHandle): TReturn $callback A callback that receives the lock handle.
      * @param PostgresLockWaitModeEnum $waitMode Whether to wait for the lock or fail immediately. Default is non-blocking.
      * @param PostgresLockAccessModeEnum $accessMode Whether to acquire a shared or exclusive lock. Default is exclusive.
      * @return TReturn The return value of the callback.
-     *
-     * @template TReturn
-     *
-     * TODO: Cover with tests
-     * @see acquireTransactionLevelLock() for preferred locking strategy.
-     *
      */
     public function withinSessionLevelLock(
         PDO $dbConnection,

test/Integration/Postgres/PostgresAdvisoryLockerTest.php

@@ -566,6 +566,30 @@ public function testItCannotReleaseAllLocksAcquiredWithinTransaction(): void
         $this->assertPgAdvisoryLockExistsInConnection($dbConnection, $lockKey2);
     }
 
+    public function testItCanExecuteCodeWithinSessionLock(): void
+    {
+        $locker = $this->initLocker();
+        $dbConnection = $this->initPostgresPdoConnection();
+        $lockKey = PostgresLockKey::create('test');
+        $x = 2;
+        $y = 3;
+
+        $result = $locker->withinSessionLevelLock(
+            $dbConnection,
+            $lockKey,
+            function () use ($dbConnection, $lockKey, $x, $y): int {
+                $this->assertPgAdvisoryLocksCount(1);
+                $this->assertPgAdvisoryLockExistsInConnection($dbConnection, $lockKey);
+
+                return $x + $y;
+            },
+        );
+
+        $this->assertSame(5, $result);
+        $this->assertPgAdvisoryLocksCount(0);
+        $this->assertPgAdvisoryLockMissingInConnection($dbConnection, $lockKey);
+    }
+
     private function initLocker(): PostgresAdvisoryLocker
     {
         return new PostgresAdvisoryLocker();