From f52896721d07da9097d81e22b4b8b9acd60d05f0 Mon Sep 17 00:00:00 2001
From: loks0n <22452787+loks0n@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:08:20 +0100
Subject: [PATCH] fix: return the mapped document type for an empty id

getDocument() short-circuits on an empty id before it looks the collection
up, and returned a plain Document there even when the collection is mapped
to a subclass with setDocumentType(). Every other empty result (missing row,
denied read, negative cache) already comes back as the mapped class, so a
caller relying on that class, such as an HTTP resource typed to return the
current user or team, hit a TypeError only on the empty-id path.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 src/Database/Database.php            |  2 +-
 tests/unit/EmptyDocumentTypeTest.php | 54 ++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 tests/unit/EmptyDocumentTypeTest.php

diff --git a/src/Database/Database.php b/src/Database/Database.php
index 3f9f92ca9..d7f1a01b2 100644
--- a/src/Database/Database.php
+++ b/src/Database/Database.php
@@ -4911,7 +4911,7 @@ public function getDocument(string $collection, string $id, array $queries = [],
         }
 
         if (empty($id)) {
-            return new Document();
+            return $this->createDocumentInstance($collection, []);
         }
 
         $collection = $this->silent(fn () => $this->getCollection($collection));
diff --git a/tests/unit/EmptyDocumentTypeTest.php b/tests/unit/EmptyDocumentTypeTest.php
new file mode 100644
index 000000000..787c0981f
--- /dev/null
+++ b/tests/unit/EmptyDocumentTypeTest.php
@@ -0,0 +1,54 @@
+<?php
+
+namespace Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Utopia\Cache\Adapter\Memory as CacheMemory;
+use Utopia\Cache\Cache;
+use Utopia\Database\Adapter\Memory as DatabaseMemory;
+use Utopia\Database\Database;
+use Utopia\Database\Document;
+
+class TypedUser extends Document
+{
+}
+
+class EmptyDocumentTypeTest extends TestCase
+{
+    /**
+     * A caller that passes the type hint of the mapped class along (an HTTP
+     * resource returning the current user, say) must be able to rely on every
+     * empty result being that class, including the one for an empty id, which
+     * short-circuits before the collection is even looked up.
+     */
+    public function testEmptyIdReturnsTheMappedDocumentType(): void
+    {
+        $database = new Database(new DatabaseMemory(), new Cache(new CacheMemory()));
+        $database
+            ->setDatabase('utopiaTests')
+            ->setNamespace('empty_type_' . \uniqid());
+        $database->create();
+        $database->createCollection('users');
+        $database->setDocumentType('users', TypedUser::class);
+
+        $empty = $database->getDocument('users', '');
+
+        $this->assertInstanceOf(TypedUser::class, $empty);
+        $this->assertTrue($empty->isEmpty());
+
+        $missing = $database->getDocument('users', 'nobody');
+
+        $this->assertInstanceOf(TypedUser::class, $missing);
+        $this->assertTrue($missing->isEmpty());
+    }
+
+    public function testEmptyIdOnAnUnmappedCollectionStaysAPlainDocument(): void
+    {
+        $database = new Database(new DatabaseMemory(), new Cache(new CacheMemory()));
+
+        $empty = $database->getDocument('anything', '');
+
+        $this->assertSame(Document::class, $empty::class);
+        $this->assertTrue($empty->isEmpty());
+    }
+}