[deprecations] Create a DocumentManagerInterface to prevent deprecations on @interal

[rbaarsma]

Bug Report

Q	A
BC Break	yes*
Version	2.0.2

• but only for automated testing without deprecations, which breaks our CI.

Summary

Since updating to Symfony 4.4 I have this deprecation message in the automated tests:

The "Doctrine\ODM\MongoDB\DocumentManager::getClassMetadata()" method is considered internal Performance-sensitive method. It may change without further notice. You should not extend it from "Mockery_11_Doctrine_ODM_MongoDB_DocumentManager".

This is due to DocumentManager.php line 280: "@internal Performance-sensitive method."

How to reproduce

basic Symfony 4.4 project with a controller and a test like this: (Note could have been any service, not necessarily a controller)

class SomeController {
  public function test(DocumentManager $dm) {
    $dm->flush();
  }
}

class SomeControllerTest {
  public function test() {
    $om = \Mockery::mock(DocumentManager::class);
    (new SomeController)->test($om);
  }
}

Expected behavior

No deprecations:

Suggested solution

Easily fixed by creating an DocumentManagerInterface, just like the EntityManagerInterface. This way we can write automated tests using the interface and have no problems with internal annotations like this. This solves other issues too.

I know there is a interface ObjectManager that could be used for this case, but in my specific use-case, I'm using both the ODM and the ORM in the same Symfony application, and due to the nature of Dependency Injection it's not logical to use the ObjectManager, which is ambiguous in this case.

[alcaeus]

I don't think a method should be marked as "internal" because it's performance sensitive, especially when it uses a cache. I suggest removing the @internal designation instead. @malarzm @jmikola would you agree?

[malarzm]

Yes, TBH I'm surprised it's still there :D IIRC long time ago @internal some comment was meant for PHPDoc to exclude part of the comment from docs and I suppose it's just a remainder of that times.

[alcaeus]

2123 removes the designations. We will still add an interface for the document manager, similar to EntityManagerInterface in ORM.