feat: flush once

[nikophil]

"flush once" is back 😁

and with very promising performances:

 +--------------------------------+-------------------+-----+------+-----+------------------+-------------------+-----------------+
| benchmark                      | subject           | set | revs | its | mem_peak         | mode              | rstdev          |
+--------------------------------+-------------------+-----+------+-----+------------------+-------------------+-----------------+
| ContactFactoryBench            | bench_create      |     | 10   | 5   | 36.505mb -0.91%  | 2.014ms -55.82%   | ±3.01% +0.62%   |
| ContactFactoryBench            | bench_create_many | 1   | 10   | 5   | 36.510mb -0.91%  | 2.006ms -56.51%   | ±5.87% +33.85%  |
| ContactFactoryBench            | bench_create_many | 10  | 10   | 5   | 38.641mb -4.17%  | 9.827ms -86.69%   | ±1.07% -28.84%  |
| ContactFactoryBench            | bench_create_many | 50  | 10   | 5   | 47.611mb -13.50% | 43.849ms -95.14%  | ±1.03% -46.15%  |
| CategoryFactoryBench           | bench_create      |     | 10   | 5   | 36.368mb +0.03%  | 4.456ms -3.47%    | ±2.42% +65.48%  |
| CategoryFactoryBench           | bench_create_many | 1   | 10   | 5   | 36.374mb +0.05%  | 5.055ms +9.20%    | ±5.23% +185.21% |
| CategoryFactoryBench           | bench_create_many | 10  | 10   | 5   | 39.982mb -0.36%  | 35.603ms -54.27%  | ±0.83% +14.62%  |
| CategoryFactoryBench           | bench_create_many | 50  | 10   | 5   | 55.253mb -1.41%  | 168.601ms -84.58% | ±1.25% +94.84%  |
| PersistentDocumentFactoryBench | bench_create      |     | 10   | 5   | 34.787mb +0.02%  | 728.893μs -0.38%  | ±2.72% +96.36%  |
| PersistentDocumentFactoryBench | bench_create_many | 1   | 10   | 5   | 34.788mb +0.02%  | 770.702μs +3.88%  | ±1.96% -8.50%   |
| PersistentDocumentFactoryBench | bench_create_many | 10  | 10   | 5   | 35.304mb -0.63%  | 4.798ms -42.16%   | ±1.55% +243.60% |
| PersistentDocumentFactoryBench | bench_create_many | 50  | 10   | 5   | 38.073mb -3.69%  | 22.310ms -67.85%  | ±1.15% +48.26%  |
+--------------------------------+-------------------+-----+------+-----+------------------+-------------------+-----------------+

(I really like that we can rely on real numbers for this!)

As I said already said here, it was a fluke that this kind of code did work before:

        $address = static::addressFactory()
            ->afterInstantiate(
                static function(Address $a): void {
                    static::contactFactory()->create(['address' => $a]);
                }
            )->create();

        self::assertNotNull($address->getContact());

OR

        $category = static::categoryFactory()
            ->afterInstantiate(
                static function(Category $c): void {
                    static::contactFactory()->create(['category' => $c]);
                }
            )
            ->create();

        self::assertCount(1, $category->getContacts());

I'm not totally sure of the magic that was involved, but for the second example, before "flush once" $category->getContacts() was a PersistentCollection with initialized: false, and with "flush once" it became an empty PersistentCollection with initialized: true

Hence all the modifications around this, in PersistentFactoryCollection::normalizeObject()

[kbond]

This'll be great! Are you still working on some edge cases?

[nikophil]

@kbond yes, I still got some failures in my CI, I'll tackle them soon(ish) 😁

[nikophil]

I'm merging this PR in 2.5.x, I'll fix the last quirks on this branch

I'll also surely add make it optional/configurable