lint

Fix users optional name error

app/config/errors.php

@@ -630,6 +630,11 @@ return [
         'description' => 'Site with the requested ID could not be found.',
         'code' => 404,
     ],
+    Exception::SITE_ALREADY_EXISTS => [
+        'name' => Exception::SITE_ALREADY_EXISTS,
+        'description' => 'Site with the requested ID already exists. Try again with a different ID or use ID.unique() to generate a unique ID.',
+        'code' => 409,
+    ],
     Exception::SITE_TEMPLATE_NOT_FOUND => [
         'name' => Exception::SITE_TEMPLATE_NOT_FOUND,
         'description' => 'Site Template with the requested ID could not be found.',
@@ -1291,6 +1296,11 @@ return [
         'description' => 'Message with the requested ID could not be found.',
         'code' => 404,
     ],
+    Exception::MESSAGE_ALREADY_EXISTS => [
+        'name' => Exception::MESSAGE_ALREADY_EXISTS,
+        'description' => 'Message with the requested ID already exists. Try again with a different ID or use ID.unique() to generate a unique ID.',
+        'code' => 409,
+    ],
     Exception::MESSAGE_MISSING_TARGET => [
         'name' => Exception::MESSAGE_MISSING_TARGET,
         'description' => 'Message with the requested ID has no recipients (topics or users or targets).',

app/controllers/api/messaging.php

@@ -3251,7 +3251,7 @@ Http::post('/v1/messaging/messages/email')
             }
         }
 
-        $message = $dbForProject->createDocument('messages', new Document([
+        $message = new Document([
             '$id' => $messageId,
             'providerType' => MESSAGE_TYPE_EMAIL,
             'topics' => $topics,
@@ -3267,7 +3267,12 @@ Http::post('/v1/messaging/messages/email')
                 'attachments' => $attachments,
             ],
             'status' => $status,
-        ]));
+        ]);
+        try {
+            $message = $dbForProject->createDocument('messages', $message);
+        } catch (DuplicateException) {
+            throw new Exception(Exception::MESSAGE_ALREADY_EXISTS);
+        }
 
         switch ($status) {
             case MessageStatus::PROCESSING:
@@ -3400,7 +3405,7 @@ Http::post('/v1/messaging/messages/sms')
             }
         }
 
-        $message = $dbForProject->createDocument('messages', new Document([
+        $message = new Document([
             '$id' => $messageId,
             'providerType' => MESSAGE_TYPE_SMS,
             'topics' => $topics,
@@ -3410,7 +3415,12 @@ Http::post('/v1/messaging/messages/sms')
                 'content' => $content,
             ],
             'status' => $status,
-        ]));
+        ]);
+        try {
+            $message = $dbForProject->createDocument('messages', $message);
+        } catch (DuplicateException) {
+            throw new Exception(Exception::MESSAGE_ALREADY_EXISTS);
+        }
 
         switch ($status) {
             case MessageStatus::PROCESSING:
@@ -3620,7 +3630,7 @@ Http::post('/v1/messaging/messages/push')
             $pushData['priority'] = $priority;
         }
 
-        $message = $dbForProject->createDocument('messages', new Document([
+        $message = new Document([
             '$id' => $messageId,
             'providerType' => MESSAGE_TYPE_PUSH,
             'topics' => $topics,
@@ -3629,7 +3639,12 @@ Http::post('/v1/messaging/messages/push')
             'scheduledAt' => $scheduledAt,
             'data' => $pushData,
             'status' => $status,
-        ]));
+        ]);
+        try {
+            $message = $dbForProject->createDocument('messages', $message);
+        } catch (DuplicateException) {
+            throw new Exception(Exception::MESSAGE_ALREADY_EXISTS);
+        }
 
         switch ($status) {
             case MessageStatus::PROCESSING:

app/controllers/api/users.php

@@ -73,8 +73,9 @@ use Utopia\Validator\Text;
 use Utopia\Validator\WhiteList;
 
 /** TODO: Remove function when we move to using utopia/platform */
-function createUser(Hash $hash, string $userId, ?string $email, ?string $password, ?string $phone, string $name, Document $project, Database $dbForProject, Hooks $hooks): Document
+function createUser(Hash $hash, string $userId, ?string $email, ?string $password, ?string $phone, ?string $name, Document $project, Database $dbForProject, Hooks $hooks): Document
 {
+    $name = $name ?? '';
     $plaintextPassword = $password;
     $passwordHistory = $project->getAttribute('auths', [])['passwordHistory'] ?? 0;
 
@@ -255,7 +256,7 @@ Http::post('/v1/users')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, ?string $email, ?string $phone, ?string $password, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, ?string $email, ?string $phone, ?string $password, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $plaintext = new Plaintext();
 
         $user = createUser($plaintext, $userId, $email, $password, $phone, $name, $project, $dbForProject, $hooks);
@@ -291,7 +292,7 @@ Http::post('/v1/users/bcrypt')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $bcrypt = new Bcrypt();
         $bcrypt->setCost(8); // Default cost
 
@@ -329,7 +330,7 @@ Http::post('/v1/users/md5')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $md5 = new MD5();
 
         $user = createUser($md5, $userId, $email, $password, null, $name, $project, $dbForProject, $hooks);
@@ -366,7 +367,7 @@ Http::post('/v1/users/argon2')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $argon2 = new Argon2();
 
         $user = createUser($argon2, $userId, $email, $password, null, $name, $project, $dbForProject, $hooks);
@@ -404,7 +405,7 @@ Http::post('/v1/users/sha')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $passwordVersion, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, string $passwordVersion, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $sha = new Sha();
         if (!empty($passwordVersion)) {
             $sha->setVersion($passwordVersion);
@@ -444,7 +445,7 @@ Http::post('/v1/users/phpass')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $phpass = new PHPass();
 
         $user = createUser($phpass, $userId, $email, $password, null, $name, $project, $dbForProject, $hooks);
@@ -486,7 +487,7 @@ Http::post('/v1/users/scrypt')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $passwordSalt, int $passwordCpu, int $passwordMemory, int $passwordParallel, int $passwordLength, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, string $passwordSalt, int $passwordCpu, int $passwordMemory, int $passwordParallel, int $passwordLength, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $scrypt = new Scrypt();
         $scrypt
             ->setSalt($passwordSalt)
@@ -532,7 +533,7 @@ Http::post('/v1/users/scrypt-modified')
     ->inject('project')
     ->inject('dbForProject')
     ->inject('hooks')
-    ->action(function (string $userId, string $email, string $password, string $passwordSalt, string $passwordSaltSeparator, string $passwordSignerKey, string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
+    ->action(function (string $userId, string $email, string $password, string $passwordSalt, string $passwordSaltSeparator, string $passwordSignerKey, ?string $name, Response $response, Document $project, Database $dbForProject, Hooks $hooks) {
         $scryptModified = new ScryptModified();
         $scryptModified
             ->setSalt($passwordSalt)

app/controllers/shared/api.php

@@ -27,6 +27,7 @@ use Utopia\Config\Config;
 use Utopia\Database\Database;
 use Utopia\Database\DateTime;
 use Utopia\Database\Document;
+use Utopia\Database\Exception\Duplicate as DuplicateException;
 use Utopia\Database\Helpers\Role;
 use Utopia\Database\Validator\Authorization;
 use Utopia\Database\Validator\Authorization\Input;
@@ -929,14 +930,19 @@ Http::shutdown()
                 $accessedAt = $cacheLog->getAttribute('accessedAt', 0);
                 $now = DateTime::now();
                 if ($cacheLog->isEmpty()) {
-                    $authorization->skip(fn () => $dbForProject->createDocument('cache', new Document([
-                        '$id' => $key,
-                        'resource' => $resource,
-                        'resourceType' => $resourceType,
-                        'mimeType' => $response->getContentType(),
-                        'accessedAt' => $now,
-                        'signature' => $signature,
-                    ])));
+                    try {
+                        $authorization->skip(fn () => $dbForProject->createDocument('cache', new Document([
+                            '$id' => $key,
+                            'resource' => $resource,
+                            'resourceType' => $resourceType,
+                            'mimeType' => $response->getContentType(),
+                            'accessedAt' => $now,
+                            'signature' => $signature,
+                        ])));
+                    } catch (DuplicateException) {
+                        // Race condition: another concurrent request already created the cache document
+                        $cacheLog = $authorization->skip(fn () => $dbForProject->getDocument('cache', $key));
+                    }
                 } elseif (DateTime::formatTz(DateTime::addSeconds(new \DateTime(), -APP_CACHE_UPDATE)) > $accessedAt) {
                     $cacheLog->setAttribute('accessedAt', $now);
                     $authorization->skip(fn () => $dbForProject->updateDocument('cache', $cacheLog->getId(), $cacheLog));

app/realtime.php

@@ -248,48 +248,62 @@ $adapter
 
 $server = new Server($adapter);
 
-$logError = function (Throwable $error, string $action) use ($register) {
-    $logger = $register->get('realtimeLogger');
+// Allows overriding
+if (!function_exists('logError')) {
+    function logError(Throwable $error, string $action, array $tags = [], ?Document $project = null, ?Document $user = null, ?Authorization $authorization = null): void
+    {
+        global $register;
 
-    if ($logger && !$error instanceof Exception) {
-        $version = System::getEnv('_APP_VERSION', 'UNKNOWN');
+        $logger = $register->get('realtimeLogger');
 
-        $log = new Log();
-        $log->setNamespace("realtime");
-        $log->setServer(System::getEnv('_APP_LOGGING_SERVICE_IDENTIFIER', \gethostname()));
-        $log->setVersion($version);
-        $log->setType(Log::TYPE_ERROR);
-        $log->setMessage($error->getMessage());
+        if ($logger && !$error instanceof Exception) {
+            $version = System::getEnv('_APP_VERSION', 'UNKNOWN');
 
-        $log->addTag('code', $error->getCode());
-        $log->addTag('verboseType', get_class($error));
+            $log = new Log();
+            $log->setNamespace("realtime");
+            $log->setServer(System::getEnv('_APP_LOGGING_SERVICE_IDENTIFIER', \gethostname()));
+            $log->setVersion($version);
+            $log->setType(Log::TYPE_ERROR);
+            $log->setMessage($error->getMessage());
 
-        $log->addExtra('file', $error->getFile());
-        $log->addExtra('line', $error->getLine());
-        $log->addExtra('trace', $error->getTraceAsString());
+            $log->addTag('code', $error->getCode());
+            $log->addTag('verboseType', get_class($error));
+            $log->addTag('projectId', $project?->getId() ?: 'n/a');
+            $log->addTag('userId', $user?->getId() ?: 'n/a');
 
-        $log->setAction($action);
+            foreach ($tags as $key => $value) {
+                $log->addTag($key, $value ?: 'n/a');
+            }
 
-        $isProduction = System::getEnv('_APP_ENV', 'development') === 'production';
-        $log->setEnvironment($isProduction ? Log::ENVIRONMENT_PRODUCTION : Log::ENVIRONMENT_STAGING);
+            $log->addExtra('file', $error->getFile());
+            $log->addExtra('line', $error->getLine());
+            $log->addExtra('trace', $error->getTraceAsString());
+            $log->addExtra('detailedTrace', $error->getTrace());
+            $log->addExtra('roles', $authorization?->getRoles() ?? []);
 
-        try {
-            $responseCode = $logger->addLog($log);
-            Console::info('Error log pushed with status code: ' . $responseCode);
-        } catch (Throwable $th) {
-            Console::error('Error pushing log: ' . $th->getMessage());
+            $log->setAction($action);
+
+            $isProduction = System::getEnv('_APP_ENV', 'development') === 'production';
+            $log->setEnvironment($isProduction ? Log::ENVIRONMENT_PRODUCTION : Log::ENVIRONMENT_STAGING);
+
+            try {
+                $responseCode = $logger->addLog($log);
+                Console::info('Error log pushed with status code: ' . $responseCode);
+            } catch (Throwable $th) {
+                Console::error('Error pushing log: ' . $th->getMessage());
+            }
         }
+
+        Console::error('[Error] Type: ' . get_class($error));
+        Console::error('[Error] Message: ' . $error->getMessage());
+        Console::error('[Error] File: ' . $error->getFile());
+        Console::error('[Error] Line: ' . $error->getLine());
     }
+}
 
-    Console::error('[Error] Type: ' . get_class($error));
-    Console::error('[Error] Message: ' . $error->getMessage());
-    Console::error('[Error] File: ' . $error->getFile());
-    Console::error('[Error] Line: ' . $error->getLine());
-};
+$server->error(logError(...));
 
-$server->error($logError);
-
-$server->onStart(function () use ($stats, $register, $containerId, &$statsDocument, $logError) {
+$server->onStart(function () use ($stats, $register, $containerId, &$statsDocument) {
     sleep(5); // wait for the initial database schema to be ready
     Console::success('Server started successfully');
 
@@ -326,7 +340,7 @@ $server->onStart(function () use ($stats, $register, $containerId, &$statsDocume
      */
     // TODO: Remove this if check once it doesn't cause issues for cloud
     if (System::getEnv('_APP_EDITION', 'self-hosted') === 'self-hosted') {
-        Timer::tick(5000, function () use ($register, $stats, &$statsDocument, $logError) {
+        Timer::tick(5000, function () use ($register, $stats, &$statsDocument) {
             $payload = [];
             foreach ($stats as $projectId => $value) {
                 $payload[$projectId] = $stats->get($projectId, 'connectionsTotal');
@@ -344,13 +358,13 @@ $server->onStart(function () use ($stats, $register, $containerId, &$statsDocume
 
                 $database->getAuthorization()->skip(fn () => $database->updateDocument('realtime', $statsDocument->getId(), $statsDocument));
             } catch (Throwable $th) {
-                $logError($th, "updateWorkerDocument");
+                logError($th, "updateWorkerDocument");
             }
         });
     }
 });
 
-$server->onWorkerStart(function (int $workerId) use ($server, $register, $stats, $realtime, $logError) {
+$server->onWorkerStart(function (int $workerId) use ($server, $register, $stats, $realtime) {
     Console::success('Worker ' . $workerId . ' started successfully');
 
     $telemetry = getTelemetry($workerId);
@@ -362,7 +376,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
     $attempts = 0;
     $start = time();
 
-    Timer::tick(5000, function () use ($server, $register, $realtime, $stats, $logError) {
+    Timer::tick(5000, function () use ($server, $register, $realtime, $stats) {
         /**
          * Sending current connections to project channels on the console project every 5 seconds.
          */
@@ -548,7 +562,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
                 }
             });
         } catch (Throwable $th) {
-            $logError($th, "pubSubConnection");
+            logError($th, "pubSubConnection");
 
             Console::error('Pub/sub error: ' . $th->getMessage());
             $attempts++;
@@ -560,7 +574,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
     Console::error('Failed to restart pub/sub...');
 });
 
-$server->onOpen(function (int $connection, SwooleRequest $request) use ($server, $register, $stats, &$realtime, $logError) {
+$server->onOpen(function (int $connection, SwooleRequest $request) use ($server, $register, $stats, &$realtime) {
     $app = new Http('UTC');
     $request = new Request($request);
     $response = new Response(new SwooleResponse());
@@ -571,6 +585,10 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server,
     Http::setResource('request', fn () => $request);
     Http::setResource('response', fn () => $response);
 
+    $project = null;
+    $logUser = null;
+    $authorization = null;
+
     try {
         /** @var Document $project */
         $project = $app->getResource('project');
@@ -593,6 +611,7 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server,
 
         $timelimit = $app->getResource('timelimit');
         $user = $app->getResource('user'); /** @var User $user */
+        $logUser = $user;
 
         /*
          * Abuse Check
@@ -683,7 +702,7 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server,
         $stats->incr($project->getId(), 'connections');
         $stats->incr($project->getId(), 'connectionsTotal');
     } catch (Throwable $th) {
-        $logError($th, "initServer");
+        logError($th, 'realtime', project: $project, user: $logUser, authorization: $authorization);
 
         // Handle SQL error code is 'HY000'
         $code = $th->getCode();
@@ -718,7 +737,10 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server,
     }
 });
 
-$server->onMessage(function (int $connection, string $message) use ($server, $register, $realtime, $containerId, $logError) {
+$server->onMessage(function (int $connection, string $message) use ($server, $register, $realtime, $containerId) {
+    $project = null;
+    $authorization = null;
+
     try {
         $response = new Response(new SwooleResponse());
         $projectId = $realtime->connections[$connection]['projectId'] ?? null;
@@ -844,7 +866,7 @@ $server->onMessage(function (int $connection, string $message) use ($server, $re
                 throw new Exception(Exception::REALTIME_MESSAGE_FORMAT_INVALID, 'Message type is not valid.');
         }
     } catch (Throwable $th) {
-        $logError($th, "realtimeMessage");
+        logError($th, 'realtimeMessage', project: $project, authorization: $authorization);
         $code = $th->getCode();
         if (!is_int($code)) {
             $code = 500;

composer.lock

@@ -4517,16 +4517,16 @@
         },
         {
             "name": "utopia-php/migration",
-            "version": "1.6.1",
+            "version": "1.6.2",
             "source": {
                 "type": "git",
                 "url": "https://github.com/utopia-php/migration.git",
-                "reference": "c5c7544d02d2418536d41050794050132f247d62"
+                "reference": "037bf4b3813d44f1b0990bc124e35b501ed27fca"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/utopia-php/migration/zipball/c5c7544d02d2418536d41050794050132f247d62",
-                "reference": "c5c7544d02d2418536d41050794050132f247d62",
+                "url": "https://api.github.com/repos/utopia-php/migration/zipball/037bf4b3813d44f1b0990bc124e35b501ed27fca",
+                "reference": "037bf4b3813d44f1b0990bc124e35b501ed27fca",
                 "shasum": ""
             },
             "require": {
@@ -4566,9 +4566,9 @@
             ],
             "support": {
                 "issues": "https://github.com/utopia-php/migration/issues",
-                "source": "https://github.com/utopia-php/migration/tree/1.6.1"
+                "source": "https://github.com/utopia-php/migration/tree/1.6.2"
             },
-            "time": "2026-02-17T05:49:48+00:00"
+            "time": "2026-02-25T12:00:11+00:00"
         },
         {
             "name": "utopia-php/mongo",
@@ -4684,16 +4684,16 @@
         },
         {
             "name": "utopia-php/pools",
-            "version": "1.0.2",
+            "version": "1.0.3",
             "source": {
                 "type": "git",
                 "url": "https://github.com/utopia-php/pools.git",
-                "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1"
+                "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/utopia-php/pools/zipball/b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1",
-                "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1",
+                "url": "https://api.github.com/repos/utopia-php/pools/zipball/74de7c5457a2c447f27e7ec4d72e8412a7d68c10",
+                "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10",
                 "shasum": ""
             },
             "require": {
@@ -4731,9 +4731,9 @@
             ],
             "support": {
                 "issues": "https://github.com/utopia-php/pools/issues",
-                "source": "https://github.com/utopia-php/pools/tree/1.0.2"
+                "source": "https://github.com/utopia-php/pools/tree/1.0.3"
             },
-            "time": "2026-01-28T13:12:36+00:00"
+            "time": "2026-02-26T08:42:40+00:00"
         },
         {
             "name": "utopia-php/preloader",
@@ -5489,16 +5489,16 @@
         },
         {
             "name": "brianium/paratest",
-            "version": "v7.19.0",
+            "version": "v7.19.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/paratestphp/paratest.git",
-                "reference": "7c6c29af7c4b406b49ce0c6b0a3a81d3684474e6"
+                "reference": "95b03194f4cdf5c83175ceead673e21cb66465e7"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/paratestphp/paratest/zipball/7c6c29af7c4b406b49ce0c6b0a3a81d3684474e6",
-                "reference": "7c6c29af7c4b406b49ce0c6b0a3a81d3684474e6",
+                "url": "https://api.github.com/repos/paratestphp/paratest/zipball/95b03194f4cdf5c83175ceead673e21cb66465e7",
+                "reference": "95b03194f4cdf5c83175ceead673e21cb66465e7",
                 "shasum": ""
             },
             "require": {
@@ -5512,7 +5512,7 @@
                 "phpunit/php-code-coverage": "^12.5.3 || ^13.0.1",
                 "phpunit/php-file-iterator": "^6.0.1 || ^7",
                 "phpunit/php-timer": "^8 || ^9",
-                "phpunit/phpunit": "^12.5.9 || ^13",
+                "phpunit/phpunit": "^12.5.14 || ^13.0.5",
                 "sebastian/environment": "^8.0.3 || ^9",
                 "symfony/console": "^7.4.4 || ^8.0.4",
                 "symfony/process": "^7.4.5 || ^8.0.5"
@@ -5522,10 +5522,10 @@
                 "ext-pcntl": "*",
                 "ext-pcov": "*",
                 "ext-posix": "*",
-                "phpstan/phpstan": "^2.1.38",
-                "phpstan/phpstan-deprecation-rules": "^2.0.3",
-                "phpstan/phpstan-phpunit": "^2.0.12",
-                "phpstan/phpstan-strict-rules": "^2.0.8",
+                "phpstan/phpstan": "^2.1.40",
+                "phpstan/phpstan-deprecation-rules": "^2.0.4",
+                "phpstan/phpstan-phpunit": "^2.0.16",
+                "phpstan/phpstan-strict-rules": "^2.0.10",
                 "symfony/filesystem": "^7.4.0 || ^8.0.1"
             },
             "bin": [
@@ -5566,7 +5566,7 @@
             ],
             "support": {
                 "issues": "https://github.com/paratestphp/paratest/issues",
-                "source": "https://github.com/paratestphp/paratest/tree/v7.19.0"
+                "source": "https://github.com/paratestphp/paratest/tree/v7.19.1"
             },
             "funding": [
                 {
@@ -5578,7 +5578,7 @@
                     "type": "paypal"
                 }
             ],
-            "time": "2026-02-06T10:53:26+00:00"
+            "time": "2026-02-25T14:53:45+00:00"
         },
         {
             "name": "doctrine/annotations",
@@ -9067,5 +9067,5 @@
     "platform-overrides": {
         "php": "8.3"
     },
-    "plugin-api-version": "2.6.0"
+    "plugin-api-version": "2.9.0"
 }

src/Appwrite/Extend/Exception.php

@@ -166,6 +166,7 @@ class Exception extends \Exception
 
     /** Sites */
     public const string SITE_NOT_FOUND = 'site_not_found';
+    public const string SITE_ALREADY_EXISTS = 'site_already_exists';
     public const string SITE_TEMPLATE_NOT_FOUND = 'site_template_not_found';
 
     /** Functions */
@@ -365,6 +366,7 @@ class Exception extends \Exception
 
     /** Message */
     public const string MESSAGE_NOT_FOUND = 'message_not_found';
+    public const string MESSAGE_ALREADY_EXISTS = 'message_already_exists';
     public const string MESSAGE_MISSING_TARGET = 'message_missing_target';
     public const string MESSAGE_ALREADY_SENT = 'message_already_sent';
     public const string MESSAGE_ALREADY_PROCESSING = 'message_already_processing';

src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/XList.php

@@ -24,6 +24,7 @@ use Utopia\Http\Adapter\Swoole\Response as SwooleResponse;
 use Utopia\Validator\ArrayList;
 use Utopia\Validator\Boolean;
 use Utopia\Validator\Nullable;
+use Utopia\Validator\Range;
 use Utopia\Validator\Text;
 
 class XList extends Action
@@ -70,15 +71,17 @@ class XList extends Action
             ->param('queries', [], new ArrayList(new Text(APP_LIMIT_ARRAY_ELEMENT_SIZE), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' queries are allowed, each ' . APP_LIMIT_ARRAY_ELEMENT_SIZE . ' characters long.', true)
             ->param('transactionId', null, fn (Database $dbForProject) => new Nullable(new UID($dbForProject->getAdapter()->getMaxUIDLength())), 'Transaction ID to read uncommitted changes within the transaction.', true, ['dbForProject'])
             ->param('total', true, new Boolean(true), 'When set to false, the total count returned will be 0 and will not be calculated.', true)
+            ->param('ttl', 0, new Range(min: 0, max: 86400), 'TTL (seconds) for cached responses when caching is enabled for select queries. Must be between 0 and 86400 (24 hours).', true)
             ->inject('response')
             ->inject('dbForProject')
+            ->inject('user')
             ->inject('queueForStatsUsage')
             ->inject('transactionState')
             ->inject('authorization')
             ->callback($this->action(...));
     }
 
-    public function action(string $databaseId, string $collectionId, array $queries, ?string $transactionId, bool $includeTotal, UtopiaResponse $response, Database $dbForProject, StatsUsage $queueForStatsUsage, TransactionState $transactionState, Authorization $authorization): void
+    public function action(string $databaseId, string $collectionId, array $queries, ?string $transactionId, bool $includeTotal, int $ttl, UtopiaResponse $response, Database $dbForProject, Document $user, StatsUsage $queueForStatsUsage, TransactionState $transactionState, Authorization $authorization): void
     {
         $isAPIKey = User::isApp($authorization->getRoles());
         $isPrivilegedUser = User::isPrivileged($authorization->getRoles());
@@ -129,9 +132,73 @@ class XList extends Action
                 $documents = $transactionState->listDocuments($collectionTableId, $transactionId, $queries);
                 $total = $includeTotal ? $transactionState->countDocuments($collectionTableId, $transactionId, $queries) : 0;
             } elseif (! empty($selectQueries)) {
-                // has selects, allow relationship on documents
-                $documents = $dbForProject->find($collectionTableId, $queries);
-                $total = $includeTotal ? $dbForProject->count($collectionTableId, $queries, APP_LIMIT_COUNT) : 0;
+
+                if ((int)$ttl > 0) {
+                    $serializedQueries = [];
+                    foreach ($queries as $query) {
+                        $serializedQueries[] = $query instanceof Query ? $query->toArray() : $query;
+                    }
+
+                    $hostname = $dbForProject->getAdapter()->getHostname();
+                    $roles = $dbForProject->getAuthorization()->getRoles();
+                    $schemaHash = \md5(\json_encode($collection->getAttribute('attributes', [])) . \json_encode($collection->getAttribute('indexes', [])));
+                    $cacheKeyBase = \sprintf(
+                        '%s-cache-%s:%s:%s:collection:%s:%s:user:%s:%s',
+                        $dbForProject->getCacheName(),
+                        $hostname ?? '',
+                        $dbForProject->getNamespace(),
+                        $dbForProject->getTenant(),
+                        $collectionId,
+                        $schemaHash,
+                        \md5(\json_encode($roles)),
+                        \md5(\json_encode($serializedQueries))
+                    );
+
+                    $documentsCacheKey = $cacheKeyBase . ':documents';
+                    $totalCacheKey = $cacheKeyBase . ':total';
+
+                    $documentsCacheHit = $totalDocumentsCacheHit = false;
+
+                    $cachedDocuments = $dbForProject->getCache()->load($documentsCacheKey, $ttl);
+
+                    if ($cachedDocuments !== null &&
+                        $cachedDocuments !== false &&
+                        \is_array($cachedDocuments)) {
+                        $documents = \array_map(function ($doc) {
+                            return new Document($doc);
+                        }, $cachedDocuments);
+                        $documentsCacheHit = true;
+                    } else {
+                        $documents = $dbForProject->find($collectionTableId, $queries);
+
+                        // Convert Document objects to arrays for caching
+                        $documentsArray = \array_map(function ($doc) {
+                            return $doc->getArrayCopy();
+                        }, $documents);
+                        $dbForProject->getCache()->save($documentsCacheKey, $documentsArray);
+                    }
+
+                    if ($includeTotal) {
+                        $cachedTotal = $dbForProject->getCache()->load($totalCacheKey, $ttl);
+                        if ($cachedTotal !== null && $cachedTotal !== false) {
+                            $total = $cachedTotal;
+                            $totalDocumentsCacheHit = true;
+                        } else {
+                            $total = $dbForProject->count($collectionTableId, $queries, APP_LIMIT_COUNT);
+                            $dbForProject->getCache()->save($totalCacheKey, $total);
+                        }
+                    } else {
+                        $total = 0;
+                    }
+
+                    $response->addHeader('X-Appwrite-Cache', $documentsCacheHit ? 'hit' : 'miss');
+
+                } else {
+                    // has selects, allow relationship on documents
+                    $documents = $dbForProject->find($collectionTableId, $queries);
+                    $total = $includeTotal ? $dbForProject->count($collectionTableId, $queries, APP_LIMIT_COUNT) : 0;
+                }
+
             } else {
                 // has no selects, disable relationship loading on documents
                 /* @type Document[] $documents */

src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Rows/XList.php

@@ -14,6 +14,7 @@ use Utopia\Http\Adapter\Swoole\Response as SwooleResponse;
 use Utopia\Validator\ArrayList;
 use Utopia\Validator\Boolean;
 use Utopia\Validator\Nullable;
+use Utopia\Validator\Range;
 use Utopia\Validator\Text;
 
 class XList extends DocumentXList
@@ -56,8 +57,10 @@ class XList extends DocumentXList
             ->param('queries', [], new ArrayList(new Text(APP_LIMIT_ARRAY_ELEMENT_SIZE), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' queries are allowed, each ' . APP_LIMIT_ARRAY_ELEMENT_SIZE . ' characters long.', true)
             ->param('transactionId', null, fn (Database $dbForProject) => new Nullable(new UID($dbForProject->getAdapter()->getMaxUIDLength())), 'Transaction ID to read uncommitted changes within the transaction.', true, ['dbForProject'])
             ->param('total', true, new Boolean(true), 'When set to false, the total count returned will be 0 and will not be calculated.', true)
+            ->param('ttl', 0, new Range(min: 0, max: 86400), 'TTL (seconds) for cached responses when caching is enabled for select queries. Must be between 0 and 86400 (24 hours).', true)
             ->inject('response')
             ->inject('dbForProject')
+            ->inject('user')
             ->inject('queueForStatsUsage')
             ->inject('transactionState')
             ->inject('authorization')

src/Appwrite/Platform/Modules/Functions/Http/Executions/Delete.php

@@ -90,6 +90,15 @@ class Delete extends Base
         }
         $status = $execution->getAttribute('status');
 
+        // Treat timed-out executions as failed so they can be deleted.
+        if ($status === 'waiting' || $status === 'processing') {
+            $timeout = $function->getAttribute('timeout', 900);
+            $elapsed = \time() - \strtotime($execution->getCreatedAt());
+            if ($elapsed >= $timeout) {
+                $status = 'failed';
+            }
+        }
+
         if (!in_array($status, ['completed', 'failed', 'scheduled'])) {
             throw new Exception(Exception::EXECUTION_IN_PROGRESS);
         }

src/Appwrite/Platform/Modules/Functions/Http/Executions/Get.php

@@ -82,6 +82,16 @@ class Get extends Base
             throw new Exception(Exception::EXECUTION_NOT_FOUND);
         }
 
+        // Override status in response if the execution is stuck in waiting/processing beyond the function timeout.
+        $status = $execution->getAttribute('status', '');
+        if ($status === 'waiting' || $status === 'processing') {
+            $timeout = $function->getAttribute('timeout', 900);
+            $elapsed = \time() - \strtotime($execution->getCreatedAt());
+            if ($elapsed >= $timeout) {
+                $execution->setAttribute('status', 'failed');
+            }
+        }
+
         $response->dynamic($execution, Response::MODEL_EXECUTION);
     }
 }

src/Appwrite/Platform/Modules/Functions/Http/Executions/XList.php

@@ -11,6 +11,7 @@ use Appwrite\Utopia\Database\Documents\User;
 use Appwrite\Utopia\Database\Validator\Queries\Executions;
 use Appwrite\Utopia\Response;
 use Utopia\Database\Database;
+use Utopia\Database\DateTime;
 use Utopia\Database\Document;
 use Utopia\Database\Exception\Order as OrderException;
 use Utopia\Database\Exception\Query as QueryException;
@@ -110,6 +111,35 @@ class XList extends Base
             $cursor->setValue($cursorDocument);
         }
 
+        // Calculate the cutoff datetime before which a waiting/processing execution is considered timed out.
+        $timeout = $function->getAttribute('timeout', 900);
+        $thresholdDate = new \DateTime("-{$timeout} seconds");
+        $threshold = DateTime::format($thresholdDate);
+
+        // Capture what statuses the caller explicitly requested, before we mutate the query.
+        $requestedStatuses = [];
+        foreach ($queries as $query) {
+            if ($query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'status') {
+                $requestedStatuses = [...$requestedStatuses, ...$query->getValues()];
+            }
+        }
+
+        // If the caller is filtering by 'failed', expand the DB query to also return
+        // waiting/processing executions created before the timeout threshold, so timed-out
+        // executions that were never marked failed in the DB are included in the results.
+        foreach ($queries as $index => $query) {
+            if ($query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'status' && \in_array('failed', $query->getValues())) {
+                $queries[$index] = Query::or([
+                    $query,
+                    Query::and([
+                        Query::equal('status', ['waiting', 'processing']),
+                        Query::createdBefore($threshold),
+                    ]),
+                ]);
+                break;
+            }
+        }
+
         $filterQueries = Query::groupByType($queries)['filters'];
 
         try {
@@ -119,6 +149,20 @@ class XList extends Base
             throw new Exception(Exception::DATABASE_QUERY_ORDER_NULL, "The order attribute '{$e->getAttribute()}' had a null value. Cursor pagination requires all documents order attribute values are non-null.");
         }
 
+        // Override status in response for timed-out executions, but only when the caller
+        // did not explicitly request a non-failed status (e.g. waiting/processing).
+        if (empty(\array_diff($requestedStatuses, ['failed']))) {
+            foreach ($results as $execution) {
+                $status = $execution->getAttribute('status', '');
+                if ($status === 'waiting' || $status === 'processing') {
+                    $elapsed = \time() - \strtotime($execution->getCreatedAt());
+                    if ($elapsed >= $timeout) {
+                        $execution->setAttribute('status', 'failed');
+                    }
+                }
+            }
+        }
+
         $response->dynamic(new Document([
             'executions' => $results,
             'total' => $total,

src/Appwrite/Platform/Modules/Sites/Http/Logs/Get.php

@@ -71,6 +71,16 @@ class Get extends Base
             throw new Exception(Exception::LOG_NOT_FOUND);
         }
 
+        // Override status in response if the log is stuck in waiting/processing beyond the site timeout.
+        $status = $log->getAttribute('status', '');
+        if ($status === 'waiting' || $status === 'processing') {
+            $timeout = $site->getAttribute('timeout', 30);
+            $elapsed = \time() - \strtotime($log->getCreatedAt());
+            if ($elapsed >= $timeout) {
+                $log->setAttribute('status', 'failed');
+            }
+        }
+
         $response->dynamic($log, Response::MODEL_EXECUTION); //TODO: Change to model log, but model log already exists - decide what to do
     }
 }

src/Appwrite/Platform/Modules/Sites/Http/Logs/XList.php

@@ -11,6 +11,7 @@ use Appwrite\Utopia\Database\Validator\Queries\Executions;
 use Appwrite\Utopia\Database\Validator\Queries\Logs;
 use Appwrite\Utopia\Response;
 use Utopia\Database\Database;
+use Utopia\Database\DateTime;
 use Utopia\Database\Document;
 use Utopia\Database\Exception\Order as OrderException;
 use Utopia\Database\Exception\Query as QueryException;
@@ -99,6 +100,35 @@ class XList extends Base
             $cursor->setValue($cursorDocument);
         }
 
+        // Calculate the cutoff datetime before which a waiting/processing log is considered timed out.
+        $timeout = $site->getAttribute('timeout', 30);
+        $thresholdDate = new \DateTime("-{$timeout} seconds");
+        $threshold = DateTime::format($thresholdDate);
+
+        // Capture what statuses the caller explicitly requested, before we mutate the query.
+        $requestedStatuses = [];
+        foreach ($queries as $query) {
+            if ($query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'status') {
+                $requestedStatuses = [...$requestedStatuses, ...$query->getValues()];
+            }
+        }
+
+        // If the caller is filtering by 'failed', expand the DB query to also return
+        // waiting/processing logs created before the timeout threshold, so timed-out
+        // logs that were never marked failed in the DB are included in the results.
+        foreach ($queries as $index => $query) {
+            if ($query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'status' && \in_array('failed', $query->getValues())) {
+                $queries[$index] = Query::or([
+                    $query,
+                    Query::and([
+                        Query::equal('status', ['waiting', 'processing']),
+                        Query::createdBefore($threshold),
+                    ]),
+                ]);
+                break;
+            }
+        }
+
         $filterQueries = Query::groupByType($queries)['filters'];
 
         try {
@@ -108,6 +138,20 @@ class XList extends Base
             throw new Exception(Exception::DATABASE_QUERY_ORDER_NULL, "The order attribute '{$e->getAttribute()}' had a null value. Cursor pagination requires all documents order attribute values are non-null.");
         }
 
+        // Override status in response for timed-out logs, but only when the caller
+        // did not explicitly request a non-failed status (e.g. waiting/processing).
+        if (empty(\array_diff($requestedStatuses, ['failed']))) {
+            foreach ($results as $log) {
+                $status = $log->getAttribute('status', '');
+                if ($status === 'waiting' || $status === 'processing') {
+                    $elapsed = \time() - \strtotime($log->getCreatedAt());
+                    if ($elapsed >= $timeout) {
+                        $log->setAttribute('status', 'failed');
+                    }
+                }
+            }
+        }
+
         $response->dynamic(new Document([
             'executions' => $results,
             'total' => $total,

src/Appwrite/Platform/Modules/Sites/Http/Sites/Create.php

@@ -14,6 +14,7 @@ use Appwrite\Utopia\Response;
 use Utopia\Config\Config;
 use Utopia\Database\Database;
 use Utopia\Database\Document;
+use Utopia\Database\Exception\Duplicate as DuplicateException;
 use Utopia\Database\Helpers\ID;
 use Utopia\Platform\Action;
 use Utopia\Platform\Scope\HTTP;
@@ -136,7 +137,7 @@ class Create extends Base
             throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'When connecting to VCS (Version Control System), you need to provide "installationId" and "providerBranch".');
         }
 
-        $site = $dbForProject->createDocument('sites', new Document([
+        $site = new Document([
             '$id' => $siteId,
             'enabled' => $enabled,
             'live' => true,
@@ -166,13 +167,17 @@ class Create extends Base
             'runtimeSpecification' => $specification,
             'buildRuntime' => $buildRuntime,
             'adapter' => $adapter,
-        ]));
+        ]);
+
+        try {
+            $site = $dbForProject->createDocument('sites', $site);
+        } catch (DuplicateException) {
+            throw new Exception(Exception::SITE_ALREADY_EXISTS);
+        }
 
-        // Git connect logic
         if (!empty($providerRepositoryId)) {
             $teamId = $project->getAttribute('teamId', '');
-
-            $repository = $dbForPlatform->createDocument('repositories', new Document([
+            $repository = new Document([
                 '$id' => ID::unique(),
                 '$permissions' => $this->getPermissions($teamId, $project->getId()),
                 'installationId' => $installation->getId(),
@@ -184,8 +189,8 @@ class Create extends Base
                 'resourceInternalId' => $site->getSequence(),
                 'resourceType' => 'site',
                 'providerPullRequestIds' => []
-            ]));
-
+            ]);
+            $repository = $dbForPlatform->createDocument('repositories', $repository);
             $site->setAttribute('repositoryId', $repository->getId());
             $site->setAttribute('repositoryInternalId', $repository->getSequence());
         }

src/Appwrite/Platform/Modules/Sites/Http/Sites/Update.php

@@ -190,11 +190,9 @@ class Update extends Base
             $repositoryInternalId = '';
         }
 
-        // Git connect logic
         if (!$isConnected && !empty($providerRepositoryId)) {
             $teamId = $project->getAttribute('teamId', '');
-
-            $repository = $dbForPlatform->createDocument('repositories', new Document([
+            $repository = new Document([
                 '$id' => ID::unique(),
                 '$permissions' => $this->getPermissions($teamId, $project->getId()),
                 'installationId' => $installation->getId(),
@@ -206,8 +204,8 @@ class Update extends Base
                 'resourceInternalId' => $site->getSequence(),
                 'resourceType' => 'site',
                 'providerPullRequestIds' => []
-            ]));
-
+            ]);
+            $repository = $dbForPlatform->createDocument('repositories', $repository);
             $repositoryId = $repository->getId();
             $repositoryInternalId = $repository->getSequence();
         }

src/Appwrite/Platform/Modules/VCS/Http/GitHub/Callback/Get.php

@@ -4,13 +4,12 @@ namespace Appwrite\Platform\Modules\VCS\Http\GitHub\Callback;
 
 use Appwrite\Auth\OAuth2\Github as OAuth2Github;
 use Appwrite\Extend\Exception;
+use Appwrite\Platform\Permission as AppwritePermission;
 use Appwrite\Utopia\Response;
 use Utopia\Database\Database;
 use Utopia\Database\DateTime;
 use Utopia\Database\Document;
 use Utopia\Database\Helpers\ID;
-use Utopia\Database\Helpers\Permission;
-use Utopia\Database\Helpers\Role;
 use Utopia\Database\Query;
 use Utopia\Platform\Action;
 use Utopia\Platform\Scope\HTTP;
@@ -21,6 +20,7 @@ use Utopia\VCS\Adapter\Git\GitHub;
 class Get extends Action
 {
     use HTTP;
+    use AppwritePermission;
 
     public static function getName()
     {
@@ -132,13 +132,7 @@ class Get extends Action
 
                 $installation = new Document([
                     '$id' => ID::unique(),
-                    '$permissions' => [
-                        Permission::read(Role::team(ID::custom($teamId))),
-                        Permission::update(Role::team(ID::custom($teamId), 'owner')),
-                        Permission::update(Role::team(ID::custom($teamId), 'developer')),
-                        Permission::delete(Role::team(ID::custom($teamId), 'owner')),
-                        Permission::delete(Role::team(ID::custom($teamId), 'developer')),
-                    ],
+                    '$permissions' => $this->getPermissions($teamId, $projectId),
                     'providerInstallationId' => $providerInstallationId,
                     'projectId' => $projectId,
                     'projectInternalId' => $projectInternalId,

src/Appwrite/Platform/Workers/Functions.php

@@ -11,7 +11,6 @@ use Appwrite\Event\StatsUsage;
 use Appwrite\Event\Webhook;
 use Appwrite\Extend\Exception as AppwriteException;
 use Appwrite\Utopia\Response\Model\Execution;
-use Exception;
 use Executor\Executor;
 use Utopia\Config\Config;
 use Utopia\Console;
@@ -73,7 +72,10 @@ class Functions extends Action
         $payload = $message->getPayload() ?? [];
 
         if (empty($payload)) {
-            throw new Exception('Missing payload');
+            throw new AppwriteException(
+                AppwriteException::GENERAL_ARGUMENT_INVALID,
+                'Functions worker: missing payload in schedule execution'
+            );
         }
 
         $type = $payload['type'] ?? '';
@@ -392,7 +394,10 @@ class Functions extends Action
         $runtimes = Config::getParam($version === 'v2' ? 'runtimes-v2' : 'runtimes', []);
 
         if (!\array_key_exists($function->getAttribute('runtime'), $runtimes)) {
-            throw new Exception('Runtime "' . $function->getAttribute('runtime', '') . '" is not supported');
+            throw new AppwriteException(
+                AppwriteException::FUNCTION_RUNTIME_UNSUPPORTED,
+                \sprintf('Runtime "%s" is not supported', $function->getAttribute('runtime', '')),
+            );
         }
 
         $runtime = $runtimes[$function->getAttribute('runtime')];
@@ -640,7 +645,7 @@ class Functions extends Action
         if (!empty($error)) {
             throw new AppwriteException(
                 AppwriteException::GENERAL_SERVER_ERROR,
-                $error ?: 'Function execution failed with no error message',
+                'Function execution failed: ' . ($error ?: 'No error message provided'),
                 $errorCode
             );
         }

tests/e2e/Services/Databases/DatabasesBase.php

@@ -3267,6 +3267,205 @@ trait DatabasesBase
         ], $this->getHeaders()));
     }
 
+    public function testListDocumentsWithCache(): void
+    {
+        $data = $this->setupDocuments();
+        $databaseId = $data['databaseId'];
+        $docIds = $data['documentIds'];
+
+        // Filter to setup documents only, since other tests may have created additional docs in this collection.
+        $baseQueries = [
+            Query::equal('$id', $docIds)->toString(),
+            Query::select(['title', 'releaseYear', '$id'])->toString(),
+            Query::orderAsc('releaseYear')->toString(),
+        ];
+
+        // 1. Using cache with select queries, first request should miss cache.
+        $documents1 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $baseQueries,
+            'ttl' => 30,
+        ]);
+
+        $this->assertEquals(200, $documents1['headers']['status-code']);
+        $this->assertEquals(3, $documents1['body']['total']);
+        $this->assertCount(3, $documents1['body'][$this->getRecordResource()]);
+        $this->assertEquals(1944, $documents1['body'][$this->getRecordResource()][0]['releaseYear']);
+        $this->assertEquals(2017, $documents1['body'][$this->getRecordResource()][1]['releaseYear']);
+        $this->assertEquals(2019, $documents1['body'][$this->getRecordResource()][2]['releaseYear']);
+        $this->assertArrayHasKey('title', $documents1['body'][$this->getRecordResource()][0]);
+        $this->assertArrayHasKey('releaseYear', $documents1['body'][$this->getRecordResource()][0]);
+        $this->assertArrayHasKey('$id', $documents1['body'][$this->getRecordResource()][0]);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents1['headers']);
+        $this->assertEquals('miss', $documents1['headers']['x-appwrite-cache']);
+
+        // 2. Using cache with same select queries, should return cached results.
+        $documents2 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $baseQueries,
+            'ttl' => 30,
+        ]);
+
+        $this->assertEquals(200, $documents2['headers']['status-code']);
+        $this->assertEquals(3, $documents2['body']['total']);
+        $this->assertCount(3, $documents2['body'][$this->getRecordResource()]);
+        $this->assertEquals($documents1['body'][$this->getRecordResource()][0]['$id'], $documents2['body'][$this->getRecordResource()][0]['$id']);
+        $this->assertEquals($documents1['body'][$this->getRecordResource()][0]['title'], $documents2['body'][$this->getRecordResource()][0]['title']);
+        $this->assertEquals($documents1['body'][$this->getRecordResource()][0]['releaseYear'], $documents2['body'][$this->getRecordResource()][0]['releaseYear']);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents2['headers']);
+        $this->assertEquals('hit', $documents2['headers']['x-appwrite-cache']);
+
+        // 3. Using cache with same select queries but total is false, should return cached results just for documents.
+        $documents3 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $baseQueries,
+            'ttl' => 30,
+            'total' => false,
+        ]);
+
+        $this->assertEquals(200, $documents3['headers']['status-code']);
+        $this->assertCount(3, $documents3['body'][$this->getRecordResource()]);
+        $this->assertEquals($documents3['body'][$this->getRecordResource()][0]['$id'], $documents1['body'][$this->getRecordResource()][0]['$id']);
+        $this->assertEquals($documents3['body'][$this->getRecordResource()][0]['title'], $documents1['body'][$this->getRecordResource()][0]['title']);
+        $this->assertEquals($documents3['body'][$this->getRecordResource()][0]['releaseYear'], $documents1['body'][$this->getRecordResource()][0]['releaseYear']);
+        $this->assertEquals(0, $documents3['body']['total']);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents3['headers']);
+        $this->assertEquals('hit', $documents3['headers']['x-appwrite-cache']);
+
+        // 4. Using cache with different select queries, should miss cache.
+        $documents4 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => [
+                Query::equal('$id', $docIds)->toString(),
+                Query::select(['title'])->toString(),
+                Query::orderAsc('releaseYear')->toString(),
+            ],
+            'ttl' => 10,
+        ]);
+
+        $this->assertEquals(200, $documents4['headers']['status-code']);
+        $this->assertEquals(3, $documents4['body']['total']);
+        $this->assertCount(3, $documents4['body'][$this->getRecordResource()]);
+        $this->assertEquals($documents4['body'][$this->getRecordResource()][0]['title'], $documents1['body'][$this->getRecordResource()][0]['title']);
+        $this->assertEquals($documents4['body'][$this->getRecordResource()][1]['title'], $documents1['body'][$this->getRecordResource()][1]['title']);
+        $this->assertEquals($documents4['body'][$this->getRecordResource()][2]['title'], $documents1['body'][$this->getRecordResource()][2]['title']);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents4['headers']);
+        $this->assertEquals('miss', $documents4['headers']['x-appwrite-cache']);
+
+        // 5. Not using cache at all
+        $documents5 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => [
+                Query::equal('$id', $docIds)->toString(),
+                Query::select(['title', 'releaseYear', '$id'])->toString(),
+                Query::orderAsc('releaseYear')->toString(),
+            ],
+        ]);
+
+        $this->assertEquals(200, $documents5['headers']['status-code']);
+        $this->assertCount(3, $documents5['body'][$this->getRecordResource()]);
+        $this->assertEquals(1944, $documents5['body'][$this->getRecordResource()][0]['releaseYear']);
+        $this->assertArrayNotHasKey('x-appwrite-cache', $documents5['headers']);
+
+        sleep(10);
+
+        // 6. Using cache with same select queries but passed ttl time, should miss cache.
+        $documents6 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $baseQueries,
+            'ttl' => 10,
+        ]);
+
+        $this->assertEquals(200, $documents6['headers']['status-code']);
+        $this->assertCount(3, $documents6['body'][$this->getRecordResource()]);
+        $this->assertArrayHasKey('title', $documents6['body'][$this->getRecordResource()][0]);
+        $this->assertArrayHasKey('releaseYear', $documents6['body'][$this->getRecordResource()][0]);
+        $this->assertArrayHasKey('$id', $documents6['body'][$this->getRecordResource()][0]);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents6['headers']);
+        $this->assertEquals('miss', $documents6['headers']['x-appwrite-cache']);
+    }
+
+    public function testListDocumentsCacheBustedByAttributeChange(): void
+    {
+        $data = $this->setupDocuments();
+        $databaseId = $data['databaseId'];
+        $docIds = $data['documentIds'];
+
+        // Use different select queries from testListDocumentsWithCache to avoid cache key collision.
+        $queries = [
+            Query::equal('$id', $docIds)->toString(),
+            Query::select(['title', '$id'])->toString(),
+            Query::orderAsc('$createdAt')->toString(),
+        ];
+
+        // 1. First request should miss cache.
+        $documents1 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $queries,
+            'ttl' => 300,
+        ]);
+
+        $this->assertEquals(200, $documents1['headers']['status-code']);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents1['headers']);
+        $this->assertEquals('miss', $documents1['headers']['x-appwrite-cache']);
+
+        // 2. Same request should hit cache.
+        $documents2 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $queries,
+            'ttl' => 300,
+        ]);
+
+        $this->assertEquals(200, $documents2['headers']['status-code']);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents2['headers']);
+        $this->assertEquals('hit', $documents2['headers']['x-appwrite-cache']);
+
+        // 3. Add a new attribute to the collection, which updates the collection's $updatedAt.
+        $attribute = $this->client->call(Client::METHOD_POST, $this->getSchemaUrl($databaseId, $data['moviesId']) . '/string', array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+            'x-appwrite-key' => $this->getProject()['apiKey']
+        ]), [
+            'key' => 'cacheTestAttr',
+            'size' => 64,
+            'required' => false,
+        ]);
+
+        $this->assertEquals(202, $attribute['headers']['status-code']);
+
+        // Wait for the attribute to be ready
+        $this->waitForAttribute($databaseId, $data['moviesId'], 'cacheTestAttr');
+
+        // 4. Same request should now miss cache because collection $updatedAt changed.
+        $documents3 = $this->client->call(Client::METHOD_GET, $this->getRecordUrl($databaseId, $data['moviesId']), array_merge([
+            'content-type' => 'application/json',
+            'x-appwrite-project' => $this->getProject()['$id'],
+        ], $this->getHeaders()), [
+            'queries' => $queries,
+            'ttl' => 300,
+        ]);
+
+        $this->assertEquals(200, $documents3['headers']['status-code']);
+        $this->assertArrayHasKey('x-appwrite-cache', $documents3['headers']);
+        $this->assertEquals('miss', $documents3['headers']['x-appwrite-cache']);
+    }
+
     public function testGetDocument(): void
     {
         $data = $this->getDocumentsList();