Transactions and Concurrency

Choosing the Field Type

When using the date-based type in a high-concurrency environment, it is still possible to create multiple documents with the same version and cause a conflict. This can be avoided by using the int or decimal128 type.

Usage

When a version conflict is encountered during DocumentManager#flush(), a LockException is thrown. This exception can be caught and handled. Potential responses to a LockException are to present the conflict to the user or to refresh or reload objects and then retry the update.

With PHP promoting a share-nothing architecture, the worst case scenario for a delay between rendering an update form (with existing document data) and modifying the document after a form submission may be your application's session timeout. If the document is changed within that time frame by some other request, it may be preferable to encounter a LockException when retrieving the document instead of executing the update.

You can specify the expected version of a document during a query with DocumentManager#find():

1
<?php
use Doctrine\ODM\MongoDB\LockMode;
use Doctrine\ODM\MongoDB\LockException;
use Doctrine\ODM\MongoDB\DocumentManager;

$theDocumentId = 1;
$expectedVersion = 184;

/* @var $dm DocumentManager */

try {
    $document = $dm->find(User::class, $theDocumentId, LockMode::OPTIMISTIC, $expectedVersion);

    // do the work

    $dm->flush();
} catch(LockException $e) {
    echo "Sorry, but someone else has already changed this document. Please apply the changes again!";
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Alternatively, an expected version may be specified for an existing document with DocumentManager#lock():

1
<?php
use Doctrine\ODM\MongoDB\LockMode;
use Doctrine\ODM\MongoDB\LockException;
use Doctrine\ODM\MongoDB\DocumentManager;

$theDocumentId = 1;
$expectedVersion = 184;

/* @var $dm DocumentManager */

$document = $dm->find(User::class, $theDocumentId);

try {
    // assert version
    $dm->lock($document, LockMode::OPTIMISTIC, $expectedVersion);

} catch(LockException $e) {
    echo "Sorry, but someone else has already changed this document. Please apply the changes again!";
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Workflow

Say you have Alice and Bob editing a hypothetical blog post:

• Alice reads the headline of the blog post being "Foo", at optimistic lock version 1 (GET Request)
• Bob reads the headline of the blog post being "Foo", at optimistic lock version 1 (GET Request)
• Bob updates the headline to "Bar", upgrading the optimistic lock version to 2 (POST Request of a Form)
• Alice updates the headline to "Baz", ... (POST Request of a Form)

At the last stage of this scenario the blog post has to be read again from the database before Alice's headline can be applied. At this point you will want to check if the blog post is still at version 1 (which it is not in this scenario).

In order to correctly utilize optimistic locking, you must add the version as hidden form field or, for more security, session attribute. Otherwise, you cannot verify that the version at the time of update is the same as what was originally read from the database when Alice performed her original GET request for the blog post. Without correlating the version across form submissions, the application could lose updates.

Example Code

The form (GET Request):

1
<?php
use Doctrine\ODM\MongoDB\DocumentManager;

/* @var $dm DocumentManager */

$post = $dm->find(BlogPost::class, 123456);

echo '<input type="hidden" name="id" value="' . $post->getId() . '" />';
echo '<input type="hidden" name="version" value="' . $post->getCurrentVersion() . '" />';
2
3
4
5
6
7
8
9

And the change headline action (POST Request):

1
<?php
use Doctrine\ODM\MongoDB\DocumentManager;
use Doctrine\ODM\MongoDB\LockMode;

/* @var $dm DocumentManager */

$postId = (int)$_POST['id'];
$postVersion = (int)$_POST['version'];

$post = $dm->find(BlogPost::class, $postId, LockMode::OPTIMISTIC, $postVersion);
2
3
4
5
6
7
8
9
10