From c973ca0a5d91eba9366a5abead65846fd0bf9771 Mon Sep 17 00:00:00 2001
From: Chirag Aggarwal <chiragaggarwal5k@gmail.com>
Date: Wed, 22 Apr 2026 09:34:03 +0530
Subject: [PATCH] Address PHPStan level 4 review feedback

---
 src/Appwrite/Messaging/Adapter/Realtime.php   |   9 +-
 src/Appwrite/Platform/Tasks/ScheduleBase.php  |   4 +-
 src/Appwrite/SDK/Specification/Format.php     |  49 +++++---
 .../Database/Validator/Queries/Webhooks.php   |  11 +-
 tests/e2e/Scopes/ApiVectorsDB.php             | 110 ++++++++++++++++++
 .../Databases/VectorsDBCustomClientTest.php   |   2 +
 6 files changed, 165 insertions(+), 20 deletions(-)
 create mode 100644 tests/e2e/Scopes/ApiVectorsDB.php

diff --git a/src/Appwrite/Messaging/Adapter/Realtime.php b/src/Appwrite/Messaging/Adapter/Realtime.php
index 345481e0de..8fe7342ec2 100644
--- a/src/Appwrite/Messaging/Adapter/Realtime.php
+++ b/src/Appwrite/Messaging/Adapter/Realtime.php
@@ -452,6 +452,7 @@ class Realtime extends MessagingAdapter
          * Reserved channel params with expected type
          * If matched the expected type then skip the query parsing like in project
          */
+        /** @var array<string, 'array'|'string'> $reservedParamExpectedTypes */
         $reservedParamExpectedTypes = [
             'project' => 'string',
         ];
@@ -461,8 +462,14 @@ class Realtime extends MessagingAdapter
             $params = $getQueryParam($paramKey);
 
             if (\array_key_exists($paramKey, $reservedParamExpectedTypes) && $params !== null) {
+                $expectedType = $reservedParamExpectedTypes[$paramKey];
+                $isExpectedType = match ($expectedType) {
+                    'array' => \is_array($params),
+                    'string' => \is_string($params),
+                };
+
                 // If the value matches the expected type dont use it the queries
-                if (\is_string($params)) {
+                if ($isExpectedType) {
                     $params = null;
                 }
             }
diff --git a/src/Appwrite/Platform/Tasks/ScheduleBase.php b/src/Appwrite/Platform/Tasks/ScheduleBase.php
index 9ecd151474..1213f78924 100644
--- a/src/Appwrite/Platform/Tasks/ScheduleBase.php
+++ b/src/Appwrite/Platform/Tasks/ScheduleBase.php
@@ -73,7 +73,7 @@ abstract class ScheduleBase extends Action
      * 2. Create timer that sync all changes from 'schedules' collection to local copy. Only reading changes thanks to 'resourceUpdatedAt' attribute
      * 3. Create timer that prepares coroutines for soon-to-execute schedules. When it's ready, coroutine sleeps until exact time before sending request to worker.
      */
-    public function action(BrokerPool $publisher, BrokerPool $publisherMigrations, BrokerPool $publisherFunctions, BrokerPool $publisherMessaging, callable $isResourceBlocked, Database $dbForPlatform, callable $getProjectDB, Telemetry $telemetry): void
+    public function action(BrokerPool $publisher, BrokerPool $publisherMigrations, BrokerPool $publisherFunctions, BrokerPool $publisherMessaging, callable $isResourceBlocked, Database $dbForPlatform, callable $getProjectDB, Telemetry $telemetry): never
     {
         Console::title(\ucfirst(static::getSupportedResource()) . ' scheduler V1');
         Console::success(APP_NAME . ' ' . \ucfirst(static::getSupportedResource()) . ' scheduler v1 has started');
@@ -102,7 +102,7 @@ abstract class ScheduleBase extends Action
             $this->collectSchedules($dbForPlatform, $getProjectDB, $lastSyncUpdate, $isResourceBlocked);
         });
 
-        for (;;) {
+        while (true) {
             try {
                 go(fn () => $this->enqueueResources($dbForPlatform, $getProjectDB));
                 $this->scheduleTelemetryCount->record(count($this->schedules), ['resourceType' => static::getSupportedResource()]);
diff --git a/src/Appwrite/SDK/Specification/Format.php b/src/Appwrite/SDK/Specification/Format.php
index 4b9ee63205..08f960b2a7 100644
--- a/src/Appwrite/SDK/Specification/Format.php
+++ b/src/Appwrite/SDK/Specification/Format.php
@@ -40,6 +40,9 @@ abstract class Format
         'license.url' => '',
     ];
 
+    /**
+     * @var list<array{namespace: string, methods: list<string>, parameter: string, excludeKeys?: list<string>, exclude?: bool}>
+     */
     private const array OAUTH_PROVIDER_BLACKLIST = [
         [
             'namespace' => 'account',
@@ -67,6 +70,9 @@ abstract class Format
         ],
     ];
 
+    /**
+     * @var list<array{namespace: string, methods: list<string>, parameter: string, excludeKeys?: list<string>, exclude?: bool}>
+     */
     private const array PROVIDER_USAGE_BLACKLIST = [
         [
             'namespace' => 'users',
@@ -78,6 +84,9 @@ abstract class Format
         ],
     ];
 
+    /**
+     * @var list<array{namespace: string, methods: list<string>, parameter: string, required?: bool, nullable?: bool}>
+     */
     private const array REQUEST_PARAMETER_OVERRIDES = [
         [
             'namespace' => 'project',
@@ -109,25 +118,20 @@ abstract class Format
     {
         $blacklist = [];
 
-        foreach (self::OAUTH_PROVIDER_BLACKLIST as $config) {
+        foreach ([...self::OAUTH_PROVIDER_BLACKLIST, ...self::PROVIDER_USAGE_BLACKLIST] as $config) {
             foreach ($config['methods'] as $method) {
-                $blacklist[] = [
+                $entry = [
                     'namespace' => $config['namespace'],
                     'method' => $method,
                     'parameter' => $config['parameter'],
-                    'excludeKeys' => $config['excludeKeys'],
-                ];
-            }
-        }
-
-        foreach (self::PROVIDER_USAGE_BLACKLIST as $config) {
-            foreach ($config['methods'] as $method) {
-                $blacklist[] = [
-                    'namespace' => $config['namespace'],
-                    'method' => $method,
-                    'parameter' => $config['parameter'],
-                    'exclude' => $config['exclude'],
                 ];
+                if (isset($config['excludeKeys'])) {
+                    $entry['excludeKeys'] = $config['excludeKeys'];
+                }
+                if (isset($config['exclude'])) {
+                    $entry['exclude'] = $config['exclude'];
+                }
+                $blacklist[] = $entry;
             }
         }
 
@@ -947,7 +951,7 @@ abstract class Format
             'nullable' => $nullable,
         ];
 
-        foreach (self::REQUEST_PARAMETER_OVERRIDES as $override) {
+        foreach ($this->getRequestParameterOverrides() as $override) {
             if (
                 $override['namespace'] !== $service
                 || !\in_array($method, $override['methods'], true)
@@ -956,7 +960,12 @@ abstract class Format
                 continue;
             }
 
-            $config['required'] = $override['required'];
+            if (isset($override['required'])) {
+                $config['required'] = $override['required'];
+            }
+            if (isset($override['nullable'])) {
+                $config['nullable'] = $override['nullable'];
+            }
             break;
         }
 
@@ -965,6 +974,14 @@ abstract class Format
         return $config;
     }
 
+    /**
+     * @return list<array{namespace: string, methods: list<string>, parameter: string, required?: bool, nullable?: bool}>
+     */
+    private function getRequestParameterOverrides(): array
+    {
+        return self::REQUEST_PARAMETER_OVERRIDES;
+    }
+
     public function getResponseEnumName(string $model, string $param): ?string
     {
         if ($param === 'type' && \str_starts_with($model, 'platform') && $model !== 'platformList') {
diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Webhooks.php b/src/Appwrite/Utopia/Database/Validator/Queries/Webhooks.php
index 9fbc158ab2..587ad58ea4 100644
--- a/src/Appwrite/Utopia/Database/Validator/Queries/Webhooks.php
+++ b/src/Appwrite/Utopia/Database/Validator/Queries/Webhooks.php
@@ -51,6 +51,15 @@ class Webhooks extends Base
      */
     public function isValid($value): bool
     {
+        return parent::isValid($this->normalizeAliases($value));
+    }
+
+    private function normalizeAliases(mixed $value): mixed
+    {
+        if (!\is_array($value)) {
+            return $value;
+        }
+
         foreach ($value as &$queryString) {
             if (!\is_string($queryString)) {
                 continue;
@@ -61,6 +70,6 @@ class Webhooks extends Base
         }
         unset($queryString);
 
-        return parent::isValid($value);
+        return $value;
     }
 }
diff --git a/tests/e2e/Scopes/ApiVectorsDB.php b/tests/e2e/Scopes/ApiVectorsDB.php
new file mode 100644
index 0000000000..09494d3c10
--- /dev/null
+++ b/tests/e2e/Scopes/ApiVectorsDB.php
@@ -0,0 +1,110 @@
+<?php
+
+namespace Tests\E2E\Scopes;
+
+/**
+ * API configuration trait for VectorsDB database API.
+ * Uses: /vectorsdb, collections, documents, indexes
+ */
+trait ApiVectorsDB
+{
+    protected function getApiBasePath(): string
+    {
+        return '/vectorsdb';
+    }
+
+    protected function getDatabaseType(): string
+    {
+        return 'vectorsdb';
+    }
+
+    protected function getContainerResource(): string
+    {
+        return 'collections';
+    }
+
+    protected function getContainerIdParam(): string
+    {
+        return 'collectionId';
+    }
+
+    protected function getSchemaResource(): string
+    {
+        return 'attributes';
+    }
+
+    protected function getSchemaParam(): string
+    {
+        return 'attribute';
+    }
+
+    protected function getRecordResource(): string
+    {
+        return 'documents';
+    }
+
+    protected function getRecordIdParam(): string
+    {
+        return 'documentId';
+    }
+
+    protected function getSecurityParam(): string
+    {
+        return 'documentSecurity';
+    }
+
+    protected function getRelatedIdParam(): string
+    {
+        return 'relatedCollectionId';
+    }
+
+    protected function getRelatedResourceKey(): string
+    {
+        return 'relatedCollection';
+    }
+
+    protected function getContainerIdResponseKey(): string
+    {
+        return '$collectionId';
+    }
+
+    protected function getOppositeContainerIdResponseKey(): string
+    {
+        return '$tableId';
+    }
+
+    protected function getIndexAttributesParam(): string
+    {
+        return 'attributes';
+    }
+
+    protected function getSecurityResponseKey(): string
+    {
+        return 'documentSecurity';
+    }
+
+    protected function getSupportForAttributes(): bool
+    {
+        return false;
+    }
+
+    protected function getSupportForRelationships(): bool
+    {
+        return false;
+    }
+
+    protected function getSupportForIntegerIds(): bool
+    {
+        return false;
+    }
+
+    protected function getSupportForOperators(): bool
+    {
+        return false;
+    }
+
+    protected function getSupportForSpatials(): bool
+    {
+        return false;
+    }
+}
diff --git a/tests/e2e/Services/Databases/VectorsDBCustomClientTest.php b/tests/e2e/Services/Databases/VectorsDBCustomClientTest.php
index 7add5c7f71..632b1a62de 100644
--- a/tests/e2e/Services/Databases/VectorsDBCustomClientTest.php
+++ b/tests/e2e/Services/Databases/VectorsDBCustomClientTest.php
@@ -3,6 +3,7 @@
 namespace Tests\E2E\Services\Databases;
 
 use Tests\E2E\Client;
+use Tests\E2E\Scopes\ApiVectorsDB;
 use Tests\E2E\Scopes\ProjectCustom;
 use Tests\E2E\Scopes\Scope;
 use Tests\E2E\Scopes\SideClient;
@@ -16,6 +17,7 @@ class VectorsDBCustomClientTest extends Scope
     use DatabasesBase;
     use ProjectCustom;
     use SideClient;
+    use ApiVectorsDB;
 
     public function testAllowedPermissions(): void
     {