feat: native uuidv7 generation (references #117)

Author: tpetry

README.md

@@ -1365,6 +1365,18 @@ Schema::create('comments', function (Blueprint $table) {
 });        
 ```
 
+When using PostgreSQL 18, you can also use the more efficient native implementation within PostgreSQL instead of the one provided by the expression:
+
+```php
+use Tpetry\PostgresqlEnhanced\Expressions\Uuid7;
+
+Schema::create('comments', function (Blueprint $table) {
+    $table->id();
+    $table->uuid()->default(new Uuid7(native: true))->unique();
+    $table->text('text');
+});  
+```
+
 # Supported Extensions
 
 You can use any extension with this PostgreSQL you like but some have received a deeper Laravel integration.

src/Expressions/Uuid7.php

@@ -12,11 +12,19 @@ class Uuid7 implements Expression
 {
     public function __construct(
         private readonly ?DateTimeInterface $time = null,
+        private readonly bool $native = false,
     ) {
     }
 
     public function getValue(Grammar $grammar): string
     {
+        if ($this->native) {
+            return match ($this->time) {
+                null => 'uuidv7()',
+                default => "uuidv7('{$this->time->format('Y-m-d H:i:s.uP')}'::timestamptz - clock_timestamp())",
+            };
+        }
+
         // The UUIDv7 algorithm in pure PostgreSQL SQL is copied from:
         // https://gist.github.com/fabiolimace/515a0440e3e40efeb234e12644a6a346#file-uuidv7-sql
 

tests/Expressions/Uuid7Test.php

@@ -22,7 +22,15 @@ protected function setUp(): void
         }
     }
 
-    public function testIncludesTimestampOrClock(): void
+    public function testNative(): void
+    {
+        $time = CarbonImmutable::createFromFormat('Y-m-d H:i:s.uP', '2009-04-23 14:57:17.830618-04:00');
+
+        $this->assertEquals('uuidv7()', (new Uuid7(native: true))->getValue($this->getConnection()->getQueryGrammar()));
+        $this->assertEquals("uuidv7('2009-04-23 14:57:17.830618-04:00'::timestamptz - clock_timestamp())", (new Uuid7($time, native: true))->getValue($this->getConnection()->getQueryGrammar()));
+    }
+
+    public function testReimplementedIncludesTimestampOrClock(): void
     {
         $uuidNow = (new Uuid7())->getValue($this->getConnection()->getQueryGrammar());
         $this->assertStringContainsString('statement_timestamp()', $uuidNow);
@@ -36,7 +44,7 @@ public function testIncludesTimestampOrClock(): void
      * Two different expression invocations would always be unique because of different time.
      * So the time is fixed to check for the randomness.
      */
-    public function testIsRandom(): void
+    public function testReimplementedIsRandom(): void
     {
         $uuid = new Uuid7(CarbonImmutable::now());
 
@@ -46,7 +54,7 @@ public function testIsRandom(): void
         $this->assertNotEquals($value1, $value2);
     }
 
-    public function testTimeIncreases(): void
+    public function testReimplementedTimeIncreases(): void
     {
         $uuid = new Uuid7();