:ref:`MongoDbStore <lock-store-mongodb>` remote no yes

.. _lock-store-mongodb:

MongoDbStore

.. versionadded:: 5.1

The ``MongoDbStore`` was introduced in Symfony 5.1.

The MongoDbStore saves locks on a MongoDB server ``>=2.2``, it requires a

``\MongoDB\Collection`` or ``\MongoDB\Client`` from `mongodb/mongodb`_ or a

`MongoDB Connection String`_.

This store does not support blocking and expects a TTL to

avoid stalled locks::

The ``MongoDbStore`` takes the following ``$options`` (depending on the first parameter type):

Option Description

gcProbablity Should a TTL Index be created expressed as a probability from 0.0 to 1.0 (Defaults to ``0.001``)

database The name of the database

collection The name of the collection

uriOptions Array of uri options for `MongoDBClient::__construct`_

driverOptions Array of driver options for `MongoDBClient::__construct`_

When the first parameter is a:

``MongoDB\Collection``:

- ``$options['database']`` is ignored

- ``$options['collection']`` is ignored

``MongoDB\Client``:

- ``$options['database']`` is mandatory

- ``$options['collection']`` is mandatory

MongoDB Connection String:

- ``$options['database']`` is used otherwise ``/path`` from the DSN, at least one is mandatory

- ``$options['collection']`` is used otherwise ``?collection=`` from the DSN, at least one is mandatory

.. note::

The ``collection`` querystring parameter is not part of the `MongoDB Connection String`_ definition.

It is used to allow constructing a ``MongoDbStore`` using a `Data Source Name (DSN)`_ without ``$options``.

:ref:`MongoDbStore <lock-store-mongodb>`,

:ref:`MongoDbStore <lock-store-mongodb>`,

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 to automatically clean up expired locks.

Such an index can be created manually:

.. code-block:: javascript

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.

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.

.. _`a maximum of 1024 bytes in length`: https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit

.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name

.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/src/Connection.php

.. _`Expire Data from Collections by Setting TTL`: https://docs.mongodb.com/manual/tutorial/expire-data/

.. _`MongoDB Connection String`: https://docs.mongodb.com/manual/reference/connection-string/

.. _`mongodb/mongodb`: https://packagist.org/packages/mongodb/mongodb

.. _`MongoDBClient::__construct`: https://docs.mongodb.com/php-library/current/reference/method/MongoDBClient__construct/

.. _`PHP semaphore functions`: https://www.php.net/manual/en/book.sem.php

.. _`Replica Set Read and Write Semantics`: https://docs.mongodb.com/manual/applications/replication/