feat: RefuseToMapException, thrown by property mapper if it needs to leave the target property unmapped

.phive/phars.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phive xmlns="https://phar.io/phive">
-  <phar name="php-cs-fixer" version="^3.64.0" installed="3.64.0" location="./tools/php-cs-fixer" copy="false"/>
+  <phar name="php-cs-fixer" version="^3.68.0" installed="3.68.0" location="./tools/php-cs-fixer" copy="false"/>
 </phive>

CHANGELOG.md

@@ -1,9 +1,11 @@
 # CHANGELOG
 
-## 1.13.6
+## 1.14.0
 
 * chore: rector run
 * fix: check file existence before unlinking, suppresses warning
+* feat: `RefuseToMapException`, thrown by property mapper if it needs to leave
+  the target property unmapped
 
 ## 1.13.5
 

src/Exception/RefuseToMapException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of rekalogika/mapper package.
+ *
+ * (c) Priyadi Iman Nurcahyo <https://rekalogika.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Rekalogika\Mapper\Exception;
+
+class RefuseToMapException extends \RuntimeException implements ExceptionInterface {}

src/MapperFactory.php

@@ -225,7 +225,7 @@ public function __construct(
         private readonly ?NormalizerInterface $normalizer = null,
         private readonly ?DenormalizerInterface $denormalizer = null,
         private readonly CacheItemPoolInterface $propertyInfoExtractorCache = new ArrayAdapter(),
-        private readonly LoggerInterface $logger = new NullLogger()
+        private readonly LoggerInterface $logger = new NullLogger(),
     ) {}
 
     /**

src/Transformer/Processor/ObjectProcessor/ObjectProcessor.php

@@ -19,6 +19,7 @@
 use Rekalogika\Mapper\Context\ExtraTargetValues;
 use Rekalogika\Mapper\Context\MapperOptions;
 use Rekalogika\Mapper\Exception\ExceptionInterface;
+use Rekalogika\Mapper\Exception\RefuseToMapException;
 use Rekalogika\Mapper\Exception\UnexpectedValueException;
 use Rekalogika\Mapper\MainTransformer\MainTransformerInterface;
 use Rekalogika\Mapper\ObjectCache\ObjectCache;
@@ -418,7 +419,7 @@ private function generateConstructorArguments(
                 $constructorArguments->addUnsetSourceProperty($sourceProperty);
 
                 continue;
-            } catch (UnsupportedPropertyMappingException) {
+            } catch (UnsupportedPropertyMappingException | RefuseToMapException) {
                 continue;
             }
         }
@@ -581,7 +582,7 @@ private function readSourcePropertyAndWriteTargetProperty(
                 mandatory: false,
                 context: $context,
             );
-        } catch (UninitializedSourcePropertyException | UnsupportedPropertyMappingException) {
+        } catch (UninitializedSourcePropertyException | UnsupportedPropertyMappingException | RefuseToMapException) {
             return $target;
         }
 

tests/config/rekalogika-mapper/generated-mappings.php

@@ -785,65 +785,71 @@
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 244
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 246
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\Bar::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\Baz::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 199
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 201
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\ChildOfSomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\ChildOfSomeObjectDto::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 182
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 184
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\ChildOfSomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectDto::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 241
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 243
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\Foo::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\Baz::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 216
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 218
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\ChildOfSomeObjectDto::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 271
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 273
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\ObjectWithChild1::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 284
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 286
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\ObjectWithChild2::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 165
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 167
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectDto::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 233
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 235
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithConstructorDto::class
     );
 
     $mappingCollection->addObjectMapping(
-        // tests/src/IntegrationTest/PropertyMappingTest.php on line 297
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 299
         source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObject::class,
         target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithDateTimeImmutableDto::class
     );
 
+    $mappingCollection->addObjectMapping(
+        // tests/src/IntegrationTest/PropertyMappingTest.php on line 309
+        source: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithUninitializedVariable::class,
+        target: \Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithUninitializedVariableDto::class
+    );
+
     $mappingCollection->addObjectMapping(
         // tests/src/IntegrationTest/ReadOnlyTest.php on line 27
         source: \Rekalogika\Mapper\Tests\Fixtures\ReadOnly\Source::class,

tests/src/Fixtures/PropertyMapper/SomeObjectWithUninitializedVariable.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of rekalogika/mapper package.
+ *
+ * (c) Priyadi Iman Nurcahyo <https://rekalogika.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Rekalogika\Mapper\Tests\Fixtures\PropertyMapper;
+
+/** @psalm-suppress MissingConstructor */
+class SomeObjectWithUninitializedVariable
+{
+    public string $propertyA;
+}

tests/src/Fixtures/PropertyMapper/SomeObjectWithUninitializedVariableDto.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of rekalogika/mapper package.
+ *
+ * (c) Priyadi Iman Nurcahyo <https://rekalogika.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Rekalogika\Mapper\Tests\Fixtures\PropertyMapper;
+
+/** @psalm-suppress MissingConstructor */
+class SomeObjectWithUninitializedVariableDto
+{
+    public string $propertyA;
+}

tests/src/IntegrationTest/PropertyMappingTest.php

@@ -29,6 +29,8 @@
 use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectDto;
 use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithConstructorDto;
 use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithDateTimeImmutableDto;
+use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithUninitializedVariable;
+use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithUninitializedVariableDto;
 use Rekalogika\Mapper\Tests\Services\PropertyMapper\PropertyMapperWithClassAttribute;
 use Rekalogika\Mapper\Tests\Services\PropertyMapper\PropertyMapperWithClassAttributeWithoutExplicitProperty;
 use Rekalogika\Mapper\Tests\Services\PropertyMapper\PropertyMapperWithConstructorWithClassAttribute;
@@ -298,6 +300,14 @@ public function testExistingUnalterableObject(): void
 
         $this->assertInstanceOf(SomeObjectWithDateTimeImmutableDto::class, $result);
         $this->assertNotSame($originalTargetValue, $result->getProperty());
+    }
+
+    public function testFromUninitializedVariable(): void
+    {
+        $source = new SomeObjectWithUninitializedVariable();
+        $target = new SomeObjectWithUninitializedVariableDto();
+        $result = $this->mapper->map($source, $target);
 
+        $this->assertFalse(isset($result->propertyA));
     }
 }

tests/src/Services/PropertyMapper/PropertyMapperFromUnitializedVariable.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of rekalogika/mapper package.
+ *
+ * (c) Priyadi Iman Nurcahyo <https://rekalogika.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Rekalogika\Mapper\Tests\Services\PropertyMapper;
+
+use Rekalogika\Mapper\Attribute\AsPropertyMapper;
+use Rekalogika\Mapper\Exception\RefuseToMapException;
+use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithUninitializedVariable;
+use Rekalogika\Mapper\Tests\Fixtures\PropertyMapper\SomeObjectWithUninitializedVariableDto;
+
+#[AsPropertyMapper(
+    targetClass: SomeObjectWithUninitializedVariableDto::class,
+)]
+class PropertyMapperFromUnitializedVariable
+{
+    #[AsPropertyMapper('propertyA')]
+    public function mapPropertyA(SomeObjectWithUninitializedVariable $object): string
+    {
+        try {
+            return $object->propertyA;
+        } catch (\Error $e) { // @phpstan-ignore-line
+            if (str_contains($e->getMessage(), 'must not be accessed before initialization')) {
+                throw new RefuseToMapException();
+            }
+
+            throw $e;
+        }
+    }
+}