Introduce UUID behavior

composer.json

@@ -13,7 +13,8 @@
     "php": ">=8.2",
     "ext-pdo": "*",
     "ipl/sql": ">=0.9.1",
-    "ipl/stdlib": ">=0.15.0"
+    "ipl/stdlib": ">=0.15.0",
+    "ramsey/uuid": "^4.9.2"
   },
   "require-dev": {
     "ext-pdo_sqlite": "*",

src/Behavior/UUID.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace ipl\Orm\Behavior;
+
+use ipl\Orm\Contract\PropertyBehavior;
+use ipl\Orm\Contract\QueryAwareBehavior;
+use ipl\Orm\Exception\ValueConversionException;
+use ipl\Orm\Query;
+use ipl\Sql\Adapter\Pgsql;
+use ipl\Sql\ExpressionInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
+use Ramsey\Uuid\Uuid as RamseyUuid;
+use Ramsey\Uuid\UuidInterface;
+use UnexpectedValueException;
+
+class UUID extends PropertyBehavior implements QueryAwareBehavior
+{
+    /** @var bool Whether the query is using a pgsql adapter */
+    protected bool $isPostgres = true;
+
+    public function fromDb($value, $key, $_)
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if (! is_string($value)) {
+            throw new UnexpectedValueException(sprintf("Unexpected value '%s' for key '%s'", $value, $key));
+        }
+
+        try {
+            if (! $this->isPostgres) {
+                return RamseyUuid::fromBytes($value);
+            }
+
+            return RamseyUuid::fromString($value);
+        } catch (InvalidArgumentException $e) {
+            throw new ValueConversionException($e->getMessage());
+        }
+    }
+
+    public function toDb($value, $key, $_)
+    {
+        if ($value === null || $value instanceof ExpressionInterface) {
+            return $value;
+        }
+
+        if (! $value instanceof UuidInterface) {
+            if (! is_string($value)) {
+                throw new UnexpectedValueException(sprintf("Unexpected value '%s' for key '%s'", $value, $key));
+            }
+
+            try {
+                $value = RamseyUuid::fromString($value);
+            } catch (InvalidArgumentException $_) {
+                throw new ValueConversionException(sprintf("Invalid UUID value provided: %s", $value));
+            }
+        }
+
+        if (! $this->isPostgres) {
+            return $value->getBytes();
+        }
+
+        return $value->toString();
+    }
+
+    public function setQuery(Query $query)
+    {
+        $this->isPostgres = $query->getDb()->getAdapter() instanceof Pgsql;
+
+        return $this;
+    }
+}

src/Contract/QueryAwareBehavior.php

@@ -10,7 +10,7 @@ interface QueryAwareBehavior extends Behavior
     /**
      * Set the query
      *
-     * @param Query $query
+     * @param Query<*> $query
      *
      * @return $this
      */

tests/Behavior/UUIDTest.php

@@ -0,0 +1,109 @@
+<?php
+
+namespace ipl\Tests\Orm\Behavior;
+
+use ipl\Orm\Behavior\UUID;
+use ipl\Orm\Exception\ValueConversionException;
+use ipl\Orm\Query;
+use ipl\Sql\Connection;
+use ipl\Tests\Orm\TestConnection;
+use PHPUnit\Framework\TestCase;
+use Ramsey\Uuid\Uuid as RamseyUuid;
+use UnexpectedValueException;
+
+class UUIDTest extends TestCase
+{
+    protected const TEST_COLUMN = 'column';
+
+    protected const TEST_UUID_VALUE = '020ed4e8-0fb3-4a98-8235-4aa2341cf1f9';
+
+    public function testRetrievePropertyReturnsNullWhenValueIsNull(): void
+    {
+        $this->assertNull($this->behavior()->retrieveProperty(null, static::TEST_COLUMN));
+        $this->assertNull($this->behavior(true)->retrieveProperty(null, static::TEST_COLUMN));
+    }
+
+    public function testRetrievePropertyReturnsUuidInstance(): void
+    {
+        $this->assertSame(
+            static::TEST_UUID_VALUE,
+            (string) $this->behavior()->retrieveProperty(
+                RamseyUuid::fromString(static::TEST_UUID_VALUE)->getBytes(),
+                static::TEST_COLUMN,
+            )
+        );
+        $this->assertSame(
+            static::TEST_UUID_VALUE,
+            (string) $this->behavior(true)->retrieveProperty(static::TEST_UUID_VALUE, static::TEST_COLUMN)
+        );
+    }
+
+    public function testPersistPropertyReturnsNullWhenValueIsNull(): void
+    {
+        $this->assertNull($this->behavior()->persistProperty(null, static::TEST_COLUMN));
+        $this->assertNull($this->behavior(true)->persistProperty(null, static::TEST_COLUMN));
+    }
+
+    public function testPersistPropertyReturnsValidValueFromString(): void
+    {
+        $uuid = RamseyUuid::fromString(static::TEST_UUID_VALUE);
+        $this->assertSame(
+            $uuid->getBytes(),
+            $this->behavior()->persistProperty(static::TEST_UUID_VALUE, static::TEST_COLUMN)
+        );
+        $this->assertSame(
+            static::TEST_UUID_VALUE,
+            $this->behavior(true)->persistProperty(static::TEST_UUID_VALUE, static::TEST_COLUMN)
+        );
+    }
+
+    public function testPersistPropertyReturnsValidValueFromUuid(): void
+    {
+        $uuid = RamseyUuid::fromString(static::TEST_UUID_VALUE);
+        $this->assertSame(
+            $uuid->getBytes(),
+            $this->behavior()->persistProperty($uuid, static::TEST_COLUMN)
+        );
+        $this->assertSame(
+            static::TEST_UUID_VALUE,
+            $this->behavior(true)->persistProperty($uuid, static::TEST_COLUMN),
+        );
+    }
+
+    public function testRetrievePropertyThrowsWithInvalidValueType(): void
+    {
+        $this->expectException(UnexpectedValueException::class);
+        $this->behavior()->retrieveProperty(true, static::TEST_COLUMN);
+        $this->behavior(true)->retrieveProperty(false, static::TEST_COLUMN);
+    }
+
+    public function testPersistPropertyThrowsWithInvalidValueType(): void
+    {
+        $this->expectException(UnexpectedValueException::class);
+        $this->behavior()->persistProperty(true, static::TEST_COLUMN);
+        $this->behavior(true)->persistProperty(false, static::TEST_COLUMN);
+    }
+
+    public function testRetrievePropertyThrowsWithInvalidUuid(): void
+    {
+        $this->expectException(ValueConversionException::class);
+        $this->behavior()->retrieveProperty('something', static::TEST_COLUMN);
+        $this->behavior(true)->retrieveProperty('something', static::TEST_COLUMN);
+    }
+
+    public function testPersistPropertyThrowsWithInvalidUuid(): void
+    {
+        $this->expectException(ValueConversionException::class);
+        $this->behavior()->persistProperty('something', static::TEST_COLUMN);
+        $this->behavior(true)->persistProperty('something', static::TEST_COLUMN);
+    }
+
+    protected function behavior(bool $postgres = false): UUID
+    {
+        return (new UUID([static::TEST_COLUMN]))
+            ->setQuery(
+                (new Query())
+                    ->setDb($postgres ? new Connection(['db' => 'pgsql']) : new TestConnection())
+            );
+    }
+}