#27345 Added MongoDbStore Lock Store documentation

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:`RedisStore <lock-store-redis>`          remote  no        yes
 :ref:`SemaphoreStore <lock-store-semaphore>`  local   yes       no
 ============================================  ======  ========  ========
@@ -217,6 +218,37 @@ support blocking, and expects a TTL to avoid stalled locks::
 
     Memcached does not support TTL lower than 1 second.
 
+.. _lock-store-mongodb:
+
+MongoDbStore
+~~~~~~~~~~
+
+The MongoDbStore saves locks on a MongoDB server, it requires a ``\MongoDB\Client`` connection.
+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         Mandatory Default        Description
+============== ========= ============== ===================================================================================
+database       Yes                      The name of the database
+collection     No        ``lock``       The name of the collection
+resource_field No        ``_id``        The field name for storing the lock id **MUST be uniquely indexed if you chage it**
+token_field    No        ``token``      The field name for storing the lock token
+aquired_field  No        ``aquired_at`` The field name for storing the acquisition timestamp
+expiry_field   No        ``expires_at`` The field name for storing the expiry-timestamp
+============== ========= ============== ===================================================================================
+
 .. _lock-store-redis:
 
 RedisStore
@@ -290,7 +322,8 @@ the component is used in the following way.
 Remote Stores
 ~~~~~~~~~~~~~
 
-Remote stores (:ref:`MemcachedStore <lock-store-memcached>` and
+Remote stores (:ref:`MemcachedStore <lock-store-memcached>`,
+:ref:`MongoDbStore <lock-store-mongodb>` and
 :ref:`RedisStore <lock-store-redis>`) use an 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 the
@@ -313,7 +346,8 @@ different machines may allow two different processes to acquire the same ``Lock`
 Expiring Stores
 ~~~~~~~~~~~~~~~
 
-Expiring stores (:ref:`MemcachedStore <lock-store-memcached>` and
+Expiring stores (:ref:`MemcachedStore <lock-store-memcached>`,
+:ref:`MongoDbStore <lock-store-mongodb>` 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
@@ -431,6 +465,28 @@ 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
+~~~~~~~~~~~~~~
+
+The MongoDbStore relies on a unique index on the ``<resource_field>``. By default
+this is ``_id`` which already has a unique index being the collection identifier.
+It is strongly recommended to leave this as is. If you do need to change the
+``<resource_field>`` you **MUST** ensure you place a unique index on your filed.
+
+It's possible to automatically expire the locks in the database as described below:
+
+A TTL index can be used on MongoDB 2.2+ to cleanup expired locks
+automatically. Such an index can for example look like this:
+
+.. code-block:: javascript
+
+    db.<lock-collection>.ensureIndex(
+        { "<expiry-field>": 1 },
+        { "expireAfterSeconds": 0 }
+    )
+
+For more details see: http://docs.mongodb.org/manual/tutorial/expire-data/
+
 RedisStore
 ~~~~~~~~~~