Add Database::close() for explicit lifecycle management

rector.php

@@ -31,6 +31,7 @@
         AddMethodCallBasedStrictParamTypeRector::class,
         StaticCallOnNonStaticToInstanceCallRector::class,
         ReadOnlyClassRector::class => [
+            __DIR__ . '/src/Database.php',
             __DIR__ . '/src/Transaction.php',
             __DIR__ . '/src/NativeClient.php',
         ],

src/Database.php

@@ -9,16 +9,31 @@
 use FFI;
 use FFI\CData;
 
-final readonly class Database implements Transactor, ReadTransactor
+final class Database implements Transactor, ReadTransactor
 {
+    private bool $closed = false;
+
     public function __construct(
-        private CData $dpointer,
-        private NativeClient $client,
+        private readonly CData $dpointer,
+        private readonly NativeClient $client,
     ) {
     }
 
+    public function close(): void
+    {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->client->fdb->fdb_database_destroy($this->dpointer);
+        $this->closed = true;
+        FoundationDB::removeDatabase($this);
+    }
+
     public function createTransaction(): Transaction
     {
+        $this->ensureOpen();
+
         $trPointer = $this->client->fdb->new('FDBTransaction*');
         $this->client->checkError(
             $this->client->fdb->fdb_database_create_transaction($this->dpointer, FFI::addr($trPointer)),
@@ -29,6 +44,8 @@ public function createTransaction(): Transaction
 
     public function openTenant(string $name): Tenant
     {
+        $this->ensureOpen();
+
         $tpointer = $this->client->fdb->new('FDBTenant*');
         $this->client->checkError(
             $this->client->fdb->fdb_database_open_tenant(
@@ -346,6 +363,15 @@ public function getClient(): NativeClient
 
     public function __destruct()
     {
-        $this->client->fdb->fdb_database_destroy($this->dpointer);
+        if (!$this->closed) {
+            $this->client->fdb->fdb_database_destroy($this->dpointer);
+        }
+    }
+
+    private function ensureOpen(): void
+    {
+        if ($this->closed) {
+            throw new \LogicException('Database has been closed');
+        }
     }
 }

src/FoundationDB.php

@@ -115,6 +115,16 @@ public static function openWithConnectionString(string $connectionString): Datab
         return $database;
     }
 
+    /** @internal */
+    public static function removeDatabase(Database $database): void
+    {
+        foreach (self::$databases as $key => $cached) {
+            if ($cached === $database) {
+                unset(self::$databases[$key]);
+            }
+        }
+    }
+
     /** @internal */
     public static function reset(): void
     {

tests/Integration/DatabaseCloseTest.php

@@ -0,0 +1,116 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CrazyGoat\FoundationDB\Tests\Integration;
+
+use CrazyGoat\FoundationDB\Database;
+use CrazyGoat\FoundationDB\FoundationDB;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class DatabaseCloseTest extends TestCase
+{
+    private static bool $initialized = false;
+
+    protected function setUp(): void
+    {
+        if (!self::$initialized) {
+            FoundationDB::reset();
+            FoundationDB::apiVersion(730);
+            self::$initialized = true;
+        }
+    }
+
+    #[Test]
+    public function closeReleasesDatabase(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+
+        $db2 = FoundationDB::open();
+        self::assertInstanceOf(Database::class, $db2);
+
+        $db2->set('test/close_key', 'value');
+        self::assertSame('value', $db2->get('test/close_key'));
+        $db2->clear('test/close_key');
+    }
+
+    #[Test]
+    public function closedDatabaseThrowsOnCreateTransaction(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('closed');
+        $db->createTransaction();
+    }
+
+    #[Test]
+    public function closedDatabaseThrowsOnGet(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('closed');
+        $db->get('key');
+    }
+
+    #[Test]
+    public function closedDatabaseThrowsOnSet(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('closed');
+        $db->set('key', 'value');
+    }
+
+    #[Test]
+    public function closedDatabaseThrowsOnTransact(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('closed');
+        $db->transact(fn (): null => null);
+    }
+
+    #[Test]
+    public function closedDatabaseThrowsOnOpenTenant(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('closed');
+        $db->openTenant('test');
+    }
+
+    #[Test]
+    public function doubleCloseIsNoOp(): void
+    {
+        $db = FoundationDB::open();
+        $db->close();
+        $db->close();
+
+        $db2 = FoundationDB::open();
+        self::assertInstanceOf(Database::class, $db2);
+        $db2->close();
+    }
+
+    #[Test]
+    public function reopenAfterCloseReturnsNewInstance(): void
+    {
+        $db1 = FoundationDB::open();
+        $db1->close();
+
+        $db2 = FoundationDB::open();
+        self::assertNotSame($db1, $db2);
+        $db2->close();
+    }
+}