fix(serializer): clarify nested-document error with actionable hints

src/Serializer/AbstractItemNormalizer.php

@@ -756,7 +756,7 @@ protected function denormalizeRelation(string $attributeName, ApiProperty $prope
             throw NotNormalizableValueException::createForUnexpectedDataType(\sprintf('The type of the "%s" attribute must be "array" (nested document) or "string" (IRI), "%s" given.', $attributeName, \gettype($value)), $value, ['array', 'string'], $context['deserialization_path'] ?? null, true);
         }
 
-        throw NotNormalizableValueException::createForUnexpectedDataType(\sprintf('Nested documents for attribute "%s" are not allowed. Use IRIs instead.', $attributeName), $value, ['array', 'string'], $context['deserialization_path'] ?? null, true);
+        throw NotNormalizableValueException::createForUnexpectedDataType(\sprintf('Nested documents for attribute "%s" are not allowed. Provide an IRI, or enable nested writes by adding matching denormalization groups on the related resource (and, for to-many relations, define adder/remover methods on the parent class).', $attributeName), $value, ['array', 'string'], $context['deserialization_path'] ?? null, true);
     }
 
     private function getResourceFromIri(string $data, array $context, string $resourceClass): ?object

src/Serializer/Tests/AbstractItemNormalizerTest.php

@@ -1422,7 +1422,7 @@ public function testDeserializationPathForNotFoundResource(): void
     public function testInnerDocumentNotAllowed(): void
     {
         $this->expectException(UnexpectedValueException::class);
-        $this->expectExceptionMessage('Nested documents for attribute "relatedDummy" are not allowed. Use IRIs instead.');
+        $this->expectExceptionMessage('Nested documents for attribute "relatedDummy" are not allowed. Provide an IRI, or enable nested writes by adding matching denormalization groups on the related resource (and, for to-many relations, define adder/remover methods on the parent class).');
 
         $data = [
             'relatedDummy' => [

tests/Functional/Hal/ProblemTest.php

@@ -71,7 +71,7 @@ public function testNestedRelationDocumentReturns400Problem(): void
         $body = $response->toArray(false);
         $this->assertSame('/errors/400', $body['type']);
         $this->assertSame('An error occurred', $body['title']);
-        $this->assertSame('Nested documents for attribute "relatedDummy" are not allowed. Use IRIs instead.', $body['detail']);
+        $this->assertSame('Nested documents for attribute "relatedDummy" are not allowed. Provide an IRI, or enable nested writes by adding matching denormalization groups on the related resource (and, for to-many relations, define adder/remover methods on the parent class).', $body['detail']);
         $this->assertArrayHasKey('trace', $body);
     }
 }