Deprecate EntityRepository#clear()

[lcobucci]

That method calls EntityManager#clear() with an argument, which won't be allowed anymore on v3.0.

We must add a @deprecated annotation (without a trigger_error() since it's already handled by EntityManager#clear()).

---

Context on the why: #7925 (comment)

[danielspk]

Help please!

What is the current solution? The documentation is not up to date: https://www.doctrine-project.org/projects/doctrine-orm/en/2.7/reference/batch-processing.html

Example:

$demoA = new DemoA();
$demoA->setName('Demo');

$entityManager->persist($demoA);
$entityManager->flush();

while (/* many entities .. */) {
  $demoB = new DemoB();
  $demoB->setDemoA($demoA);

  $entityManager->persist($demoB);
  $entityManager->flush();
  $entityManager->detach($demoB); // ERROR: Method Doctrine\\ORM\\EntityManager::detach() is deprecated and will be removed in Doctrine ORM 3.0
}

[Ocramius]

Yes, the docs will require updating there 👍

@danielspk check ocramius/doctrine-batch-utils for a more (simplistic) self-contained batch processing library

[lcobucci]

Handled by #7928

Documentation will be sorted out by another PR.

[danielspk]

@Ocramius I think ocramius/doctrine-batch-utils doesn't solve this BC:

• support Doctrine ORM 2.7 version?
• in my example $demoA should never be cleaned/detached. Only instances of $demoB that can be thousands should be cleared/detached. How would it be possible to perform this selective cleaning with doctrine-batch-utils?

[lcobucci]

@danielspk if your code is your simple as your example, then it should be converted to this:

$demoA = new DemoA();
$demoA->setName('Demo');

$entityManager->persist($demoA);
$entityManager->flush();
$entityManager->clear(); // we don't need anything in the UoW

while (/* many entities .. */) {
  $demoB = new DemoB();
  $demoB->setDemoA($entityManager->getReference(DemoA::class, $demoA->getId()); // assuming that `getId()` is how you get the identifier

  $entityManager->persist($demoB);
  $entityManager->flush();
  $entityManager->clear();
}

How would it be possible to perform this selective cleaning?

Ideally, nobody would need that.

Managing the UoW is an internal operation that might affect the behaviour of the ORM, hence our move to try to regain control over it.
We're still having some discussions about it, since some people are fine with messing up with the UoW while understanding that their on their own.

In the meantime, (if you really really really really really want to detach stuff and you're aware that you may have to deal with dragons) you can do $entityManager->getUnitOfWork()->detach($blah) without triggering and E_USER_DEPRECATED - it only has a @deprecated annotation which may be converted to @internal depending how our discussion goes.

Nevertheless your comment isn't related to this issue, since you're talking about EntityManager#clear() and not EntityRepository#clear().

[danielspk]

Thank you very much @lcobucci

His example is enlightening.

In my case, after the loop, I need to use $ demoA again, but once again accessing the database is not expensive, it simply requires a refactor.

Under these discussions, do you think it is worthwhile to make a refactor to migrate to version 2.7 or will it simply be better to wait for 2.8 when you are more certain?

Cheers

[lcobucci]

In my case, after the loop, I need to use $ demoA again, but once again accessing the database is not expensive, it simply requires a refactor.

Using the L2C would also make this even less expensive - but you'd have to check if it's applicable to your use cases.

Under these discussions, do you think it is worthwhile to make a refactor to migrate to version 2.7 or will it simply be better to wait for 2.8 when you are more certain?

Triggering E_USER_DEPRECATED will remain in 2.8 and it's not an error perse, it's a warning to help you be ready for when Doctrine ORM 3.0 comes.

I'd suggest you to always try to migrate to the latest versions to reduce your maintenance burden but I can't tell how much effort is involved in your app. I'd also say for you to be as away from the UoW as possible but I understand that it's sometimes inevitable.