#27345 Added Component\Lock\Store\MongoDbStore

Author: Joe Bennett

components/lock.rst

@@ -173,6 +173,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
@@ -219,6 +220,36 @@ 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.2
+    The MongoDbStore was introduced Symfony 4.2.
+
+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 = array(
+        '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
+========== ======== ====================================
+
 .. _lock-store-pdo:
 
 PdoStore
@@ -361,7 +392,8 @@ Remote Stores
 ~~~~~~~~~~~~~
 
 Remote stores (:ref:`MemcachedStore <lock-store-memcached>`,
-:ref:`PdoStore <lock-store-pdo>`, :ref:`RedisStore <lock-store-redis>`, and
+: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
 :class:`Symfony\\Component\\Lock\\Key` object and is used internally by
@@ -385,7 +417,8 @@ Expiring Stores
 ~~~~~~~~~~~~~~~
 
 Expiring stores (:ref:`MemcachedStore <lock-store-memcached>`,
-:ref:`PdoStore <lock-store-pdo>` and :ref:`RedisStore <lock-store-redis>`)
+: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
 store and acquired by someone else.
@@ -502,6 +535,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 resouce name is indexed in the ``_id`` field of the
+    lock collection.
+    An indexed field's value in MongoDB can be a maximum of 1024 bytes in
+    length inclusive of structural overhead.
+
+For more details see: https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit
+
+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.
+
+For more details see: http://docs.mongodb.org/manual/tutorial/expire-data/
+
+.. caution::
+
+    This store relies on all client and server 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 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.
+
+For more details see: https://docs.mongodb.com/manual/applications/replication/
+
 PdoStore
 ~~~~~~~~~~
 
@@ -622,6 +695,7 @@ are still running.
 
 .. _`ACID`: https://en.wikipedia.org/wiki/ACID
 .. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science)
+.. _`mongodb/mongodb`: https://packagist.org/packages/mongodb/mongodb
 .. _Packagist: https://packagist.org/packages/symfony/lock
 .. _`PHP semaphore functions`: http://php.net/manual/en/book.sem.php
 .. _`PDO`: https://php.net/pdo