wip

Author: mpyw

.github/workflows/ci.yml

@@ -79,7 +79,7 @@ jobs:
         run: composer phpstan
 
       - name: Test
-        run: composer test -- --coverage-clover build/logs/clover.xml
+        run: composer test -- --testdox --coverage-clover build/logs/clover.xml
         env:
           PG_HOST: 127.0.0.1
           MY_HOST: 127.0.0.1

composer.json

@@ -24,6 +24,7 @@
     "require": {
         "php": "^8.0.2",
         "ext-pdo": "*",
+        "illuminate/events": "^8.0 || ^9.0 || ^10.0",
         "illuminate/support": "^8.0 || ^9.0 || ^10.0",
         "illuminate/database": "^8.0 || ^9.0 || ^10.0",
         "illuminate/contracts": "^8.0 || ^9.0 || ^10.0"
@@ -46,6 +47,11 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "extra": {
+        "laravel": {
+            "providers": [
+                "Mpyw\\LaravelDatabaseAdvisoryLock\\AdvisoryLockServiceProvider"
+            ]
+        },
         "phpstan": {
             "includes": [
                 "extension.neon"

src/AdvisoryLockServiceProvider.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mpyw\LaravelDatabaseAdvisoryLock;
+
+use Illuminate\Support\ServiceProvider;
+
+/**
+ * class AdvisoryLockServiceProvider
+ *
+ * Automatically registered through package discovery.
+ */
+final class AdvisoryLockServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->app->singleton(TransactionEventHub::class);
+    }
+
+    public function boot(TransactionEventHub $hub): void
+    {
+        TransactionEventHub::setResolver(fn () => $hub);
+    }
+}

src/AdvisoryLocks.php

@@ -9,10 +9,18 @@
 use Illuminate\Database\QueryException;
 use Mpyw\LaravelDatabaseAdvisoryLock\Contracts\LockerFactory as FactoryContract;
 
+/**
+ * trait AdvisoryLocks
+ *
+ * Designed to be mixed in with the Connection classes.
+ */
 trait AdvisoryLocks
 {
     public ?FactoryContract $advisoryLocker = null;
 
+    /**
+     * Create LockerFactory or return existing one.
+     */
     public function advisoryLocker(): FactoryContract
     {
         assert($this instanceof Connection);
@@ -21,6 +29,8 @@ public function advisoryLocker(): FactoryContract
     }
 
     /**
+     * Overrides the original implementation.
+     *
      * @param  string         $query
      * @param  array          $bindings
      * @throws QueryException
@@ -29,7 +39,7 @@ protected function handleQueryException(QueryException $e, $query, $bindings, Cl
     {
         assert($this instanceof Connection);
 
-        // Don't try again if there are session-level locks
+        // Don't try again if there are session-level locks.
         if ($this->transactionLevel() > 0 || $this->advisoryLocker()->forSession()->hasAny()) {
             throw $e;
         }

src/Concerns/ReleasesWhenDestructed.php

@@ -4,9 +4,6 @@
 
 namespace Mpyw\LaravelDatabaseAdvisoryLock\Concerns;
 
-/**
- * @internal
- */
 trait ReleasesWhenDestructed
 {
     abstract public function release(): bool;

src/Concerns/SessionLocks.php

@@ -7,9 +7,6 @@
 use Mpyw\LaravelDatabaseAdvisoryLock\Contracts\LockFailedException;
 use Mpyw\LaravelDatabaseAdvisoryLock\Contracts\SessionLock;
 
-/**
- * @internal
- */
 trait SessionLocks
 {
     abstract public function lockOrFail(string $key, int $timeout = 0): SessionLock;

src/Concerns/TransactionalLocks.php

@@ -6,9 +6,6 @@
 
 use Mpyw\LaravelDatabaseAdvisoryLock\Contracts\LockFailedException;
 
-/**
- * @internal
- */
 trait TransactionalLocks
 {
     public function tryLock(string $key, int $timeout = 0): bool

src/Contracts/InvalidTransactionLevelException.php

@@ -6,6 +6,11 @@
 
 use BadMethodCallException;
 
+/**
+ * class InvalidTransactionLevelException
+ *
+ * You can't use TransactionLocker outside of transaction.
+ */
 class InvalidTransactionLevelException extends BadMethodCallException
 {
 }

src/Contracts/LockFailedException.php

@@ -7,6 +7,11 @@
 use Illuminate\Database\QueryException;
 use RuntimeException;
 
+/**
+ * class LockFailedException
+ *
+ * Lock acquisition has been failed.
+ */
 class LockFailedException extends QueryException
 {
     public function __construct(string $message, string $sql, array $bindings)

src/Contracts/LockerFactory.php

@@ -4,9 +4,21 @@
 
 namespace Mpyw\LaravelDatabaseAdvisoryLock\Contracts;
 
+/**
+ * interface LockerFactory
+ *
+ * Entrypoint used from the mix-in AdvisoryLocks trait.
+ * Underlying locker instances are managed as singletons.
+ */
 interface LockerFactory
 {
+    /**
+     * Create a transaction-level locker or return existing one.
+     */
     public function forTransaction(): TransactionLocker;
 
+    /**
+     * Create a session-level locker or return existing one.
+     */
     public function forSession(): SessionLocker;
 }