PHPORM-99 Implement optimized lock and cache (#2877)

Fix fo PHPORM-99

In theory, we can use DatabaseStore and DatabaseLock. But various issues prove the changing nature of their implementation, based on new features in the query builder, make this feature unstable for MongoDB users. fix #2718, fix #2609

By introducing dedicated drivers, we can optimize the implementation to use the mongodb library directly instead of the subset of features provided by Laravel query builder.

Usage:

# config/cache.php
return [

    'stores' => [

        'mongodb' => [
            'driver' => 'mongodb',
            'connection' => 'mongodb',
            'collection' => 'cache',
            'lock_connection' => 'mongodb',
            'lock_collection' => 'cache_locks',
            'lock_lottery' => [2, 100],
            'lock_timeout' => '86400',
        ]
    ]

]
Cache:

// Store any value into the cache. The value is serialized in MongoDB
Cache::set('foo', [1, 2, 3]);

// Read the value
dump(Cache::get('foo'));

// Clear the cache
Cache::flush();
Lock:

// Get an unique lock. It's very important to keep this object in memory
// so that the lock can be released.
$lock = Cache::lock('foo');
$lock->block(10); // Wait 10 seconds before throwing an exception if the lock isn't released

// Any time-consuming task
sleep(5);

// Release the lock
$lock->release();

Author: GromNaN

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 * New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738)
 * Drop support for Composer 1.x by @GromNaN in [#2784](https://github.com/mongodb/laravel-mongodb/pull/2784)
 * Fix `artisan query:retry` command by @GromNaN in [#2838](https://github.com/mongodb/laravel-mongodb/pull/2838)
+* Add `mongodb` cache and lock drivers by @GromNaN in [#2877](https://github.com/mongodb/laravel-mongodb/pull/2877)
 
 ## [4.2.0] - 2024-03-14
 

composer.json

@@ -25,10 +25,11 @@
         "php": "^8.1",
         "ext-mongodb": "^1.15",
         "composer-runtime-api": "^2.0.0",
-        "illuminate/support": "^10.0|^11",
+        "illuminate/cache": "^10.36|^11",
         "illuminate/container": "^10.0|^11",
         "illuminate/database": "^10.30|^11",
         "illuminate/events": "^10.0|^11",
+        "illuminate/support": "^10.0|^11",
         "mongodb/mongodb": "^1.15"
     },
     "require-dev": {

src/Cache/MongoLock.php

@@ -0,0 +1,134 @@
+<?php
+
+namespace MongoDB\Laravel\Cache;
+
+use Illuminate\Cache\Lock;
+use MongoDB\Laravel\Collection;
+use MongoDB\Operation\FindOneAndUpdate;
+use Override;
+
+use function random_int;
+
+final class MongoLock extends Lock
+{
+    /**
+     * Create a new lock instance.
+     *
+     * @param Collection  $collection              The MongoDB collection
+     * @param string      $name                    Name of the lock
+     * @param int         $seconds                 Time-to-live of the lock in seconds
+     * @param string|null $owner                   A unique string that identifies the owner. Random if not set
+     * @param array       $lottery                 The prune probability odds
+     * @param int         $defaultTimeoutInSeconds The default number of seconds that a lock should be held
+     */
+    public function __construct(
+        private readonly Collection $collection,
+        string $name,
+        int $seconds,
+        ?string $owner = null,
+        private readonly array $lottery = [2, 100],
+        private readonly int $defaultTimeoutInSeconds = 86400,
+    ) {
+        parent::__construct($name, $seconds, $owner);
+    }
+
+    /**
+     * Attempt to acquire the lock.
+     */
+    public function acquire(): bool
+    {
+        // The lock can be acquired if: it doesn't exist, it has expired,
+        // or it is already owned by the same lock instance.
+        $isExpiredOrAlreadyOwned = [
+            '$or' => [
+                ['$lte' => ['$expiration', $this->currentTime()]],
+                ['$eq' => ['$owner', $this->owner]],
+            ],
+        ];
+        $result = $this->collection->findOneAndUpdate(
+            ['_id' => $this->name],
+            [
+                [
+                    '$set' => [
+                        'owner' => [
+                            '$cond' => [
+                                'if' => $isExpiredOrAlreadyOwned,
+                                'then' => $this->owner,
+                                'else' => '$owner',
+                            ],
+                        ],
+                        'expiration' => [
+                            '$cond' => [
+                                'if' => $isExpiredOrAlreadyOwned,
+                                'then' => $this->expiresAt(),
+                                'else' => '$expiration',
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+            [
+                'upsert' => true,
+                'returnDocument' => FindOneAndUpdate::RETURN_DOCUMENT_AFTER,
+                'projection' => ['owner' => 1],
+            ],
+        );
+
+        if (random_int(1, $this->lottery[1]) <= $this->lottery[0]) {
+            $this->collection->deleteMany(['expiration' => ['$lte' => $this->currentTime()]]);
+        }
+
+        return $result['owner'] === $this->owner;
+    }
+
+    /**
+     * Release the lock.
+     */
+    #[Override]
+    public function release(): bool
+    {
+        $result = $this->collection
+            ->deleteOne([
+                '_id' => $this->name,
+                'owner' => $this->owner,
+            ]);
+
+        return $result->getDeletedCount() > 0;
+    }
+
+    /**
+     * Releases this lock in disregard of ownership.
+     */
+    #[Override]
+    public function forceRelease(): void
+    {
+        $this->collection->deleteOne([
+            '_id' => $this->name,
+        ]);
+    }
+
+    /**
+     * Returns the owner value written into the driver for this lock.
+     */
+    #[Override]
+    protected function getCurrentOwner(): ?string
+    {
+        return $this->collection->findOne(
+            [
+                '_id' => $this->name,
+                'expiration' => ['$gte' => $this->currentTime()],
+            ],
+            ['projection' => ['owner' => 1]],
+        )['owner'] ?? null;
+    }
+
+    /**
+     * Get the UNIX timestamp indicating when the lock should expire.
+     */
+    private function expiresAt(): int
+    {
+        $lockTimeout = $this->seconds > 0 ? $this->seconds : $this->defaultTimeoutInSeconds;
+
+        return $this->currentTime() + $lockTimeout;
+    }
+}