#27345 Added Component/Lock/Store/MongoDbStore

Author: Joe Bennett

components/lock.rst

@@ -225,6 +225,7 @@ Store                                         Scope   Blocking  Expiring
 ============================================  ======  ========  ========
 :ref:`FlockStore <lock-store-flock>`          local   yes       no
 :ref:`MemcachedStore <lock-store-memcached>`  remote  no        yes
+:ref:`MongoDbStore <lock-store-mongodb>`      remote  no        yes
 :ref:`PdoStore <lock-store-pdo>`              remote  no        yes
 :ref:`RedisStore <lock-store-redis>`          remote  no        yes
 :ref:`SemaphoreStore <lock-store-semaphore>`  local   yes       no
@@ -277,6 +278,39 @@ support blocking, and expects a TTL to avoid stalled locks::
 
     Memcached does not support TTL lower than 1 second.
 
+.. _lock-store-mongodb:
+
+MongoDbStore
+~~~~~~~~~~~~
+
+.. versionadded:: 4.4
+
+    The ``MongoDbStore`` was introduced in Symfony 4.4.
+
+The MongoDbStore saves locks on a MongoDB server, it requires a
+``\MongoDB\Client`` connection from `mongodb/mongodb`_. This store does not
+support blocking and expects a TTL to avoid stalled locks::
+
+    use Symfony\Component\Lock\Store\MongoDbStore;
+
+    $mongoClient = new \MongoDB\Client('mongo://localhost/');
+
+    $options = [
+        'database' => 'my-app',
+    ];
+
+    $store = new MongoDbStore($mongoClient, $options);
+
+The ``MongoDbStore`` takes the following ``$options``:
+
+============  =========  ========================================================================
+Option        Default    Description
+============  =========  ========================================================================
+database                 The name of the database [Mandatory]
+collection    ``lock``   The name of the collection
+gcProbablity  ``0.001``  Should a TTL Index be created expressed as a probability from 0.0 to 1.0
+============  =========  ========================================================================
+
 .. _lock-store-pdo:
 
 PdoStore
@@ -413,7 +447,7 @@ Remote Stores
 ~~~~~~~~~~~~~
 
 Remote stores (:ref:`MemcachedStore <lock-store-memcached>`,
-:ref:`PdoStore <lock-store-pdo>`,
+:ref:`MongoDbStore <lock-store-mongodb>`, :ref:`PdoStore <lock-store-pdo>`,
 :ref:`RedisStore <lock-store-redis>` and
 :ref:`ZookeeperStore <lock-store-zookeeper>`) use a unique token to recognize
 the true owner of the lock. This token is stored in the
@@ -438,7 +472,7 @@ Expiring Stores
 ~~~~~~~~~~~~~~~
 
 Expiring stores (:ref:`MemcachedStore <lock-store-memcached>`,
-:ref:`PdoStore <lock-store-pdo>` and
+:ref:`MongoDbStore <lock-store-mongodb>`, :ref:`PdoStore <lock-store-pdo>` and
 :ref:`RedisStore <lock-store-redis>`)
 guarantee that the lock is acquired only for the defined duration of time. If
 the task takes longer to be accomplished, then the lock can be released by the
@@ -556,6 +590,46 @@ method uses the Memcached's ``flush()`` method which purges and removes everythi
     The method ``flush()`` must not be called, or locks should be stored in a
     dedicated Memcached service away from Cache.
 
+MongoDbStore
+~~~~~~~~~~~~
+
+.. caution::
+
+    The locked resource name is indexed in the ``_id`` field of the lock
+    collection. Beware that in MongoDB an indexed field's value can be
+    `a maximum of 1024 bytes in length`_ inclusive of structural overhead.
+
+A TTL index MUST BE used on MongoDB 2.2+ to automatically clean up expired locks.
+Such an index can be created manually:
+
+.. code-block:: javascript
+
+    db.lock.ensureIndex(
+        { "expires_at": 1 },
+        { "expireAfterSeconds": 0 }
+    )
+
+Alternatively, the method ``MongoDbStore::createTtlIndex(int $expireAfterSeconds = 0)``
+can be called once to create the TTL index during database setup. Read more
+about `Expire Data from Collections by Setting TTL`_ in MongoDB.
+
+.. tip::
+
+    ``MongoDbStore`` will attempt to automatically create a TTL index on MongoDB
+    2.2+. It's recommended to set constructor option ``gcProbablity = 0.0`` to
+    disable this behavior if you have manually dealt with TTL index creation.
+
+.. caution::
+
+    This store relies on all PHP application and database nodes to have
+    synchronized clocks for lock expiry to occur at the correct time. To ensure
+    locks don't expire prematurely; the lock TTL should be set with enough extra
+    time in ``expireAfterSeconds`` to account for any clock drift between nodes.
+
+``writeConcern``, ``readConcern`` and ``readPreference`` are not specified by
+MongoDbStore meaning the collection's settings will take effect. Read more
+about `Replica Set Read and Write Semantics`_ in MongoDB.
+
 PdoStore
 ~~~~~~~~~~
 
@@ -674,10 +748,14 @@ instance, during the deployment of a new version. Processes with new
 configuration must not be started while old processes with old configuration
 are still running.
 
+.. _`a maximum of 1024 bytes in length`: https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit
 .. _`ACID`: https://en.wikipedia.org/wiki/ACID
+.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
+.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
+.. _`Expire Data from Collections by Setting TTL`: https://docs.mongodb.com/manual/tutorial/expire-data/
 .. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science)
-.. _`PHP semaphore functions`: https://php.net/manual/en/book.sem.php
+.. _`mongodb/mongodb`: https://packagist.org/packages/mongodb/mongodb
 .. _`PDO`: https://php.net/pdo
-.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
-.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
+.. _`PHP semaphore functions`: https://php.net/manual/en/book.sem.php
+.. _`Replica Set Read and Write Semantics`: https://docs.mongodb.com/manual/applications/replication/
 .. _`ZooKeeper`: https://zookeeper.apache.org/