Add context to TypeInterface convert methods

CHANGELOG.md

@@ -1,9 +1,10 @@
 # Cycle Typecast Change Log
 
-## 2.2.1 under development
+## 3.0.0 under development
 
 - Chg #7, #8: Change PHP constraint in `composer.json` to `8.1 - 8.4`
 - Chg #8: Bump minimal PHP version to 8.1
+- New #9: Add context to `TypeInterface` convert methods
 
 ## 2.2.0 June 17, 2024
 

src/ArrayToStringType.php

@@ -23,7 +23,7 @@ public function __construct(string $delimiter)
         $this->delimiter = $delimiter;
     }
 
-    public function convertToDatabaseValue(mixed $value): mixed
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed
     {
         if ($value === null) {
             return null;
@@ -37,7 +37,7 @@ public function convertToDatabaseValue(mixed $value): mixed
         return implode($this->delimiter, $value);
     }
 
-    public function convertToPhpValue(mixed $value): mixed
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed
     {
         if ($value === null) {
             return null;

src/AttributeTypecastHandler.php

@@ -28,7 +28,7 @@
             foreach ($reflection->getProperties() as $property) {
                 $attributes = $property->getAttributes(TypeInterface::class, ReflectionAttribute::IS_INSTANCEOF);
                 if (empty($attributes)) {
                     continue;
                 }
                 $this->types[$property->getName()] = $attributes[0]->newInstance();
             }
@@ -42,7 +42,7 @@
                 unset($rules[$key]);
             }
         }
         return $rules;
     }
 
     public function cast(array $data): array
@@ -50,7 +50,10 @@
         /** @psalm-var array<non-empty-string, mixed> $data */
         foreach ($data as $key => $value) {
             if (isset($this->types[$key])) {
-                $data[$key] = $this->types[$key]->convertToPhpValue($value);
+                $data[$key] = $this->types[$key]->convertToPhpValue(
+                    $value,
+                    new CastContext($key, $data),
+                );
             }
         }
         return $data;
@@ -61,7 +64,10 @@
         /** @psalm-var array<non-empty-string, mixed> $data */
         foreach ($data as $key => $value) {
             if (isset($this->types[$key])) {
-                $data[$key] = $this->types[$key]->convertToDatabaseValue($value);
+                $data[$key] = $this->types[$key]->convertToDatabaseValue(
+                    $value,
+                    new UncastContext($key, $data),
+                );
             }
         }
         return $data;

src/CastContext.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Vjik\CycleTypecast;
+
+final class CastContext
+{
+    public function __construct(
+        public readonly string $property,
+        public readonly array $data,
+    ) {}
+}

src/DateTimeImmutable/DateTimeImmutableType.php

@@ -6,11 +6,13 @@
 
 use DateTimeImmutable;
 use InvalidArgumentException;
+use Vjik\CycleTypecast\CastContext;
 use Vjik\CycleTypecast\TypeInterface;
+use Vjik\CycleTypecast\UncastContext;
 
 abstract class DateTimeImmutableType implements TypeInterface
 {
-    public function convertToDatabaseValue(mixed $value): mixed
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed
     {
         if ($value === null) {
             return null;
@@ -25,7 +27,7 @@ public function convertToDatabaseValue(mixed $value): mixed
 
     abstract protected function toDatabaseValue(DateTimeImmutable $value): mixed;
 
-    public function convertToPhpValue(mixed $value): mixed
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed
     {
         if ($value === null) {
             return null;

src/IntegerEnumType.php

@@ -18,7 +18,7 @@ public function __construct(private string $enumClass)
     {
     }
 
-    public function convertToDatabaseValue(mixed $value): mixed
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed
     {
         if ($value === null) {
             return null;
@@ -31,7 +31,7 @@ public function convertToDatabaseValue(mixed $value): mixed
         return $value->value;
     }
 
-    public function convertToPhpValue(mixed $value): mixed
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed
     {
         if ($value === null) {
             return null;

src/StringEnumType.php

@@ -18,7 +18,7 @@ public function __construct(private string $enumClass)
     {
     }
 
-    public function convertToDatabaseValue(mixed $value): mixed
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed
     {
         if ($value === null) {
             return null;
@@ -31,7 +31,7 @@ public function convertToDatabaseValue(mixed $value): mixed
         return $value->value;
     }
 
-    public function convertToPhpValue(mixed $value): mixed
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed
     {
         if ($value === null) {
             return null;

src/TypeInterface.php

@@ -6,7 +6,7 @@
 
 interface TypeInterface
 {
-    public function convertToDatabaseValue(mixed $value): mixed;
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed;
 
-    public function convertToPhpValue(mixed $value): mixed;
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed;
 }

src/Typecaster.php

@@ -4,6 +4,8 @@
 
 namespace Vjik\CycleTypecast;
 
+use function array_key_exists;
+
 final class Typecaster
 {
     /**
@@ -23,8 +25,10 @@ public function prepareAfterExtract(array $data): array
     {
         foreach ($this->config as $column => $type) {
             if (array_key_exists($column, $data)) {
-                /** @var mixed */
-                $data[$column] = $type->convertToDatabaseValue($data[$column]);
+                $data[$column] = $type->convertToDatabaseValue(
+                    $data[$column],
+                    new UncastContext($column, $data),
+                );
             }
         }
         return $data;
@@ -34,8 +38,10 @@ public function prepareBeforeHydrate(array $data): array
     {
         foreach ($this->config as $column => $type) {
             if (array_key_exists($column, $data)) {
-                /** @var mixed */
-                $data[$column] = $type->convertToPhpValue($data[$column]);
+                $data[$column] = $type->convertToPhpValue(
+                    $data[$column],
+                    new CastContext($column, $data),
+                );
             }
         }
         return $data;

src/UncastContext.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Vjik\CycleTypecast;
+
+final class UncastContext
+{
+    public function __construct(
+        public readonly string $property,
+        public readonly array $data,
+    ) {}
+}

src/UuidString/UuidStringType.php

@@ -8,11 +8,13 @@
 use InvalidArgumentException;
 use Ramsey\Uuid\Uuid;
 use Ramsey\Uuid\UuidInterface;
+use Vjik\CycleTypecast\CastContext;
 use Vjik\CycleTypecast\TypeInterface;
+use Vjik\CycleTypecast\UncastContext;
 
 abstract class UuidStringType implements TypeInterface
 {
-    public function convertToDatabaseValue(mixed $value): mixed
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed
     {
         if ($value === null) {
             return null;
@@ -33,7 +35,7 @@ public function convertToDatabaseValue(mixed $value): mixed
 
     abstract protected function toDatabaseValue(UuidInterface $value): mixed;
 
-    public function convertToPhpValue(mixed $value): mixed
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed
     {
         if ($value === null) {
             return null;

tests/ArrayToStringTypeTest.php

@@ -8,6 +8,7 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 use Vjik\CycleTypecast\ArrayToStringType;
+use Vjik\CycleTypecast\Tests\Support\ContextFactory;
 
 final class ArrayToStringTypeTest extends TestCase
 {
@@ -34,23 +35,25 @@ public function testBase(?string $databaseValue, ?array $entityValue): void
     {
         $type = new ArrayToStringType(',');
 
-        $this->assertSame($databaseValue, $type->convertToDatabaseValue($entityValue));
-        $this->assertSame($entityValue, $type->convertToPhpValue($databaseValue));
+        $this->assertSame($databaseValue, $type->convertToDatabaseValue($entityValue, ContextFactory::uncastContext()));
+        $this->assertSame($entityValue, $type->convertToPhpValue($databaseValue, ContextFactory::castContext()));
     }
 
     public function testConvertToDatabaseValueIncorrectValue(): void
     {
         $type = new ArrayToStringType(',');
+        $context = ContextFactory::uncastContext();
 
         $this->expectException(InvalidArgumentException::class);
-        $type->convertToDatabaseValue(42);
+        $type->convertToDatabaseValue(42, $context);
     }
 
-    public function testConertToPhpValueWithIntegerValue(): void
+    public function testConvertToPhpValueWithIntegerValue(): void
     {
         $type = new ArrayToStringType(',');
+        $context = ContextFactory::castContext();
 
         $this->expectException(InvalidArgumentException::class);
-        $type->convertToPhpValue(42);
+        $type->convertToPhpValue(42, $context);
     }
 }

tests/AttributeTypecastHandlerTest.php → tests/AttributeTypecastHandler/AttributeTypecastHandlerTest.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Vjik\CycleTypecast\Tests;
+namespace Vjik\CycleTypecast\Tests\AttributeTypecastHandler;
 
 use Cycle\ORM\SchemaInterface;
 use PHPUnit\Framework\TestCase;

tests/AttributeTypecastHandler/Context/ContextTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Vjik\CycleTypecast\Tests\AttributeTypecastHandler\Context;
+
+use Cycle\ORM\SchemaInterface;
+use PHPUnit\Framework\TestCase;
+use Vjik\CycleTypecast\AttributeTypecastHandler;
+
+use Vjik\CycleTypecast\CastContext;
+use Vjik\CycleTypecast\UncastContext;
+
+use function PHPUnit\Framework\assertInstanceOf;
+use function PHPUnit\Framework\assertSame;
+
+final class ContextTest extends TestCase
+{
+    public function testBase(): void
+    {
+        $schema = $this->createMock(SchemaInterface::class);
+        $schema
+            ->method('define')
+            ->with('role_user', SchemaInterface::ENTITY)
+            ->willReturn(Entity::class);
+
+        $typecastHandler = new AttributeTypecastHandler($schema, 'role_user');
+
+        $context = $typecastHandler->uncast([
+            'id' => '1f2d3897-a226-4eec-bd2c-d0145ef25df9',
+            'name' => 'John',
+        ])['id'];
+        assertInstanceOf(UncastContext::class, $context);
+        assertSame('id', $context->property);
+        assertSame(
+            [
+                'id' => '1f2d3897-a226-4eec-bd2c-d0145ef25df9',
+                'name' => 'John',
+            ],
+            $context->data
+        );
+
+        $context = $typecastHandler->cast([
+            'id' => '2f2d3897-a226-4eec-bd2c-d0145ef25df9',
+            'name' => 'Doe',
+        ])['id'];
+        assertInstanceOf(CastContext::class, $context);
+        assertSame('id', $context->property);
+        assertSame(
+            [
+                'id' => '2f2d3897-a226-4eec-bd2c-d0145ef25df9',
+                'name' => 'Doe',
+            ],
+            $context->data
+        );
+    }
+}

tests/AttributeTypecastHandler/Context/ContextType.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Vjik\CycleTypecast\Tests\AttributeTypecastHandler\Context;
+
+use Attribute;
+use Vjik\CycleTypecast\CastContext;
+use Vjik\CycleTypecast\TypeInterface;
+use Vjik\CycleTypecast\UncastContext;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class ContextType implements TypeInterface
+{
+    public function convertToDatabaseValue(mixed $value, UncastContext $context): mixed
+    {
+        return $context;
+    }
+
+    public function convertToPhpValue(mixed $value, CastContext $context): mixed
+    {
+        return $context;
+    }
+}

tests/AttributeTypecastHandler/Context/Entity.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Vjik\CycleTypecast\Tests\AttributeTypecastHandler\Context;
+
+final class Entity
+{
+    #[ContextType]
+    public string $id = '';
+
+    public string $name = '';
+}