Better explain the EntityManager::getReference() method

[mpdude]

As one takeaway from #3037 (comment) and #843, we should look into better explaining the EntityManager::getReference() method, it’s semantics, caveats and potential responsibilities placed on the user.

[mpdude]

@flack what would have helped you, what would you like to have known before, what warning signs do you deem appropriate?

[flack]

@mpdude I was about to open a ticket about that, too (was thinking something along the lines of "getReference() can corrupt UnitOfWork internal state").

A stern warning in the documentation can't hurt, but realistically, it won't prevent many errors either. I suppose there are no sanity checks in this method because of performance, but it's a bit absurd that I can have an entity with an autoincrement ID field, and then get a reference for id -1 and for id "some random string" (but ok, those totally invalid references won't cause collisions later on).

It would be nice it doctrine had some way of handling these invalid references gracefully. E.g. if addToIdentityMap detects a collision and sees the existing entry is a reference, it could try to load it and if that fails remove it and replace it with the new entity. But I don't know if that detection can be made 100% reliable.

[flack]

How terrible would it be to make getReference actually do a DB query to see if the identifier exists? Maybe this could be optional so that you can skip it if you're sure the ID is valid, e.g. something like this:

public function getReference($entityName, $id, $skip_id_check = false);