Add a new topological sort implementation

[mpdude]

This is the first chunk to break #10547 into smaller PRs suitable for reviewing. It adds a new topological sort implementation.

Background

Topological sort is an algorithm that sorts the vertices of a directed acyclic graph (DAG) in a linear order such that for every directed edge from vertex A to vertex B, vertex A comes before vertex B in the ordering. This ordering is called a topological order.

Ultimately (beyond the scope of this PR), in the ORM we'll need this to find an order in which we can insert new entities into the database. When one entity needs to refer to another one by means of a foreign key, the referred-to entity must be inserted before the referring entity. Deleting entities is similar.

A topological sorting can be obtained by running a depth first search (DFS) on the graph. The order in which the DFS finishes on the vertices is a topological order. The DFS is possible iif there are no cycles in the graph. When there are cycles, the DFS will find them.

For more information about topological sorting, as well as a description of an DFS-based topological sorting algorithm, see https://en.wikipedia.org/wiki/Topological_sorting.

Current situation

There is a DFS-based topological sorting implemented in the CommitOrderCalculator. This implementation has two kinks:

1. It does not detect cycles

When there is a cycle in the graph, we need to know about it. Ultimately, this means we will not be able to insert entities into the database in any order that allows all foreign keys constraints to be satisfied.

If you look at CommitOrderCalculator, you'll see that there is no code dealing with this situation.

2. It has an obscure concept of edge "weights"

To me, it is not clear how those are supposed to work. The weights are related to whether a foreign key is nullable or not, but can (could) be arbitrary integers. An edge will be ignored if it has a higher (lower) weight than another, already processed edge... 🤷🏻?

Suggested change

In fact, when inserting entities into the database, we have two kinds of foreign key relationships: Those that are nullable, and those that are not.

Non-nullable foreign keys are hard requirements: Referred-to entities must be inserted first, no matter what. These are "non-optional" edges in the dependency graph.

Nullable foreign keys can be set to NULL when first inserting an entity, and then coming back and updating the foreign key value after the referred-to (related) entity has been inserted into the database. This is already implemented in \Doctrine\ORM\UnitOfWork::scheduleExtraUpdate, at the expense of performing one extra UPDATE query after all the INSERTs have been processed. These edges are "optional".

When finding a cycle that consists of non-optional edges only, treat it as a failure. We won't be able to insert entities with a circular dependency when all foreign keys are non-NULLable.

When a cycle contains at least one optional edge, we can use it to break the cycle: Use backtracking to go back to the point before traversing the last optional edge. This omits the edge from the topological sort order, but will cost one extra UPDATE later on.

To make the transition easier, the new implementation is provided as a separate class, which is marked as @internal.

Outlook

Backtracking to the last optional edge is the simplest solution for now. In general, it might be better to find another (optional) edge that would also break the cycle, if that edge is also part of other cycles.

Remember, every optional edge skipped costs an extra UPDATE query later on. The underlying problem is known as the "minimum feedback arc set" problem, and is not easily/efficiently solvable. Thus, for the time being, picking the nearest optional edge seems to be reasonable.

Extra bonus

This is what the DALL·E AI thinks it looks like when you have a directed graph with cycles, and some wizardry finds a solution to break those.

[greg0ire]

Git says the concept of "weight" was introduced in #1570
@guilhermeblanco hi! Could you maybe shed some light on how they work?

[mpdude]

@derrabus I've added the @internal docbock and a comment explaining the use of array_reverse.

[mpdude]

@derrabus Do you 👍 this? I need to get this merged into the temporary branch so I can continue working on #10547.