Document restrictions for postUpdate, postRemove and postPersist events

[mpdude]

Coming from #10869 and #10874:

May listeners for these post* events...

• call EntityManager#flush() again?
• make updates to managed entities, which might be due for processing in the currently running transaction?

[mpdude]

Regarding updates to managed entities, I am concerned about when the UoW takes snapshots/updates originalEntityData. Does that happen before or after the events?

One potential issue I see is that the changesets may be computed, then the event fires and leads to entity modifications, and then the entity state is snapshotted/marked as clean. In that case, we might miss necessary updates (also in subsequent flushes).

Note the code paths are somewhat different for updates to plain attributes vs. collection updates.

[mpdude]

Just realized that at the time where postPersist is emitted (during/at the end of UoW::executeInserts), there may still be pending extra updates (so the database does not 100% reflect the desired entity state). Also, collection updates did not yet happen, so many-to-many tables might be incomplete also.