[Docs] Explicit transaction example with connection does not close EntityManager at rollback

[ToshY]

Bug Report

Q	A
BC Break	no
Version	>=2.5.0

Summary

• The first example for an explicit transaction (using the Doctrine\DBAL\Connection API) has lost the part that closes the EntityManager, therefore making it no longer "functionally equivalent" to the subsequent example using EntityManager#transactional($func).

Current behavior

<?php
// $em instanceof EntityManager
$em->getConnection()->beginTransaction(); // suspend auto-commit
try {
    //... do some work
    $user = new User;
    $user->setName('George');
    $em->persist($user);
    $em->flush();
    $em->getConnection()->commit();
} catch (Exception $e) {
    $em->getConnection()->rollback();
    throw $e;
}

Expected behavior

<?php
// $em instanceof EntityManager
$em->getConnection()->beginTransaction(); // suspend auto-commit
try {
    //... do some work
    $user = new User;
    $user->setName('George');
    $em->persist($user);
    $em->flush();
    $em->getConnection()->commit();
} catch (Exception $e) {
    $em->close();
    $em->getConnection()->rollback();
    throw $e;
}

[mpdude]

What about this code?

https://github.com/doctrine/orm/blob/597a63a86ca8c5f9d1ec2dc74fe3d1269d43434a/lib/Doctrine/ORM/UnitOfWork.php#L477-L487

When an exception occurs inside UnitOfWork::commit(), the EM is closed before the exception is re-thrown. Isn't that what you're looking for?

[ToshY]

@mpdude I don't think we are on the same page.

• I have no issues with the code implementations, just the example in the documentations. I'm trying to point out that the example does not correspond to textual explanation that is provided.
• Please not that it concerns an explicit transaction, so it uses Doctrine\DBAL\Connection. Looking at the Connection it only performs a rollback, and does not close the entitymanager unlike EntityManager#transactional($func), making the following sentence in the documentation incorrect: https://github.com/doctrine/orm/blob/19db7510a7b49605a9139fc2964342a98a682a8c/docs/en/reference/transactions-and-concurrency.rst?plain=1#L87-L88

As it's currently not "funcionally equivalent", I propose to update the documentation to include $em->close() in the catch block before the rollback, in order to be consistent with the behavior of EntityManager#transactional as mentioned in the text.

[mpdude]

Doesn't the UoW already close the entity manager when an exception is thrown from inside UoW::commit()?

[mpdude]

What I want to say is:

From the user's perspective, you don't have to close the EntityManager, in neither of the two ways. The ORM code will make sure it will be closed.