[Spamercz]

Problem

EntityFactory resolves every single-entity reference (a property typed as an ElasticEntityInterface whose document stores only the id, or an STIElasticEntity) with EntityManager::find(). That is one ElasticSearch search per distinct referenced document, run one after another.

On colectio.com, the seller order list hydrates 495 CollectionItemElastic documents, each referencing a CollectibleElastic. That came to 462 serial searches. Profiled in production, this one findBy() took 8.9–9.6 s, and the whole request took 16–49 s.

Change

• EntityFactory::collectReferences() walks a hit the way resolveProperties() does and returns the referenced ids per class. Lazy collections (Collection, ElasticCollection) are left out; they resolve their references when first read, and preloadRelations() already covers ElasticCollection.
• EntityManager::createCollection() collects the references of all hits before hydrating. It fetches each class with one terms _id query, in chunks of 1000. Hydration then finds them in the identity map. Because the preload goes through findBy(), preloaded pages preload their own references too: a chain of references costs one query per level.
• The preload skips ids that are already in the identity map, being created, or being preloaded further up (IdentityMap::$preloadingList). This ends cycles such as Title → Image → Title.
• A failed preload is not fatal. Anything it did not load is still fetched with find() during hydration, exactly as before. A missing referenced document still drops the hit that references it.

Measured

On a local colectio.com snapshot: findBy of 500 collection items referencing 363 collectibles, comparing v2.0 with this branch, two runs each.

	collectible searches	findBy + hydrate
v2.0	363	0.61–0.76 s
this branch	1	0.12–0.14 s

The hydrated result is identical (same hash of itemId, collectibleId and name).

Tests

New EntityManager/PreloadReferencesTest.phpt counts real searches on the referenced index through _stats:

• A page of 5 titles loads its 5 images in 1 search. On v2.0 this fails with 5 should be 1.
• A reference shared by several hits resolves to one instance.
• A Title ↔ Image cycle hydrates both sides.
• A reference already in the identity map is not queried again.
• A deleted referenced document still drops the referencing hit.

Full suite run locally against ES 9.2.2: 684 tests. The 32 failures are exactly the same set as on v2.0 (ClearTest, the MatchAll class missing from the installed elastic-query, InsertMultiple, Scroll, …). None are new. PHPStan level 6 is clean, and phpcs is clean on the changed files.

🤖 Generated with Claude Code