feat: add support for uuid_extract_timestamp and uuid_extract_version

Author: martin-georgiev

docs/AVAILABLE-FUNCTIONS-AND-OPERATORS.md

@@ -102,6 +102,8 @@ Complete documentation for PostgreSQL ltree (label tree) operations and hierarch
 - `CRC32` - CRC-32 checksum computation
 - `CRC32C` - CRC-32C checksum computation
 - `REVERSE_BYTES` - Reverse byte order for bytea values
+- `UUID_EXTRACT_TIMESTAMP` - Extract timestamp from UUID v1 or v7
+- `UUID_EXTRACT_VERSION` - Extract version number from UUID
 - `UUIDV4` - Explicit UUID version 4 generation
 - `UUIDV7` - Generate timestamp-ordered UUIDs (version 7) for better database performance
 

docs/MATHEMATICAL-FUNCTIONS.md

@@ -36,6 +36,8 @@ This document covers PostgreSQL mathematical, utility, and miscellaneous functio
 | to_char | TO_CHAR | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ToChar` |
 | to_number | TO_NUMBER | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ToNumber` |
 
+**Note**: `TO_NUMBER` supports Roman numeral conversion via the `RN` pattern (PostgreSQL 18+).
+
 ## Utility and Miscellaneous Functions
 
 | PostgreSQL functions | Register for DQL as | Implemented by |
@@ -46,6 +48,8 @@ This document covers PostgreSQL mathematical, utility, and miscellaneous functio
 | reverse (bytea) | REVERSE_BYTES | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ReverseBytes` |
 | row | ROW | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Row` |
 | row_to_json | ROW_TO_JSON | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\RowToJson` |
+| uuid_extract_timestamp | UUID_EXTRACT_TIMESTAMP | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\UuidExtractTimestamp` |
+| uuid_extract_version | UUID_EXTRACT_VERSION | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\UuidExtractVersion` |
 | uuidv4 | UUIDV4 | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Uuidv4` |
 | uuidv7 | UUIDV7 | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Uuidv7` |
 | xmlagg | XML_AGG | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\XmlAgg` |

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/ToNumber.php

@@ -7,7 +7,9 @@
 /**
  * Implementation of PostgreSQL to_number().
  *
- * @see https://www.postgresql.org/docs/17/functions-formatting.html
+ * Supports Roman numeral conversion via RN pattern (PostgreSQL 18+).
+ *
+ * @see https://www.postgresql.org/docs/18/functions-formatting.html
  * @since 3.3.0
  */
 class ToNumber extends BaseFunction

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/UuidExtractTimestamp.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostgreSQL UUID_EXTRACT_TIMESTAMP().
+ *
+ * @see https://www.postgresql.org/docs/17/functions-uuid.html
+ * @since 3.6
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+class UuidExtractTimestamp extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('uuid_extract_timestamp(%s)');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/UuidExtractVersion.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostgreSQL UUID_EXTRACT_VERSION().
+ *
+ * @see https://www.postgresql.org/docs/17/functions-uuid.html
+ * @since 3.6
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+class UuidExtractVersion extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('uuid_extract_version(%s)');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/ToNumberTest.php

@@ -26,6 +26,26 @@ public function tonumber(): void
         $this->assertSame('-12454.8', $result[0]['result']);
     }
 
+    #[Test]
+    public function tonumber_converts_roman_numerals(): void
+    {
+        $this->requirePostgresVersion(180000, 'Roman numeral support in to_number');
+
+        $dql = "SELECT to_number('MCMXCIV', 'RN') as result FROM Fixtures\\MartinGeorgiev\\Doctrine\\Entity\\ContainsTexts t WHERE t.id = 1";
+        $result = $this->executeDqlQuery($dql);
+        $this->assertSame('1994', $result[0]['result']);
+    }
+
+    #[Test]
+    public function tonumber_converts_lowercase_roman_numerals(): void
+    {
+        $this->requirePostgresVersion(180000, 'Roman numeral support in to_number');
+
+        $dql = "SELECT to_number('xlii', 'rn') as result FROM Fixtures\\MartinGeorgiev\\Doctrine\\Entity\\ContainsTexts t WHERE t.id = 1";
+        $result = $this->executeDqlQuery($dql);
+        $this->assertSame('42', $result[0]['result']);
+    }
+
     #[Test]
     public function tonumber_throws_with_invalid_format(): void
     {

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/UuidExtractTimestampTest.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Integration\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\UuidExtractTimestamp;
+use PHPUnit\Framework\Attributes\Test;
+
+class UuidExtractTimestampTest extends NumericTestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->requirePostgresVersion(170000, 'uuid_extract_timestamp function');
+    }
+
+    protected function getStringFunctions(): array
+    {
+        return [
+            'UUID_EXTRACT_TIMESTAMP' => UuidExtractTimestamp::class,
+        ];
+    }
+
+    #[Test]
+    public function can_extract_timestamp_from_uuid_v1(): void
+    {
+        $dql = "SELECT UUID_EXTRACT_TIMESTAMP('a0eebc99-9c0b-11d1-b465-00c04fd430c8') as result
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsNumerics t
+                WHERE t.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $timestamp = $result[0]['result'];
+
+        $this->assertSame('1997-02-03 17:43:12.219+00', $timestamp);
+    }
+
+    #[Test]
+    public function can_extract_timestamp_from_uuid_v7(): void
+    {
+        $dql = "SELECT UUID_EXTRACT_TIMESTAMP('018e7e39-9f42-7000-8000-000000000000') as result
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsNumerics t
+                WHERE t.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $timestamp = $result[0]['result'];
+
+        $this->assertSame('2024-03-15 14:27:30.114+00', $timestamp);
+    }
+
+    #[Test]
+    public function returns_null_for_non_timestamped_uuid(): void
+    {
+        $dql = "SELECT UUID_EXTRACT_TIMESTAMP('550e8400-e29b-41d4-a716-446655440000') as result 
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsNumerics t 
+                WHERE t.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+
+        $this->assertNull($result[0]['result']);
+    }
+}

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/UuidExtractVersionTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Integration\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\UuidExtractVersion;
+use PHPUnit\Framework\Attributes\Test;
+
+class UuidExtractVersionTest extends NumericTestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->requirePostgresVersion(170000, 'uuid_extract_version function');
+    }
+
+    protected function getStringFunctions(): array
+    {
+        return [
+            'UUID_EXTRACT_VERSION' => UuidExtractVersion::class,
+        ];
+    }
+
+    #[Test]
+    public function can_extract_version_from_uuid_v1(): void
+    {
+        $dql = "SELECT UUID_EXTRACT_VERSION('a0eebc99-9c0b-11d1-b465-00c04fd430c8') as result 
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsNumerics t 
+                WHERE t.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+
+        $this->assertSame('1', $result[0]['result']);
+    }
+
+    #[Test]
+    public function can_extract_version_from_uuid_v4(): void
+    {
+        $dql = "SELECT UUID_EXTRACT_VERSION('550e8400-e29b-41d4-a716-446655440000') as result 
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsNumerics t 
+                WHERE t.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+
+        $this->assertSame('4', $result[0]['result']);
+    }
+
+    #[Test]
+    public function can_extract_version_from_uuid_v7(): void
+    {
+        $dql = "SELECT UUID_EXTRACT_VERSION('018e7e39-9f42-7000-8000-000000000000') as result 
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsNumerics t 
+                WHERE t.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+
+        $this->assertSame('7', $result[0]['result']);
+    }
+}

tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/ToNumberTest.php

@@ -22,13 +22,15 @@ protected function getExpectedSqlStatements(): array
     {
         return [
             'converts text to number using format pattern' => "SELECT to_number(c0_.text1, '99G999D9S') AS sclr_0 FROM ContainsTexts c0_",
+            'converts roman numerals to number' => "SELECT to_number(c0_.text1, 'RN') AS sclr_0 FROM ContainsTexts c0_",
         ];
     }
 
     protected function getDqlStatements(): array
     {
         return [
             'converts text to number using format pattern' => \sprintf("SELECT TO_NUMBER(e.text1, '99G999D9S') FROM %s e", ContainsTexts::class),
+            'converts roman numerals to number' => \sprintf("SELECT TO_NUMBER(e.text1, 'RN') FROM %s e", ContainsTexts::class),
         ];
     }
 

tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/UuidExtractTimestampTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsTexts;
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\UuidExtractTimestamp;
+
+class UuidExtractTimestampTest extends TestCase
+{
+    protected function getStringFunctions(): array
+    {
+        return [
+            'UUID_EXTRACT_TIMESTAMP' => UuidExtractTimestamp::class,
+        ];
+    }
+
+    protected function getExpectedSqlStatements(): array
+    {
+        return [
+            'extracts timestamp from uuid' => 'SELECT uuid_extract_timestamp(c0_.text1) AS sclr_0 FROM ContainsTexts c0_',
+        ];
+    }
+
+    protected function getDqlStatements(): array
+    {
+        return [
+            'extracts timestamp from uuid' => \sprintf('SELECT UUID_EXTRACT_TIMESTAMP(e.text1) FROM %s e', ContainsTexts::class),
+        ];
+    }
+}