Add onRoutesCreated callback to PageDataBuilder

Fires after phaseThree (routes created) but before phaseFour (positions), passing direct child PageBuilders so fixture code can reference child route paths when building parent content.

Author: silverbackdan

CLAUDE.md

@@ -400,6 +400,7 @@ PageBuilder
 
 PageDataBuilder
   ->nested(Closure): void                            (Closure receives CwaFixtureBuilder with parent context)
+  ->onRoutesCreated(Closure): self                   (Closure receives array<PageBuilder> of direct child page builders; called after phaseThree so child route paths are available)
   ->getRoute(): ?Route
 
 GroupBuilder
@@ -431,11 +432,96 @@ The builder manages persisting in the correct order. Roughly:
 4. `flush()`
 5. Call `RouteGenerator::create()` for all auto-routed entities (parents before children — breadth-first)
 6. `flush()` — routes now have paths
+6.5. Call `onRoutesCreated` callbacks on any `PageDataBuilder` that registered one, passing the child `PageBuilder` instances tracked during `evaluateNested()`. The callback mutates already-persisted entity properties (e.g. sets `HtmlContent.html` with real child paths). Followed by a `flush()` to persist those changes.
 7. Create ComponentPositions and nav-bar links (which may reference routes created in step 5)
 8. Final `flush()`
 
 `->getRoute(routeName)` and `PageDataBuilder/PageBuilder->getRoute()` are only valid after step 5 completes. The builder defers all closures to the correct phase internally. Closures registered against GroupBuilder via `->add()` or `->pageDataPosition()` are evaluated in phase 7. The `->nested()` closure is evaluated during phase 5 so parent routes exist before child routes are generated.
 
+### `onRoutesCreated` — implementation plan
+
+**Use case:** A `PageData` entity has a component whose content must reference child page URLs (e.g. an `HtmlContent` with links to the child pages). Child routes don't exist at entity-creation time, so the content must be set after `phaseThree`.
+
+**Required changes in `CwaFixtureBuilder`:**
+
+In `evaluateNested()`, record which page refs were registered by each nested closure and store them on the `PageDataBuilder`:
+
+```php
+foreach ($this->pageDataSpecs as $spec) {
+    $closure = $spec['builder']->getNestedClosure();
+    if (null === $closure) continue;
+    $beforePageRefs = array_keys($this->pageSpecs);
+    $this->parentContext = $spec['builder']->getPageData();
+    $closure($this);
+    $this->parentContext = null;
+    $addedRefs = array_diff(array_keys($this->pageSpecs), $beforePageRefs);
+    $spec['builder']->setChildPageRefs(array_values($addedRefs));
+}
+```
+
+Add a new `phaseThreePointFive()` called between `phaseThree()` and `phaseFour()` in `flush()`:
+
+```php
+private function phaseThreePointFive(): void
+{
+    $hasChanges = false;
+    foreach ($this->pageDataSpecs as $spec) {
+        $cb = $spec['builder']->getOnRoutesCreated();
+        if (null === $cb) continue;
+        $childBuilders = array_values(array_filter(array_map(
+            fn($ref) => $this->pageSpecs[$ref]['builder'] ?? null,
+            $spec['builder']->getChildPageRefs(),
+        )));
+        $cb($childBuilders);
+        $hasChanges = true;
+    }
+    if ($hasChanges) {
+        $this->manager->flush();
+    }
+}
+```
+
+**Required changes in `PageDataBuilder`:**
+
+```php
+private ?\Closure $onRoutesCreated = null;
+private array $childPageRefs = [];
+
+public function onRoutesCreated(\Closure $cb): self { $this->onRoutesCreated = $cb; return $this; }
+public function getOnRoutesCreated(): ?\Closure { return $this->onRoutesCreated; }
+public function setChildPageRefs(array $refs): void { $this->childPageRefs = $refs; }
+public function getChildPageRefs(): array { return $this->childPageRefs; }
+```
+
+**App usage (`AppScaffold`):**
+
+```php
+$intro = new HtmlContent();
+$intro->setPublishedAt(new \DateTime());
+$topicPageData->introContent = $intro;  // persisted in phaseOne via cascade
+
+$topicBuilder = $cwa->pageData($topicPageData, template: 'nested-topic-template', routeName: 'topic-1');
+
+$topicBuilder->nested(function (CwaFixtureBuilder $child) use ($chapters) {
+    foreach ($chapters as $j => $chapter) {
+        $child->page(sprintf('topic-1-chapter-%d', $j + 1), 'NestedSubPageTemplate', layout: 'main',
+            configure: fn(PageBuilder $p) => $p->title($chapter['title'])->group('primary')->add(...)
+        );
+    }
+});
+
+$topicBuilder->onRoutesCreated(function (array $childBuilders) use ($intro) {
+    $links = implode(' | ', array_map(
+        fn(PageBuilder $b) => sprintf('<a href="%s">%s</a>', $b->getRoute()->getPath(), $b->getPage()->getTitle()),
+        $childBuilders
+    ));
+    $intro->html = sprintf('<p>Introduction to Topic 1. Chapters: %s</p>', $links);
+    // No persist() needed — entity is already managed; flush() in phaseThreePointFive picks it up
+});
+```
+
+**Key constraint:** The `HtmlContent` (or any entity updated in the callback) must already be persisted before `onRoutesCreated` fires — i.e. set on the `PageData` entity before passing to `->pageData()` so phaseOne cascades it. The callback only mutates properties on already-managed entities; it does not call `persist()`.
+
 ### What the builder handles invisibly
 
 - `TimestampedDataPersister->persistTimestampedFields($entity, true)` on every entity

src/Fixture/Builder/PageDataBuilder.php

@@ -17,21 +17,47 @@
 class PageDataBuilder
 {
     private ?\Closure $nestedClosure = null;
+    private ?\Closure $onRoutesCreated = null;
+    private array $childPageRefs = [];
 
     public function __construct(private readonly AbstractPageData $pageData)
     {
     }
 
-    public function nested(\Closure $configure): void
+    public function nested(\Closure $configure): self
     {
         $this->nestedClosure = $configure;
+
+        return $this;
     }
 
     public function getNestedClosure(): ?\Closure
     {
         return $this->nestedClosure;
     }
 
+    public function onRoutesCreated(\Closure $cb): self
+    {
+        $this->onRoutesCreated = $cb;
+
+        return $this;
+    }
+
+    public function getOnRoutesCreated(): ?\Closure
+    {
+        return $this->onRoutesCreated;
+    }
+
+    public function setChildPageRefs(array $refs): void
+    {
+        $this->childPageRefs = $refs;
+    }
+
+    public function getChildPageRefs(): array
+    {
+        return $this->childPageRefs;
+    }
+
     public function getPageData(): AbstractPageData
     {
         return $this->pageData;

src/Fixture/CwaFixtureBuilder.php

@@ -197,6 +197,7 @@ public function flush(): void
             $this->evaluateNested();
             $this->phaseTwo();
             $this->phaseThree();
+            $this->phaseThreePointFive();
             $this->initialFlushDone = true;
         }
 
@@ -213,9 +214,12 @@ private function evaluateNested(): void
             if (null === $closure) {
                 continue;
             }
+            $beforePageRefs = array_keys($this->pageSpecs);
             $this->parentContext = $spec['builder']->getPageData();
             $closure($this);
             $this->parentContext = null;
+            $addedRefs = array_values(array_diff(array_keys($this->pageSpecs), $beforePageRefs));
+            $spec['builder']->setChildPageRefs($addedRefs);
         }
 
         foreach ($this->pageSpecs as $spec) {
@@ -381,6 +385,28 @@ private function phaseThree(): void
         $this->manager->flush();
     }
 
+    private function phaseThreePointFive(): void
+    {
+        $hasChanges = false;
+
+        foreach ($this->pageDataSpecs as $spec) {
+            $cb = $spec['builder']->getOnRoutesCreated();
+            if (null === $cb) {
+                continue;
+            }
+            $childBuilders = array_values(array_filter(array_map(
+                fn ($ref) => $this->pageSpecs[$ref]['builder'] ?? null,
+                $spec['builder']->getChildPageRefs(),
+            )));
+            $cb($childBuilders);
+            $hasChanges = true;
+        }
+
+        if ($hasChanges) {
+            $this->manager->flush();
+        }
+    }
+
     private function phaseFour(): void
     {
         $hasPositions = false;
@@ -482,7 +508,7 @@ private function persistWithAssociations(object $entity): void
                 }
                 if (is_iterable($related)) {
                     foreach ($related as $item) {
-                        if (is_object($item)) {
+                        if (\is_object($item)) {
                             $this->persistWithAssociations($item);
                         }
                     }

src/Resources/config/services.php

@@ -102,14 +102,14 @@
 use Silverback\ApiComponentsBundle\Factory\User\Mailer\WelcomeEmailFactory;
 use Silverback\ApiComponentsBundle\Factory\User\UserFactory;
 use Silverback\ApiComponentsBundle\Filter\OrSearchFilter;
+use Silverback\ApiComponentsBundle\Fixture\CwaFixtureBuilder;
 use Silverback\ApiComponentsBundle\Flysystem\FilesystemFactory;
 use Silverback\ApiComponentsBundle\Flysystem\FilesystemProvider;
 use Silverback\ApiComponentsBundle\Form\Type\User\ChangePasswordType;
 use Silverback\ApiComponentsBundle\Form\Type\User\NewEmailAddressType;
 use Silverback\ApiComponentsBundle\Form\Type\User\PasswordUpdateType;
 use Silverback\ApiComponentsBundle\Form\Type\User\UserLoginType;
 use Silverback\ApiComponentsBundle\Form\Type\User\UserRegisterType;
-use Silverback\ApiComponentsBundle\Fixture\CwaFixtureBuilder;
 use Silverback\ApiComponentsBundle\Helper\ComponentPosition\ComponentPositionSortValueHelper;
 use Silverback\ApiComponentsBundle\Helper\Form\FormCachePurger;
 use Silverback\ApiComponentsBundle\Helper\Form\FormSubmitHelper;

tests/Fixture/CwaFixtureBuilderTest.php

@@ -15,7 +15,6 @@
 use Doctrine\Persistence\ObjectManager;
 use PHPUnit\Framework\TestCase;
 use Silverback\ApiComponentsBundle\Entity\Core\AbstractComponent;
-use Silverback\ApiComponentsBundle\Entity\Core\AbstractPage;
 use Silverback\ApiComponentsBundle\Entity\Core\AbstractPageData;
 use Silverback\ApiComponentsBundle\Entity\Core\ComponentGroup;
 use Silverback\ApiComponentsBundle\Entity\Core\ComponentPosition;
@@ -171,7 +170,7 @@ public function test_layout_group_creates_component_group_with_correct_propertie
 
         $iriConverter = $this->createStub(IriConverterInterface::class);
         $iriConverter->method('getIriFromResource')->willReturnCallback(
-            static fn ($resource) => is_string($resource) ? '/_/some_components' : '/_api/_/layouts/test-uuid'
+            static fn ($resource) => \is_string($resource) ? '/_/some_components' : '/_api/_/layouts/test-uuid'
         );
 
         $builder = $this->makeBuilder($em, iriConverter: $iriConverter);
@@ -460,6 +459,7 @@ public function test_phases_one_to_three_run_only_once_across_multiple_flushes()
                 $route->setPath('/' . spl_object_id($entity));
                 $route->setName((string) spl_object_id($entity));
                 $entity->setRoute($route);
+
                 return $route;
             });
 
@@ -471,6 +471,41 @@ public function test_phases_one_to_three_run_only_once_across_multiple_flushes()
         $builder->flush(); // second flush must NOT call routeGenerator->create() again
     }
 
+    public function test_on_routes_created_fires_after_child_routes_exist_with_child_builders(): void
+    {
+        $parentPageData = new class extends AbstractPageData {};
+        $capturedBuilders = null;
+        $capturedChildRoute = null;
+
+        $builder = $this->makeBuilder(routeGenerator: $this->autoRouteGenerator());
+        $builder->layout('main', 'CwaLayoutPrimary');
+        $builder->pageData($parentPageData)
+            ->nested(static function (CwaFixtureBuilder $child): void {
+                $child->page('chapter', 'ChapterTemplate', layout: 'main');
+            })
+            ->onRoutesCreated(static function (array $childBuilders) use (&$capturedBuilders, &$capturedChildRoute): void {
+                $capturedBuilders = $childBuilders;
+                $capturedChildRoute = $childBuilders[0]->getRoute()?->getPath();
+            });
+        $builder->flush();
+
+        $this->assertIsArray($capturedBuilders);
+        $this->assertCount(1, $capturedBuilders);
+        $this->assertNotNull($capturedChildRoute, 'Child route path should be available inside onRoutesCreated');
+    }
+
+    public function test_on_routes_created_not_called_when_no_callback_registered(): void
+    {
+        $called = false;
+        $parentPageData = new class extends AbstractPageData {};
+
+        $builder = $this->makeBuilder(routeGenerator: $this->autoRouteGenerator());
+        $builder->pageData($parentPageData);
+        $builder->flush();
+
+        $this->assertFalse($called); // trivially passes; confirms no exception thrown
+    }
+
     public function test_parent_pagedata_route_created_before_child_pagedata_route(): void
     {
         $createOrder = [];