Add pageDataClass to ComponentPosition with write-side validation (#170)

ComponentPosition now stores pageDataClass (FQCN) alongside pageDataProperty.
Both fields must be set together or both null. ComponentPositionValidator
validates: pageDataClass is a known PageData resource, pageDataProperty is a
component-typed property on that class, and the resolved type is in
allowedComponents if configured. GroupBuilder.pageDataPosition() takes
pageDataClass as its new first argument.

Author: silverbackdan

CLAUDE.md

@@ -317,8 +317,8 @@ class AppScaffold extends AbstractCwaScaffold
         // Blog article template (isTemplate: true, pageDataProperty positions, no route)
         $cwa->page('blog-template', 'BlogPageTemplate', layout: 'main', isTemplate: true, fn(PageBuilder $page) =>
             $page->group('primary', fn(GroupBuilder $g) => $g
-                ->pageDataPosition('image')      // dynamic — resolved from BlogArticleData.image at render time
-                ->pageDataPosition('htmlContent')
+                ->pageDataPosition(BlogArticleData::class, 'image')      // dynamic — resolved from BlogArticleData.image at render time
+                ->pageDataPosition(BlogArticleData::class, 'htmlContent')
             )
         );
 
@@ -332,7 +332,7 @@ class AppScaffold extends AbstractCwaScaffold
         // Topic template (isTemplate: true, pageDataProperty for per-instance intro content)
         $cwa->page('topic-template', 'NestedTopicTemplate', layout: 'main', isTemplate: true, fn(PageBuilder $page) =>
             $page->group('primary', fn(GroupBuilder $g) => $g
-                ->pageDataPosition('introContent')
+                ->pageDataPosition(NestedPageData::class, 'introContent')
             )
         );
 
@@ -412,7 +412,7 @@ PageDataBuilder
 
 GroupBuilder
   ->add(AbstractComponent, ?sort): self              (sort defaults to insertion order × 10)
-  ->pageDataPosition(propertyName, ?sort): self      (creates ComponentPosition with pageDataProperty set)
+  ->pageDataPosition(pageDataClass, propertyName, ?sort): self      (creates ComponentPosition with pageDataClass and pageDataProperty set)
 ```
 
 ### Route auto-generation rules
@@ -576,13 +576,15 @@ Related: Nuxt module issue `components-web-app/cwa-nuxt-module#224` Bug 2.
 
 ---
 
-### #170 — Component group `allowedComponents` does not validate `pageDataProperty` positions on write
+### ~~#170 — Component group `allowedComponents` does not validate `pageDataProperty` positions on write~~ — FIXED
 
-**Read side fixed** (commit `2305ad89`): `ComponentPositionNormalizer.normalizeForPageData()` now skips populating the component if the resolved type is not in `componentGroup.allowedComponents`. Direct-component write-side validation already works via `ComponentPositionValidator`.
+**Read side fixed** (commit `2305ad89`): `ComponentPositionNormalizer.normalizeForPageData()` now skips populating the component if the resolved type is not in `componentGroup.allowedComponents`.
 
-**`pageDataProperty` write-side still open:** When creating a `ComponentPosition` with `pageDataProperty` set, no validation is done against `allowedComponents`. The property name is just a string — the component type isn't known until render time.
+**Write side fixed** (pending commit): `ComponentPosition` now stores a `pageDataClass` (FQCN) alongside `pageDataProperty`. `ComponentPositionValidator` validates the pair on every POST/PATCH: (1) `pageDataClass` must be a known API-registered PageData resource; (2) `pageDataProperty` must be a component-typed property on that class; (3) the resolved component type must be in `componentGroup.allowedComponents` if set. Both fields must be set together (entity-level `Assert\Expression` constraint).
 
-**Agreed plan:** The module must send `pageDataClass` (FQCN of the PageData entity, e.g. `"App\\Entity\\ConferenceData"`) alongside `pageDataProperty` in POST/PATCH. The API can then resolve the property type and validate against `allowedComponents`. Requires coordinated change in both projects. See issue #170 (reopened) and nuxt module CLAUDE.md section on `allowedComponents` for the full spec.
+**`CwaFixtureBuilder` updated:** `GroupBuilder.pageDataPosition()` now takes `pageDataClass` as its first argument: `->pageDataPosition(string $pageDataClass, string $propertyName, ?int $sort = null)`.
+
+**Nuxt module action required:** The module must now send `pageDataClass` alongside `pageDataProperty` in POST/PATCH requests to `/_/component_positions`. See nuxt module CLAUDE.md for the consumer-side spec.
 
 Related Nuxt module issue: `components-web-app/cwa-nuxt-module#151`.
 

features/bootstrap/DoctrineContext.php

@@ -732,6 +732,7 @@ public function theComponentPositionHasTheDynamicReference(string $ref)
         /** @var ComponentPosition $componentPosition */
         $componentPosition = $this->iriConverter->getResourceFromIri($this->restContext->resources['position_0']);
         $componentPosition->setPageDataProperty($ref);
+        $componentPosition->pageDataClass = PageDataWithComponent::class;
         $this->manager->flush();
     }
 
@@ -748,6 +749,7 @@ public function thereIsAPageDataResourceWithRoutePath(?string $path): void
 
         $componentPosition = new ComponentPosition();
         $componentPosition->pageDataProperty = 'component';
+        $componentPosition->pageDataClass = PageDataWithComponent::class;
         $componentPosition->componentGroup = $componentGroup;
         $componentPosition->sortValue = 0;
         $this->timestampedHelper->persistTimestampedFields($componentPosition, true);
@@ -799,6 +801,7 @@ public function thereIsAPageDataWithDraftComponentInPageDataPropertyPosition(str
 
         $componentPosition = new ComponentPosition();
         $componentPosition->pageDataProperty = 'publishableComponent';
+        $componentPosition->pageDataClass = PageDataWithComponent::class;
         $componentPosition->componentGroup = $componentGroup;
         $componentPosition->sortValue = 0;
         $this->timestampedHelper->persistTimestampedFields($componentPosition, true);
@@ -846,6 +849,7 @@ public function thereIsAPageDataWithPublishedComponentInPageDataPropertyPosition
 
         $componentPosition = new ComponentPosition();
         $componentPosition->pageDataProperty = 'publishableComponent';
+        $componentPosition->pageDataClass = PageDataWithComponent::class;
         $componentPosition->componentGroup = $componentGroup;
         $componentPosition->sortValue = 0;
         $this->timestampedHelper->persistTimestampedFields($componentPosition, true);
@@ -894,6 +898,7 @@ public function thereIsAPageDataPropertyPositionWithDisallowedComponentType(stri
 
         $componentPosition = new ComponentPosition();
         $componentPosition->pageDataProperty = 'publishableComponent';
+        $componentPosition->pageDataClass = PageDataWithComponent::class;
         $componentPosition->componentGroup = $componentGroup;
         $componentPosition->sortValue = 0;
         $this->timestampedHelper->persistTimestampedFields($componentPosition, true);
@@ -942,6 +947,7 @@ public function thereIsAPageDataPropertyPositionWithAllowedComponentType(string
 
         $componentPosition = new ComponentPosition();
         $componentPosition->pageDataProperty = 'component';
+        $componentPosition->pageDataClass = PageDataWithComponent::class;
         $componentPosition->componentGroup = $componentGroup;
         $componentPosition->sortValue = 0;
         $this->timestampedHelper->persistTimestampedFields($componentPosition, true);
@@ -1132,8 +1138,10 @@ public function abstractThereIsADummyComponentInPageDataAndAPosition(AbstractCom
 
         if ($dummyComponent instanceof DummyComponent) {
             $componentPosition->pageDataProperty = 'component';
+            $componentPosition->pageDataClass = PageDataWithComponent::class;
         } elseif ($dummyComponent instanceof DummyPublishableComponent) {
             $componentPosition->pageDataProperty = 'publishableComponent';
+            $componentPosition->pageDataClass = PageDataWithComponent::class;
         }
 
         $this->restContext->resources['page_data_component'] = $this->iriConverter->getIriFromResource($dummyComponent);

features/main/component_position.feature

@@ -158,3 +158,68 @@ Feature: Component positions
     And I send a "GET" request to the resource "position_2"
     And the response status code should be 200
     And the JSON node "sortValue" should be equal to the number 2
+
+  @loginUser
+  Scenario: Cannot create a dynamic position with pageDataProperty but no pageDataClass
+    Given there is a ComponentGroup with 0 components
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataProperty |
+      | resource[component_group] | component        |
+    Then the response status code should be 422
+
+  @loginUser
+  Scenario: Cannot create a dynamic position with pageDataClass but no pageDataProperty
+    Given there is a ComponentGroup with 0 components
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataClass                                                                           |
+      | resource[component_group] | Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent |
+    Then the response status code should be 422
+
+  @loginUser
+  Scenario: Cannot create a dynamic position with a pageDataClass that is not a known PageData resource
+    Given there is a ComponentGroup with 0 components
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataProperty | pageDataClass         |
+      | resource[component_group] | component        | App\NotAPageDataClass |
+    Then the response status code should be 422
+
+  @loginUser
+  Scenario: Cannot create a dynamic position where pageDataProperty is not a component-typed property on the pageDataClass
+    Given there is a ComponentGroup with 0 components
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataProperty | pageDataClass                                                                           |
+      | resource[component_group] | notAProperty     | Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent |
+    Then the response status code should be 422
+
+  @loginUser
+  Scenario: Cannot create a dynamic position where the resolved component type is not in allowedComponents
+    Given there is a ComponentGroup with 0 components
+    And the ComponentGroup has the allowedComponent "/component/dummy_components"
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataProperty     | pageDataClass                                                                           |
+      | resource[component_group] | publishableComponent | Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent |
+    Then the response status code should be 422
+
+  @loginUser
+  Scenario: Can create a dynamic position with a valid pageDataClass and pageDataProperty
+    Given there is a ComponentGroup with 0 components
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataProperty | pageDataClass                                                                           |
+      | resource[component_group] | component        | Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent |
+    Then the response status code should be 201
+
+  @loginUser
+  Scenario: Can create a dynamic position where the component type matches allowedComponents
+    Given there is a ComponentGroup with 0 components
+    And the ComponentGroup has the allowedComponent "/component/dummy_components"
+    When I send a "POST" request to "/_/component_positions" with data:
+      | componentGroup            | pageDataProperty | pageDataClass                                                                           |
+      | resource[component_group] | component        | Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent |
+    Then the response status code should be 201
+
+  @loginAdmin
+  Scenario: An admin can read pageDataClass from a dynamic position
+    Given there is a PageData resource with the route path "/page-data"
+    When I send a "GET" request to the resource "component_position"
+    Then the response status code should be 200
+    And the JSON node "pageDataClass" should be equal to "Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent"

features/main/dynamic_page.feature

@@ -72,6 +72,7 @@ Feature: Dynamic pages
     When I send a "GET" request to the resource "component_position"
     Then the response status code should be 200
     And the JSON node "pageDataProperty" should be equal to "component"
+    And the JSON node "pageDataClass" should be equal to "Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent"
     And the JSON node "component" should be null
 
   @loginAdmin
@@ -81,6 +82,7 @@ Feature: Dynamic pages
     When I send a "GET" request to the resource "component_position"
     Then the response status code should be 200
     And the JSON node "pageDataProperty" should be equal to "component"
+    And the JSON node "pageDataClass" should be equal to "Silverback\ApiComponentsBundle\Tests\Functional\TestBundle\Entity\PageDataWithComponent"
     And the JSON node "component" should be null
 
   Scenario: A published pageDataProperty component is returned for anonymous users

src/Entity/Core/ComponentPosition.php

@@ -32,7 +32,11 @@
 #[AcbAssert\ComponentPosition]
 #[Assert\Expression(
     '!(this.component == null & this.pageDataProperty == null)',
-    message: 'Please specify either a component or pageDataProperty.',
+    message: 'Please specify either a component or both pageDataProperty and pageDataClass.',
+)]
+#[Assert\Expression(
+    '!(this.pageDataProperty != null & this.pageDataClass == null) && !(this.pageDataProperty == null & this.pageDataClass != null)',
+    message: 'pageDataProperty and pageDataClass must both be set or both be null.',
 )]
 class ComponentPosition
 {
@@ -54,6 +58,10 @@ class ComponentPosition
     #[Groups(['ComponentPosition:read:role_admin', 'ComponentPosition:write'])]
     public ?string $pageDataProperty = null;
 
+    #[ORM\Column(name: 'page_data_class', nullable: true)]
+    #[Groups(['ComponentPosition:read:role_admin', 'ComponentPosition:write'])]
+    public ?string $pageDataClass = null;
+
     #[ORM\Column(name: 'sort_value', type: 'integer')]
     #[Assert\NotNull]
     #[Groups(['ComponentPosition:read', 'ComponentPosition:write', 'AbstractComponent:cwa_resource:write'])]

src/Fixture/Builder/GroupBuilder.php

@@ -36,9 +36,9 @@ public function add(AbstractComponent $component, ?int $sort = null): self
         return $this;
     }
 
-    public function pageDataPosition(string $propertyName, ?int $sort = null): self
+    public function pageDataPosition(string $pageDataClass, string $propertyName, ?int $sort = null): self
     {
-        $this->pageDataPositions[] = ['property' => $propertyName, 'sort' => $sort ?? $this->nextSort];
+        $this->pageDataPositions[] = ['class' => $pageDataClass, 'property' => $propertyName, 'sort' => $sort ?? $this->nextSort];
         $this->nextSort += 10;
 
         return $this;

src/Fixture/CwaFixtureBuilder.php

@@ -510,6 +510,7 @@ private function createPositions(GroupBuilder $groupBuilder): bool
             $position = new ComponentPosition();
             $position->sortValue = $item['sort'];
             $position->pageDataProperty = $item['property'];
+            $position->pageDataClass = $item['class'];
             $position->componentGroup = $componentGroup;
             $this->timestampedPersister->persistTimestampedFields($position, true);
             $this->manager->persist($position);

src/Resources/config/services.php

@@ -342,6 +342,7 @@
         ->class(ComponentPositionValidator::class)
         ->args([
             new Reference(IriConverterInterface::class),
+            new Reference('silverback.metadata_provider.page_data'),
         ])
         ->tag('validator.constraint_validator');
     $services->alias(ComponentPositionValidator::class, 'silverback.api_components.validator.component_position');

src/Validator/Constraints/ComponentPosition.php

@@ -23,6 +23,8 @@ class ComponentPosition extends Constraint
 {
     public string $message = 'The IRI `{{ iri }}` is not permitted to be added to the collection `{{ reference }}`. Allowed IRIs: {{ allowed }}';
     public string $restrictedMessage = 'The IRI `{{ iri }}` must be specifically allowed within the collection {{ reference }}';
+    public string $invalidPageDataClassMessage = '`{{ class }}` is not a known PageData resource class';
+    public string $invalidPageDataPropertyMessage = '`{{ property }}` is not a component-typed property on `{{ class }}`';
 
     public function getTargets(): string|array
     {