From cf8c7bd382b09e35a2c8e1df49471d40fe905874 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 2 Jun 2026 14:50:10 +0200 Subject: [PATCH 01/24] OIDC customization support --- src/Appwrite/Auth/OAuth2/Oidc.php | 50 +++++++++- .../Http/Project/OAuth2/Oidc/Update.php | 30 +++++- .../Utopia/Response/Model/OAuth2Oidc.php | 15 +++ tests/e2e/Services/Project/OAuth2Base.php | 92 +++++++++++++++++++ 4 files changed, 184 insertions(+), 3 deletions(-) diff --git a/src/Appwrite/Auth/OAuth2/Oidc.php b/src/Appwrite/Auth/OAuth2/Oidc.php index c9810c48eb..f8d5e6c4e9 100644 --- a/src/Appwrite/Auth/OAuth2/Oidc.php +++ b/src/Appwrite/Auth/OAuth2/Oidc.php @@ -43,13 +43,25 @@ class Oidc extends OAuth2 */ public function getLoginURL(): string { - return $this->getAuthorizationEndpoint() . '?' . \http_build_query([ + $params = [ 'client_id' => $this->appID, 'redirect_uri' => $this->callback, 'state' => \json_encode($this->state), 'scope' => \implode(' ', $this->getScopes()), 'response_type' => 'code', - ]); + ]; + + $prompt = $this->getPrompt(); + if (!empty($prompt)) { + $params['prompt'] = $prompt; + } + + $maxAge = $this->getMaxAge(); + if ($maxAge !== null) { + $params['max_age'] = $maxAge; + } + + return $this->getAuthorizationEndpoint() . '?' . \http_build_query($params); } /** @@ -196,6 +208,40 @@ class Oidc extends OAuth2 return $secret['clientSecret'] ?? ''; } + /** + * Extracts the prompt values from the JSON stored in appSecret. + * + * @return string + */ + protected function getPrompt(): string + { + $secret = $this->getAppSecret(); + $prompt = $secret['prompt'] ?? []; + + if (!\is_array($prompt)) { + $prompt = [$prompt]; + } + + return \implode(' ', $prompt); + } + + /** + * Extracts the max_age value from the JSON stored in appSecret. + * + * @return int|null + */ + protected function getMaxAge(): ?int + { + $secret = $this->getAppSecret(); + $maxAge = $secret['maxAge'] ?? null; + + if ($maxAge === null || $maxAge === '') { + return null; + } + + return (int) $maxAge; + } + /** * Extracts the well known endpoint from the JSON stored in appSecret. * diff --git a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php index 697b306be8..866704454a 100644 --- a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php +++ b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php @@ -14,10 +14,14 @@ use Appwrite\Utopia\Response; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Validator\Authorization; +use Utopia\Platform\Enum; +use Utopia\Validator\ArrayList; use Utopia\Validator\Boolean; use Utopia\Validator\Nullable; +use Utopia\Validator\Range; use Utopia\Validator\Text; use Utopia\Validator\URL; +use Utopia\Validator\WhiteList; class Update extends Base { @@ -93,6 +97,18 @@ class Update extends Base 'example' => 'https://myoauth.com/oauth2/userinfo', 'hint' => '', ], + [ + '$id' => 'prompt', + 'name' => 'Prompt', + 'example' => '["consent"]', + 'hint' => '', + ], + [ + '$id' => 'maxAge', + 'name' => 'Max Age', + 'example' => '3600', + 'hint' => '', + ], ]); } @@ -129,6 +145,8 @@ class Update extends Base ->param('authorizationURL', null, new Nullable(new URL(allowEmpty: true)), 'OpenID Connect authorization endpoint URL. Required when wellKnownURL is not provided. For example: https://myoauth.com/oauth2/authorize', optional: true) ->param('tokenURL', null, new Nullable(new URL(allowEmpty: true)), 'OpenID Connect token endpoint URL. Required when wellKnownURL is not provided. For example: https://myoauth.com/oauth2/token', optional: true, aliases: ['tokenUrl']) ->param('userInfoURL', null, new Nullable(new URL(allowEmpty: true)), 'OpenID Connect user info endpoint URL. Required when wellKnownURL is not provided. For example: https://myoauth.com/oauth2/userinfo', optional: true, aliases: ['userInfoUrl']) + ->param('prompt', null, new Nullable(new ArrayList(new WhiteList(['none', 'login', 'consent', 'select_account'], true), 4)), 'Array of OpenID Connect prompt values controlling the authentication and consent screens. If "none" is included, it must be the only element. "none" means: don\'t display any authentication or consent screens. "login" means: prompt the user to re-authenticate. "consent" means: prompt the user for consent. "select_account" means: prompt the user to select an account.', optional: true, enum: new Enum(name: 'ProjectOAuth2OidcPrompt')) + ->param('maxAge', null, new Nullable(new Range(0, PHP_INT_MAX, Range::TYPE_INTEGER)), 'Maximum authentication age in seconds. When set, the user must have authenticated within this many seconds, otherwise they are prompted to re-authenticate. Set to null or omit to leave unspecified.', optional: true) ->param('enabled', null, new Nullable(new Boolean()), 'OAuth2 sign-in method status. Set to true to enable new session creation. Setting to true will trigger end-to-end credentials validation, and will throw if the credentials are invalid.', true) ->inject('response') ->inject('dbForPlatform') @@ -153,6 +171,8 @@ class Update extends Base 'authorizationURL' => $decoded['authorizationEndpoint'] ?? '', 'tokenURL' => $decoded['tokenEndpoint'] ?? '', 'userInfoURL' => $decoded['userInfoEndpoint'] ?? '', + 'prompt' => $decoded['prompt'] ?? [], + 'maxAge' => $decoded['maxAge'] ?? null, ]); } @@ -176,6 +196,8 @@ class Update extends Base ?string $authorizationURL, ?string $tokenURL, ?string $userInfoURL, + ?array $prompt, + ?int $maxAge, ?bool $enabled, Response $response, Database $dbForPlatform, @@ -186,8 +208,12 @@ class Update extends Base $providerId = static::getProviderId(); $queueForEvents->setParam('providerId', $providerId); + if ($prompt !== null && \in_array('none', $prompt) && \count($prompt) > 1) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'When "none" is used as a prompt value, it must be the only element in the array.'); + } + // The secret is stored as JSON - // `{"clientSecret": "...", "wellKnownEndpoint": "...", "authorizationEndpoint": "...", "tokenEndpoint": "...", "userInfoEndpoint": "..."}` + // `{"clientSecret": "...", "wellKnownEndpoint": "...", "authorizationEndpoint": "...", "tokenEndpoint": "...", "userInfoEndpoint": "...", "prompt": [...], "maxAge": ...}` // so that the OIDC OAuth2 adapter can extract each endpoint individually. // Merge new values with what's already stored so that submitting only a // subset of fields leaves the others untouched. @@ -203,6 +229,8 @@ class Update extends Base 'authorizationEndpoint' => $authorizationURL ?? ($existing['authorizationEndpoint'] ?? ''), 'tokenEndpoint' => $tokenURL ?? ($existing['tokenEndpoint'] ?? ''), 'userInfoEndpoint' => $userInfoURL ?? ($existing['userInfoEndpoint'] ?? ''), + 'prompt' => $prompt ?? ($existing['prompt'] ?? []), + 'maxAge' => $maxAge ?? ($existing['maxAge'] ?? null), ]; // When enabling, require either wellKnownEndpoint alone, or all three diff --git a/src/Appwrite/Utopia/Response/Model/OAuth2Oidc.php b/src/Appwrite/Utopia/Response/Model/OAuth2Oidc.php index 0b18539423..e3b4191496 100644 --- a/src/Appwrite/Utopia/Response/Model/OAuth2Oidc.php +++ b/src/Appwrite/Utopia/Response/Model/OAuth2Oidc.php @@ -53,6 +53,21 @@ class OAuth2Oidc extends OAuth2Base 'description' => 'OpenID Connect user info endpoint URL.', 'default' => '', 'example' => 'https://myoauth.com/oauth2/userinfo', + ]) + ->addRule('prompt', [ + 'type' => self::TYPE_ENUM, + 'description' => 'OpenID Connect prompt values controlling the authentication and consent screens.', + 'default' => [], + 'example' => ['consent'], + 'array' => true, + 'enum' => ['none', 'login', 'consent', 'select_account'], + ]) + ->addRule('maxAge', [ + 'type' => self::TYPE_INTEGER, + 'description' => 'Maximum authentication age in seconds. When set, the user must have authenticated within this many seconds.', + 'default' => null, + 'example' => 3600, + 'required' => false, ]); } diff --git a/tests/e2e/Services/Project/OAuth2Base.php b/tests/e2e/Services/Project/OAuth2Base.php index 8a317f3e1d..d5ff1c10c6 100644 --- a/tests/e2e/Services/Project/OAuth2Base.php +++ b/tests/e2e/Services/Project/OAuth2Base.php @@ -2090,6 +2090,98 @@ trait OAuth2Base ]); } + public function testUpdateOAuth2OidcPromptAndMaxAge(): void + { + $response = $this->updateOAuth2('oidc', [ + 'clientId' => 'oidc-prompt-client', + 'clientSecret' => 'oidc-prompt-secret', + 'wellKnownURL' => 'https://idp.example.com/.well-known/openid-configuration', + 'prompt' => ['login', 'consent'], + 'maxAge' => 3600, + 'enabled' => false, + ]); + + $this->assertSame(200, $response['headers']['status-code']); + $this->assertSame(['login', 'consent'], $response['body']['prompt']); + $this->assertSame(3600, $response['body']['maxAge']); + + // GET reads back prompt + maxAge while hiding the clientSecret. + $get = $this->getOAuth2Provider('oidc'); + $this->assertSame(200, $get['headers']['status-code']); + $this->assertSame(['login', 'consent'], $get['body']['prompt']); + $this->assertSame(3600, $get['body']['maxAge']); + $this->assertSame('', $get['body']['clientSecret']); + + // Cleanup + $this->updateOAuth2('oidc', [ + 'clientId' => '', + 'clientSecret' => '', + 'wellKnownURL' => '', + 'authorizationURL' => '', + 'tokenURL' => '', + 'userInfoURL' => '', + 'prompt' => [], + 'enabled' => false, + ]); + } + + public function testUpdateOAuth2OidcPartialPreservesPromptAndMaxAge(): void + { + // Seed prompt + maxAge. + $this->updateOAuth2('oidc', [ + 'clientId' => 'oidc-seed-client', + 'clientSecret' => 'oidc-seed-secret', + 'wellKnownURL' => 'https://idp.example.com/.well-known/openid-configuration', + 'prompt' => ['select_account'], + 'maxAge' => 120, + 'enabled' => false, + ]); + + // Update only clientId — prompt and maxAge must be preserved. + $response = $this->updateOAuth2('oidc', [ + 'clientId' => 'oidc-rotated-client', + ]); + + $this->assertSame(200, $response['headers']['status-code']); + $this->assertSame('oidc-rotated-client', $response['body']['clientId']); + $this->assertSame(['select_account'], $response['body']['prompt']); + $this->assertSame(120, $response['body']['maxAge']); + + // Cleanup + $this->updateOAuth2('oidc', [ + 'clientId' => '', + 'clientSecret' => '', + 'wellKnownURL' => '', + 'prompt' => [], + 'enabled' => false, + ]); + } + + public function testUpdateOAuth2OidcPromptNoneAloneRejected(): void + { + $response = $this->updateOAuth2('oidc', [ + 'clientId' => 'oidc-prompt-none', + 'clientSecret' => 'oidc-prompt-none-secret', + 'prompt' => ['none', 'consent'], + 'enabled' => false, + ]); + + $this->assertSame(400, $response['headers']['status-code']); + $this->assertSame('general_argument_invalid', $response['body']['type']); + } + + public function testUpdateOAuth2OidcMaxAgeNegativeRejected(): void + { + $response = $this->updateOAuth2('oidc', [ + 'clientId' => 'oidc-maxage-negative', + 'clientSecret' => 'oidc-maxage-negative-secret', + 'maxAge' => -1, + 'enabled' => false, + ]); + + $this->assertSame(400, $response['headers']['status-code']); + } + // ========================================================================= // Update Okta (clientId + clientSecret + optional domain/authServer) // ========================================================================= From db11c8fcc6595739ba410ec4c0adb9e77779d8f4 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 19:48:28 +0400 Subject: [PATCH 02/24] Add Folder validator for storage virtual folder paths --- .../Utopia/Database/Validator/Folder.php | 72 +++++++++++++++++++ .../Utopia/Database/Validator/FolderTest.php | 55 ++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 src/Appwrite/Utopia/Database/Validator/Folder.php create mode 100644 tests/unit/Utopia/Database/Validator/FolderTest.php diff --git a/src/Appwrite/Utopia/Database/Validator/Folder.php b/src/Appwrite/Utopia/Database/Validator/Folder.php new file mode 100644 index 0000000000..592f1a9ff7 --- /dev/null +++ b/src/Appwrite/Utopia/Database/Validator/Folder.php @@ -0,0 +1,72 @@ + self::MAX_LENGTH) { + return false; + } + + if (\preg_match('/[\x00-\x1F\x7F]/', $value)) { + return false; + } + + if (\str_ends_with($value, '/')) { + $value = \substr($value, 0, -1); + } + + if ($value === '') { + return false; + } + + foreach (\explode('/', $value) as $segment) { + if ($segment === '' || $segment === '.' || $segment === '..') { + return false; + } + } + + return true; + } + + /** + * Canonical stored form: trailing slash when non-empty. + */ + public static function normalize(string $value): string + { + if ($value === '') { + return ''; + } + + return \str_ends_with($value, '/') ? $value : $value . '/'; + } + + public function isArray(): bool + { + return false; + } + + public function getType(): string + { + return self::TYPE_STRING; + } +} diff --git a/tests/unit/Utopia/Database/Validator/FolderTest.php b/tests/unit/Utopia/Database/Validator/FolderTest.php new file mode 100644 index 0000000000..d313526db9 --- /dev/null +++ b/tests/unit/Utopia/Database/Validator/FolderTest.php @@ -0,0 +1,55 @@ +object = new Folder(); + } + + public function testValues(): void + { + // valid + $this->assertTrue($this->object->isValid('')); + $this->assertTrue($this->object->isValid('photos')); + $this->assertTrue($this->object->isValid('photos/')); + $this->assertTrue($this->object->isValid('photos/2026')); + $this->assertTrue($this->object->isValid('photos/2026/')); + $this->assertTrue($this->object->isValid('photos/2026/july')); + $this->assertTrue($this->object->isValid('with space/and-dash_underscore.dot')); + $this->assertTrue($this->object->isValid(\str_repeat('a', 2047) . '/')); + + // invalid + $this->assertFalse($this->object->isValid(null)); + $this->assertFalse($this->object->isValid(false)); + $this->assertFalse($this->object->isValid(123)); + $this->assertFalse($this->object->isValid('/')); + $this->assertFalse($this->object->isValid('/photos')); + $this->assertFalse($this->object->isValid('photos//2026')); + $this->assertFalse($this->object->isValid('photos/./2026')); + $this->assertFalse($this->object->isValid('photos/../2026')); + $this->assertFalse($this->object->isValid('..')); + $this->assertFalse($this->object->isValid("photos/\x01")); + $this->assertFalse($this->object->isValid("photos\n")); + // 2048 chars without trailing slash normalizes to 2049 -- too long + $this->assertFalse($this->object->isValid(\str_repeat('a', 2048))); + $this->assertFalse($this->object->isValid(\str_repeat('a', 3000))); + } + + public function testNormalize(): void + { + $this->assertEquals('', Folder::normalize('')); + $this->assertEquals('photos/', Folder::normalize('photos')); + $this->assertEquals('photos/', Folder::normalize('photos/')); + $this->assertEquals('photos/2026/', Folder::normalize('photos/2026')); + } +} From eb72169b89ce44f8976a2161e328259f64700b7d Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:05:00 +0400 Subject: [PATCH 03/24] Add parent attribute and index to files collections with V25 migration --- app/config/collections/common.php | 18 ++++++++++++ src/Appwrite/Migration/Version/V25.php | 38 ++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index 70b0730077..a2379229a3 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2530,6 +2530,17 @@ return [ 'array' => false, 'filters' => [], ], + [ + '$id' => ID::custom('parent'), + 'type' => Database::VAR_STRING, + 'format' => '', + 'size' => 2048, + 'signed' => true, + 'required' => false, + 'default' => '', + 'array' => false, + 'filters' => [], + ], [ '$id' => ID::custom('signature'), 'type' => Database::VAR_STRING, @@ -2718,6 +2729,13 @@ return [ 'lengths' => [256], 'orders' => [Database::ORDER_ASC], ], + [ + '$id' => ID::custom('_key_parent'), + 'type' => Database::INDEX_KEY, + 'attributes' => ['parent'], + 'lengths' => [256], + 'orders' => [Database::ORDER_ASC], + ], [ '$id' => ID::custom('_key_signature'), 'type' => Database::INDEX_KEY, diff --git a/src/Appwrite/Migration/Version/V25.php b/src/Appwrite/Migration/Version/V25.php index 800b9b451f..b2c65fd9f8 100644 --- a/src/Appwrite/Migration/Version/V25.php +++ b/src/Appwrite/Migration/Version/V25.php @@ -7,6 +7,8 @@ use Exception; use Throwable; use Utopia\Console; use Utopia\Database\Database; +use Utopia\Database\Document; +use Utopia\Database\Exception\Duplicate; class V25 extends Migration { @@ -17,6 +19,9 @@ class V25 extends Migration { Console::info('Migrating collections'); $this->migrateCollections(); + + Console::info('Migrating buckets'); + $this->migrateBuckets(); } /** @@ -66,4 +71,37 @@ class V25 extends Migration } } } + + /** + * Add the virtual folder `parent` attribute and index to every + * per-bucket files collection. + * + * @return void + * @throws Throwable + */ + private function migrateBuckets(): void + { + $this->dbForProject->foreach('buckets', function (Document $bucket) { + $bucketTable = "bucket_{$bucket->getSequence()}"; + Console::log("Migrating Bucket {$bucket->getId()} ({$bucket->getAttribute('name')})"); + + try { + $this->createAttributeFromCollection($this->dbForProject, $bucketTable, 'parent', 'files'); + } catch (Duplicate) { + Console::warning("'parent' from {$bucketTable}: Column already exists"); + } catch (Throwable $th) { + Console::warning("'parent' from {$bucketTable}: {$th->getMessage()}"); + } + + try { + $this->createIndexFromCollection($this->dbForProject, $bucketTable, '_key_parent', 'files'); + } catch (Duplicate) { + Console::warning("'_key_parent' from {$bucketTable}: Index already exists"); + } catch (Throwable $th) { + Console::warning("'_key_parent' from {$bucketTable}: {$th->getMessage()}"); + } + + $this->dbForProject->purgeCachedCollection($bucketTable); + }); + } } From 5d7594194dd83b61a95bc58bfa740bcaffad9ffe Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:16:47 +0400 Subject: [PATCH 04/24] Add parent param to file create and expose parent/key on file model --- .../Storage/Http/Buckets/Files/Create.php | 10 +- src/Appwrite/Utopia/Response/Model/File.php | 16 +++ tests/e2e/Services/Storage/StorageBase.php | 107 ++++++++++++++++++ 3 files changed, 131 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php index cf934575c0..be11e4191b 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php @@ -13,6 +13,7 @@ use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Database\Validator\CustomId; +use Appwrite\Utopia\Database\Validator\Folder; use Appwrite\Utopia\Response; use Utopia\Compression\Algorithms\GZIP; use Utopia\Compression\Algorithms\Zstd; @@ -85,6 +86,7 @@ class Create extends Action ->param('fileId', '', new CustomId(), 'File ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.') ->param('file', [], new File(), 'Binary file. Appwrite SDKs provide helpers to handle file input. [Learn about file input](https://appwrite.io/docs/products/storage/upload-download#input-file).', skipValidation: true) ->param('permissions', null, new Nullable(new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE, [Database::PERMISSION_READ, Database::PERMISSION_UPDATE, Database::PERMISSION_DELETE, Database::PERMISSION_WRITE])), 'An array of permission strings. By default, only the current user is granted all permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).', true) + ->param('parent', '', new Folder(), 'Virtual folder to place the file in, for example "photos/2026". Nest folders with `/`. Defaults to the bucket root.', true) ->inject('request') ->inject('response') ->inject('dbForProject') @@ -103,6 +105,7 @@ class Create extends Action string $fileId, mixed $file, ?array $permissions, + string $parent, Request $request, Response $response, Database $dbForProject, @@ -190,6 +193,7 @@ class Create extends Action $contentRange = $request->getHeaderLine('content-range'); $fileId = $fileId === 'unique()' ? ID::unique() : $fileId; + $parent = Folder::normalize($parent); $chunk = 1; $chunks = 1; @@ -261,7 +265,7 @@ class Create extends Action }; try { - $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $path, $permissions, $response, &$completed): void { + $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $parent, $path, $permissions, $response, &$completed): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); if (!$file->isEmpty()) { $chunks = $file->getAttribute('chunksTotal', 1); @@ -292,6 +296,7 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, + 'parent' => $parent, 'path' => $path, 'signature' => '', 'mimeType' => '', @@ -325,7 +330,7 @@ class Create extends Action return; } - $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $path, $permissions, $queueForEvents, $response): void { + $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $parent, $path, $permissions, $queueForEvents, $response): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); $uploaded = 0; @@ -428,6 +433,7 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, + 'parent' => $parent, 'path' => $path, 'signature' => $fileHash, 'mimeType' => $mimeType, diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 61dd496f52..029f4defa0 100644 --- a/src/Appwrite/Utopia/Response/Model/File.php +++ b/src/Appwrite/Utopia/Response/Model/File.php @@ -49,6 +49,18 @@ class File extends Model 'default' => '', 'example' => 'Pink.png', ]) + ->addRule('parent', [ + 'type' => self::TYPE_STRING, + 'description' => 'Virtual folder containing the file, with a trailing slash. Empty for the bucket root.', + 'default' => '', + 'example' => 'photos/2026/', + ]) + ->addRule('key', [ + 'type' => self::TYPE_STRING, + 'description' => 'Full virtual path of the file: the parent folder followed by the file name.', + 'default' => '', + 'example' => 'photos/2026/Pink.png', + ]) ->addRule('signature', [ 'type' => self::TYPE_STRING, 'description' => 'File MD5 signature.', @@ -127,6 +139,10 @@ class File extends Model $encryption = !empty($document->getAttribute('openSSLCipher', '')); $document->setAttribute('encryption', $encryption); + $parent = $document->getAttribute('parent') ?? ''; + $document->setAttribute('parent', $parent); + $document->setAttribute('key', $parent . $document->getAttribute('name', '')); + return $document; } } diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 3f823c38e9..f90a967148 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -491,6 +491,113 @@ trait StorageBase $this->assertNotEmpty($webpView['body']); } + public function testCreateBucketFileWithParent(): void + { + $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'bucketId' => ID::unique(), + 'name' => 'Test Bucket Folders', + 'fileSecurity' => true, + 'permissions' => [ + Permission::read(Role::any()), + Permission::create(Role::any()), + Permission::update(Role::any()), + Permission::delete(Role::any()), + ], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + // without trailing slash -- normalized on storage + $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => 'photos/2026', + ]); + $this->assertEquals(201, $file['headers']['status-code']); + $this->assertEquals('photos/2026/', $file['body']['parent']); + $this->assertEquals('photos/2026/logo.png', $file['body']['key']); + $this->assertEquals('logo.png', $file['body']['name']); + + // default -- bucket root + $rootFile = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + ]); + $this->assertEquals(201, $rootFile['headers']['status-code']); + $this->assertEquals('', $rootFile['body']['parent']); + $this->assertEquals('logo.png', $rootFile['body']['key']); + + // duplicate keys allowed -- same parent + name, different fileId + $duplicate = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => 'photos/2026', + ]); + $this->assertEquals(201, $duplicate['headers']['status-code']); + $this->assertEquals('photos/2026/logo.png', $duplicate['body']['key']); + $this->assertNotEquals($file['body']['$id'], $duplicate['body']['$id']); + + // invalid values + foreach (['/photos', 'photos//2026', 'photos/../2026', "photos/\x01"] as $invalid) { + $res = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => $invalid, + ]); + $this->assertEquals(400, $res['headers']['status-code']); + } + + // chunked upload -- parent is stored when the document is created + // with the first chunk (pattern from testCreateBucketFile) + $source = __DIR__ . '/../../../resources/disk-a/large-file.mp4'; + $size = \filesize($source); + $chunkSize = 5 * 1024 * 1024; + $handle = @\fopen($source, 'rb'); + $mimeType = \mime_content_type($source); + $counter = 0; + $id = ''; + $chunked = null; + $headers = [ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ]; + while (!\feof($handle)) { + $curlFile = new CURLFile('data://' . $mimeType . ';base64,' . \base64_encode(@\fread($handle, $chunkSize)), $mimeType, 'large-file.mp4'); + $headers['content-range'] = 'bytes ' . ($counter * $chunkSize) . '-' . \min(((($counter * $chunkSize) + $chunkSize) - 1), $size - 1) . '/' . $size; + if (!empty($id)) { + $headers['x-appwrite-id'] = $id; + } + $chunked = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', \array_merge($headers, $this->getHeaders()), [ + 'fileId' => 'unique()', + 'file' => $curlFile, + 'parent' => 'videos/2026', + ]); + $this->assertNotEmpty($chunked['body']['$id']); + $id = $chunked['body']['$id']; + $counter++; + } + \fclose($handle); + $this->assertEquals(201, $chunked['headers']['status-code']); + $this->assertEquals('videos/2026/', $chunked['body']['parent']); + $this->assertEquals('videos/2026/large-file.mp4', $chunked['body']['key']); + } + public function testCreateBucketFileZstdCompression(): void { $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ From 4037de3eb5c7ccbb345bc37e1aeca00dbc42e496 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:21:48 +0400 Subject: [PATCH 05/24] Add parent filter to list files and whitelist parent queries --- .../Storage/Http/Buckets/Files/XList.php | 11 +++ .../Database/Validator/Queries/Files.php | 1 + tests/e2e/Services/Storage/StorageBase.php | 67 +++++++++++++++++++ 3 files changed, 79 insertions(+) diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php index de61ea5910..93ade4bb32 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php @@ -7,6 +7,7 @@ use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; +use Appwrite\Utopia\Database\Validator\Folder; use Appwrite\Utopia\Database\Validator\Queries\Files; use Appwrite\Utopia\Response; use Utopia\Database\Database; @@ -22,6 +23,7 @@ use Utopia\Database\Validator\UID; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Boolean; +use Utopia\Validator\Nullable; use Utopia\Validator\Text; class XList extends Action @@ -60,6 +62,7 @@ class XList extends Action ->param('queries', [], new Files(), '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. You may filter on the following attributes: ' . implode(', ', Files::ALLOWED_ATTRIBUTES), true) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) ->param('total', true, new Boolean(true), 'When set to false, the total count returned will be 0 and will not be calculated.', true) + ->param('parent', null, new Nullable(new Folder()), 'Filter results to files directly inside this virtual folder. Pass an empty string for the bucket root. Returns files from all folders when omitted.', true) ->inject('response') ->inject('dbForProject') ->inject('mode') @@ -73,6 +76,7 @@ class XList extends Action array $queries, string $search, bool $includeTotal, + ?string $parent, Response $response, Database $dbForProject, string $mode, @@ -104,6 +108,13 @@ class XList extends Action $queries[] = Query::search('search', $search); } + if (!\is_null($parent)) { + $parent = Folder::normalize($parent); + $queries[] = $parent === '' + ? Query::or([Query::equal('parent', ['']), Query::isNull('parent')]) + : Query::equal('parent', [$parent]); + } + $cursor = Query::getCursorQueries($queries, false); $cursor = \reset($cursor); diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php index 1941eabcdb..da3f12d266 100644 --- a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php +++ b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php @@ -6,6 +6,7 @@ class Files extends Base { public const ALLOWED_ATTRIBUTES = [ 'name', + 'parent', 'signature', 'mimeType', 'sizeOriginal', diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index f90a967148..1de9efd63a 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -1997,4 +1997,71 @@ trait StorageBase /* will always be 0 in tests because the worker runs hourly! */ $this->assertGreaterThanOrEqual(0, $bucket['body']['totalSize']); } + + public function testListFilesByParent(): void + { + $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'bucketId' => ID::unique(), + 'name' => 'Test Bucket Parent Filter', + 'fileSecurity' => true, + 'permissions' => [ + Permission::read(Role::any()), + Permission::create(Role::any()), + ], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + $upload = function (string $parent) use ($bucketId): void { + $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => $parent, + 'permissions' => [Permission::read(Role::any())], + ]); + $this->assertEquals(201, $file['headers']['status-code']); + }; + + $upload(''); + $upload('photos'); + $upload('photos/2026'); + + $list = function (array $params) use ($bucketId): array { + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), $params); + $this->assertEquals(200, $response['headers']['status-code']); + return $response['body']; + }; + + // no filter -- all files + $this->assertEquals(3, $list([])['total']); + + // exact match -- immediate children only + $this->assertEquals(1, $list(['parent' => 'photos'])['total']); + $this->assertEquals('photos/', $list(['parent' => 'photos'])['files'][0]['parent']); + + // root only + $this->assertEquals(1, $list(['parent' => ''])['total']); + $this->assertEquals('', $list(['parent' => ''])['files'][0]['parent']); + + // recursive via queries + $recursive = $list(['queries' => [Query::startsWith('parent', 'photos/')->toString()]]); + $this->assertEquals(2, $recursive['total']); + + // invalid parent + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), ['parent' => '/photos']); + $this->assertEquals(400, $response['headers']['status-code']); + } } From 0e0a5a38e7ada44f7f29988287ff391d079f127c Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:28:44 +0400 Subject: [PATCH 06/24] Add derived folder listing endpoint for storage buckets --- app/init/models.php | 3 + docs/references/storage/list-folders.md | 1 + .../Storage/Http/Buckets/Folders/XList.php | 153 ++++++++++++++++++ .../Modules/Storage/Services/Http.php | 4 + src/Appwrite/Utopia/Response.php | 2 + src/Appwrite/Utopia/Response/Model/Folder.php | 53 ++++++ tests/e2e/Services/Storage/StorageBase.php | 81 ++++++++++ 7 files changed, 297 insertions(+) create mode 100644 docs/references/storage/list-folders.md create mode 100644 src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php create mode 100644 src/Appwrite/Utopia/Response/Model/Folder.php diff --git a/app/init/models.php b/app/init/models.php index cdb2a9b9b6..411f6acc89 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -80,6 +80,7 @@ use Appwrite\Utopia\Response\Model\Error; use Appwrite\Utopia\Response\Model\ErrorDev; use Appwrite\Utopia\Response\Model\Execution; use Appwrite\Utopia\Response\Model\File; +use Appwrite\Utopia\Response\Model\Folder; use Appwrite\Utopia\Response\Model\Framework; use Appwrite\Utopia\Response\Model\FrameworkAdapter; use Appwrite\Utopia\Response\Model\Func; @@ -254,6 +255,7 @@ Response::setModel(new BaseList('Identities List', Response::MODEL_IDENTITY_LIST Response::setModel(new BaseList('Notifications List', Response::MODEL_NOTIFICATION_LIST, 'notifications', Response::MODEL_NOTIFICATION)); Response::setModel(new BaseList('Logs List', Response::MODEL_LOG_LIST, 'logs', Response::MODEL_LOG)); Response::setModel(new BaseList('Files List', Response::MODEL_FILE_LIST, 'files', Response::MODEL_FILE)); +Response::setModel(new BaseList('Folders List', Response::MODEL_FOLDER_LIST, 'folders', Response::MODEL_FOLDER, paging: false)); Response::setModel(new BaseList('Buckets List', Response::MODEL_BUCKET_LIST, 'buckets', Response::MODEL_BUCKET)); Response::setModel(new BaseList('Resource Tokens List', Response::MODEL_RESOURCE_TOKEN_LIST, 'tokens', Response::MODEL_RESOURCE_TOKEN)); Response::setModel(new BaseList('Teams List', Response::MODEL_TEAM_LIST, 'teams', Response::MODEL_TEAM)); @@ -389,6 +391,7 @@ Response::setModel(new JWT()); Response::setModel(new Locale()); Response::setModel(new LocaleCode()); Response::setModel(new File()); +Response::setModel(new Folder()); Response::setModel(new Bucket()); Response::setModel(new ResourceToken()); Response::setModel(new Team()); diff --git a/docs/references/storage/list-folders.md b/docs/references/storage/list-folders.md new file mode 100644 index 0000000000..62d99808f2 --- /dev/null +++ b/docs/references/storage/list-folders.md @@ -0,0 +1 @@ +Get a list of the child folders directly inside a virtual folder in a bucket. Folders are derived from the parent paths of existing files: a folder exists while at least one file lives under it, and empty pages mean the listing is complete. diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php new file mode 100644 index 0000000000..0d67ffef1d --- /dev/null +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -0,0 +1,153 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/storage/buckets/:bucketId/folders') + ->desc('List folders') + ->groups(['api', 'storage']) + ->label('scope', 'files.read') + ->label('usage.resource', 'bucket/{request.bucketId}') + ->label('resourceType', RESOURCE_TYPE_BUCKETS) + ->label('sdk', new Method( + namespace: 'storage', + group: 'files', + name: 'listFolders', + description: '/docs/references/storage/list-folders.md', + auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_FOLDER_LIST, + ) + ] + )) + ->param('bucketId', '', new UID(), 'Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket).') + ->param('parent', '', new Folder(), 'Virtual folder to list the child folders of. Defaults to the bucket root.', true) + ->param('limit', 25, new Range(1, 100), 'Maximum number of folders to return. Must be between 1 and 100. A page shorter than this limit means the listing is complete.', true) + ->param('cursor', '', new Folder(), 'Folder path returned last by a previous page, used to continue the listing.', true) + ->inject('response') + ->inject('dbForProject') + ->inject('authorization') + ->inject('user') + ->callback($this->action(...)); + } + + public function action( + string $bucketId, + string $parent, + int $limit, + string $cursor, + Response $response, + Database $dbForProject, + Authorization $authorization, + User $user + ) { + $bucket = $authorization->skip(fn () => $dbForProject->getDocument('buckets', $bucketId)); + + $isAPIKey = $user->isKey($authorization->getRoles()); + $isPrivilegedUser = $user->isPrivileged($authorization->getRoles()); + + if ($bucket->isEmpty() || (!$bucket->getAttribute('enabled') && !$isAPIKey && !$isPrivilegedUser)) { + throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); + } + + $fileSecurity = $bucket->getAttribute('fileSecurity', false); + $valid = $authorization->isValid(new Input(Database::PERMISSION_READ, $bucket->getRead())); + if (!$fileSecurity && !$valid) { + throw new Exception(Exception::USER_UNAUTHORIZED, $authorization->getDescription()); + } + + $parent = Folder::normalize($parent); + $cursor = Folder::normalize($cursor); + + if ($cursor !== '' && (!\str_starts_with($cursor, $parent) || $cursor === $parent)) { + throw new Exception(Exception::GENERAL_CURSOR_NOT_FOUND, "Folder '{$cursor}' for the 'cursor' value is not inside '{$parent}'."); + } + + $collection = 'bucket_' . $bucket->getSequence(); + $seek = $cursor === '' ? $parent : self::seekPast($cursor); + $folders = []; + + try { + while (\count($folders) < $limit) { + $queries = [ + Query::greaterThan('parent', $seek), + Query::orderAsc('parent'), + Query::limit(1), + ]; + if ($parent !== '') { + $queries[] = Query::startsWith('parent', $parent); + } + + if ($fileSecurity && !$valid) { + $results = $dbForProject->find($collection, $queries); + } else { + $results = $authorization->skip(fn () => $dbForProject->find($collection, $queries)); + } + + if (empty($results)) { + break; + } + + $fileParent = $results[0]->getAttribute('parent', ''); + $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; + $key = $parent . $segment . '/'; + + $folders[] = new Document([ + 'key' => $key, + 'name' => $segment, + 'parent' => $parent, + ]); + + $seek = self::seekPast($key); + } + } catch (NotFoundException) { + throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); + } + + $response->dynamic(new Document([ + 'folders' => $folders, + ]), Response::MODEL_FOLDER_LIST); + } + + /** + * Smallest string that sorts after every `parent` value inside the given + * folder: the trailing '/' replaced with the next code point ('0'), so a + * seek jumps past all of the folder's contents in one indexed query. + */ + private static function seekPast(string $folder): string + { + return \substr($folder, 0, -1) . \chr(\ord('/') + 1); + } +} diff --git a/src/Appwrite/Platform/Modules/Storage/Services/Http.php b/src/Appwrite/Platform/Modules/Storage/Services/Http.php index 4010918205..dd7b8a900e 100644 --- a/src/Appwrite/Platform/Modules/Storage/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Storage/Services/Http.php @@ -13,6 +13,7 @@ use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Push\Get as GetFileForP use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Update as UpdateFile; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\View\Get as GetFileView; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\XList as ListFiles; +use Appwrite\Platform\Modules\Storage\Http\Buckets\Folders\XList as ListFolders; use Appwrite\Platform\Modules\Storage\Http\Buckets\Get as GetBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\Update as UpdateBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\XList as ListBuckets; @@ -41,5 +42,8 @@ class Http extends Service $this->addAction(GetFileDownload::getName(), new GetFileDownload()); $this->addAction(GetFileView::getName(), new GetFileView()); $this->addAction(GetFileForPush::getName(), new GetFileForPush()); + + // Folders + $this->addAction(ListFolders::getName(), new ListFolders()); } } diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index e6b713d530..8494cb3705 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -157,6 +157,8 @@ class Response extends SwooleResponse public const MODEL_FILE_LIST = 'fileList'; public const MODEL_BUCKET = 'bucket'; public const MODEL_BUCKET_LIST = 'bucketList'; + public const MODEL_FOLDER = 'folder'; + public const MODEL_FOLDER_LIST = 'folderList'; public const MODEL_RESOURCE_TOKEN = 'resourceToken'; public const MODEL_RESOURCE_TOKEN_LIST = 'resourceTokenList'; diff --git a/src/Appwrite/Utopia/Response/Model/Folder.php b/src/Appwrite/Utopia/Response/Model/Folder.php new file mode 100644 index 0000000000..10bc40837b --- /dev/null +++ b/src/Appwrite/Utopia/Response/Model/Folder.php @@ -0,0 +1,53 @@ +addRule('key', [ + 'type' => self::TYPE_STRING, + 'description' => 'Full folder path, with a trailing slash.', + 'default' => '', + 'example' => 'photos/2026/', + ]) + ->addRule('name', [ + 'type' => self::TYPE_STRING, + 'description' => 'Folder name: the last segment of the path.', + 'default' => '', + 'example' => '2026', + ]) + ->addRule('parent', [ + 'type' => self::TYPE_STRING, + 'description' => 'Parent folder path with a trailing slash. Empty for top-level folders.', + 'default' => '', + 'example' => 'photos/', + ]) + ; + } + + /** + * Get Name + * + * @return string + */ + public function getName(): string + { + return 'Folder'; + } + + /** + * Get Type + * + * @return string + */ + public function getType(): string + { + return Response::MODEL_FOLDER; + } +} diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 1de9efd63a..163059be40 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -2064,4 +2064,85 @@ trait StorageBase ], $this->getHeaders()), ['parent' => '/photos']); $this->assertEquals(400, $response['headers']['status-code']); } + + public function testListFolders(): void + { + $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'bucketId' => ID::unique(), + 'name' => 'Test Bucket Folder Listing', + 'fileSecurity' => true, + 'permissions' => [ + Permission::read(Role::any()), + Permission::create(Role::any()), + Permission::delete(Role::any()), + ], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + $upload = function (string $parent) use ($bucketId): string { + $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => $parent, + 'permissions' => [Permission::read(Role::any()), Permission::delete(Role::any())], + ]); + $this->assertEquals(201, $file['headers']['status-code']); + return $file['body']['$id']; + }; + + $upload(''); + $upload('invoices'); + $upload('photos/2025'); + $julyFileId = $upload('photos/2026/july'); + + $listFolders = function (array $params) use ($bucketId): array { + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), $params); + $this->assertEquals(200, $response['headers']['status-code']); + return $response['body']['folders']; + }; + + // top level, alphabetical + $folders = $listFolders([]); + $this->assertCount(2, $folders); + $this->assertEquals(['invoices/', 'photos/'], \array_column($folders, 'key')); + $this->assertEquals(['invoices', 'photos'], \array_column($folders, 'name')); + $this->assertEquals(['', ''], \array_column($folders, 'parent')); + + // nested level -- deep files imply intermediate folders + $folders = $listFolders(['parent' => 'photos']); + $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); + + $folders = $listFolders(['parent' => 'photos/2026']); + $this->assertEquals(['photos/2026/july/'], \array_column($folders, 'key')); + + // pagination + $page = $listFolders(['limit' => 1]); + $this->assertEquals(['invoices/'], \array_column($page, 'key')); + $page = $listFolders(['limit' => 1, 'cursor' => 'invoices/']); + $this->assertEquals(['photos/'], \array_column($page, 'key')); + $page = $listFolders(['limit' => 1, 'cursor' => 'photos/']); + $this->assertCount(0, $page); + + // nonexistent prefix -- empty list, not 404 + $this->assertCount(0, $listFolders(['parent' => 'missing'])); + + // implicit lifecycle -- deleting the last file removes the folder chain + $delete = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId . '/files/' . $julyFileId, array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders())); + $this->assertEquals(204, $delete['headers']['status-code']); + $this->assertEquals(['photos/2025/'], \array_column($listFolders(['parent' => 'photos']), 'key')); + } } From ea68308838f6af7dc89c59ef301ad4bebfd3936a Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:36:55 +0400 Subject: [PATCH 07/24] Test folder listing visibility with file security --- .../Storage/StorageCustomClientTest.php | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index 7f188241b4..a851018e6d 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1606,4 +1606,44 @@ final class StorageCustomClientTest extends Scope ]); $this->assertEquals(204, $response['headers']['status-code']); } + + public function testListFoldersFileSecurityVisibility(): void + { + $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'bucketId' => ID::unique(), + 'name' => 'Folder Visibility', + 'fileSecurity' => true, + 'permissions' => [], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + $upload = function (string $parent, array $permissions) use ($bucketId): void { + $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', [ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => $parent, + 'permissions' => $permissions, + ]); + $this->assertEquals(201, $file['headers']['status-code']); + }; + + $upload('secret', []); + $upload('shared', [Permission::read(Role::any())]); + + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders())); + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals(['shared/'], \array_column($response['body']['folders'], 'key')); + } } From ff14e5dcec49a021cce23334945d79b6604b26a1 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:57:55 +0400 Subject: [PATCH 08/24] Add bucket teardown to folder tests and dot segment validator case --- tests/e2e/Services/Storage/StorageBase.php | 21 +++++++++++++++++++ .../Storage/StorageCustomClientTest.php | 7 +++++++ .../Utopia/Database/Validator/FolderTest.php | 1 + 3 files changed, 29 insertions(+) diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 163059be40..295303abb3 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -596,6 +596,13 @@ trait StorageBase $this->assertEquals(201, $chunked['headers']['status-code']); $this->assertEquals('videos/2026/', $chunked['body']['parent']); $this->assertEquals('videos/2026/large-file.mp4', $chunked['body']['key']); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); } public function testCreateBucketFileZstdCompression(): void @@ -2063,6 +2070,13 @@ trait StorageBase 'x-appwrite-project' => $this->getProject()['$id'], ], $this->getHeaders()), ['parent' => '/photos']); $this->assertEquals(400, $response['headers']['status-code']); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); } public function testListFolders(): void @@ -2144,5 +2158,12 @@ trait StorageBase ], $this->getHeaders())); $this->assertEquals(204, $delete['headers']['status-code']); $this->assertEquals(['photos/2025/'], \array_column($listFolders(['parent' => 'photos']), 'key')); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); } } diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index a851018e6d..1ddd8bd57c 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1645,5 +1645,12 @@ final class StorageCustomClientTest extends Scope ], $this->getHeaders())); $this->assertEquals(200, $response['headers']['status-code']); $this->assertEquals(['shared/'], \array_column($response['body']['folders'], 'key')); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); } } diff --git a/tests/unit/Utopia/Database/Validator/FolderTest.php b/tests/unit/Utopia/Database/Validator/FolderTest.php index d313526db9..d645788bb2 100644 --- a/tests/unit/Utopia/Database/Validator/FolderTest.php +++ b/tests/unit/Utopia/Database/Validator/FolderTest.php @@ -38,6 +38,7 @@ final class FolderTest extends TestCase $this->assertFalse($this->object->isValid('photos/./2026')); $this->assertFalse($this->object->isValid('photos/../2026')); $this->assertFalse($this->object->isValid('..')); + $this->assertFalse($this->object->isValid('.')); $this->assertFalse($this->object->isValid("photos/\x01")); $this->assertFalse($this->object->isValid("photos\n")); // 2048 chars without trailing slash normalizes to 2049 -- too long From a8beaaabbadfccc80dbe6d900f50f0981ac0cc71 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 21:46:45 +0400 Subject: [PATCH 09/24] Validate folder cursor as immediate child and correct error code --- .../Modules/Storage/Http/Buckets/Folders/XList.php | 9 +++++++-- tests/e2e/Services/Storage/StorageBase.php | 12 ++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php index 0d67ffef1d..ee69a39a0b 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -91,8 +91,11 @@ class XList extends Action $parent = Folder::normalize($parent); $cursor = Folder::normalize($cursor); - if ($cursor !== '' && (!\str_starts_with($cursor, $parent) || $cursor === $parent)) { - throw new Exception(Exception::GENERAL_CURSOR_NOT_FOUND, "Folder '{$cursor}' for the 'cursor' value is not inside '{$parent}'."); + if ($cursor !== '') { + $remainder = \substr($cursor, \strlen($parent), -1); + if (!\str_starts_with($cursor, $parent) || $cursor === $parent || \str_contains($remainder, '/')) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, "Folder '{$cursor}' for the 'cursor' value is not an immediate child of '{$parent}'."); + } } $collection = 'bucket_' . $bucket->getSequence(); @@ -145,6 +148,8 @@ class XList extends Action * Smallest string that sorts after every `parent` value inside the given * folder: the trailing '/' replaced with the next code point ('0'), so a * seek jumps past all of the folder's contents in one indexed query. + * Assumes the database orders `parent` values bytewise (binary collation), + * so nothing sorts between '/' (0x2F) and '0' (0x30). */ private static function seekPast(string $folder): string { diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 295303abb3..e3c0a7c8b2 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -2151,6 +2151,18 @@ trait StorageBase // nonexistent prefix -- empty list, not 404 $this->assertCount(0, $listFolders(['parent' => 'missing'])); + // crafted cursors -- must be an immediate child of parent + foreach ([ + ['parent' => 'photos', 'cursor' => 'photos/2026/july'], // grandchild + ['parent' => 'photos', 'cursor' => 'invoices'], // outside parent + ] as $params) { + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), $params); + $this->assertEquals(400, $response['headers']['status-code']); + } + // implicit lifecycle -- deleting the last file removes the folder chain $delete = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId . '/files/' . $julyFileId, array_merge([ 'content-type' => 'application/json', From ef9581e4c7e89735b51751dd4edade003045e5e0 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 22:05:21 +0400 Subject: [PATCH 10/24] Use assertSame for scalar assertions per Rector --- tests/e2e/Services/Storage/StorageCustomClientTest.php | 2 +- tests/unit/Utopia/Database/Validator/FolderTest.php | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index 1ddd8bd57c..215df8627f 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1644,7 +1644,7 @@ final class StorageCustomClientTest extends Scope 'x-appwrite-project' => $this->getProject()['$id'], ], $this->getHeaders())); $this->assertEquals(200, $response['headers']['status-code']); - $this->assertEquals(['shared/'], \array_column($response['body']['folders'], 'key')); + $this->assertSame(['shared/'], \array_column($response['body']['folders'], 'key')); $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ 'content-type' => 'application/json', diff --git a/tests/unit/Utopia/Database/Validator/FolderTest.php b/tests/unit/Utopia/Database/Validator/FolderTest.php index d645788bb2..c95165ef74 100644 --- a/tests/unit/Utopia/Database/Validator/FolderTest.php +++ b/tests/unit/Utopia/Database/Validator/FolderTest.php @@ -48,9 +48,9 @@ final class FolderTest extends TestCase public function testNormalize(): void { - $this->assertEquals('', Folder::normalize('')); - $this->assertEquals('photos/', Folder::normalize('photos')); - $this->assertEquals('photos/', Folder::normalize('photos/')); - $this->assertEquals('photos/2026/', Folder::normalize('photos/2026')); + $this->assertSame('', Folder::normalize('')); + $this->assertSame('photos/', Folder::normalize('photos')); + $this->assertSame('photos/', Folder::normalize('photos/')); + $this->assertSame('photos/2026/', Folder::normalize('photos/2026')); } } From 99ee9714c93bf79285024a3a6d490c8818bcfa35 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Tue, 7 Jul 2026 12:20:44 +0400 Subject: [PATCH 11/24] Rename public folder attribute and params from parent to folder --- app/config/collections/common.php | 6 +-- docs/references/storage/list-folders.md | 2 +- src/Appwrite/Migration/Version/V25.php | 14 +++--- .../Storage/Http/Buckets/Files/Create.php | 14 +++--- .../Storage/Http/Buckets/Files/XList.php | 14 +++--- .../Storage/Http/Buckets/Folders/XList.php | 18 ++++---- .../Database/Validator/Queries/Files.php | 2 +- src/Appwrite/Utopia/Response/Model/File.php | 10 ++-- tests/e2e/Services/Storage/StorageBase.php | 46 +++++++++---------- .../Storage/StorageCustomClientTest.php | 4 +- 10 files changed, 65 insertions(+), 65 deletions(-) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index a2379229a3..ccf13a4eea 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2531,7 +2531,7 @@ return [ 'filters' => [], ], [ - '$id' => ID::custom('parent'), + '$id' => ID::custom('folder'), 'type' => Database::VAR_STRING, 'format' => '', 'size' => 2048, @@ -2730,9 +2730,9 @@ return [ 'orders' => [Database::ORDER_ASC], ], [ - '$id' => ID::custom('_key_parent'), + '$id' => ID::custom('_key_folder'), 'type' => Database::INDEX_KEY, - 'attributes' => ['parent'], + 'attributes' => ['folder'], 'lengths' => [256], 'orders' => [Database::ORDER_ASC], ], diff --git a/docs/references/storage/list-folders.md b/docs/references/storage/list-folders.md index 62d99808f2..446580b223 100644 --- a/docs/references/storage/list-folders.md +++ b/docs/references/storage/list-folders.md @@ -1 +1 @@ -Get a list of the child folders directly inside a virtual folder in a bucket. Folders are derived from the parent paths of existing files: a folder exists while at least one file lives under it, and empty pages mean the listing is complete. +Get a list of the child folders directly inside a virtual folder in a bucket. Folders are derived from the folder paths of existing files: a folder exists while at least one file lives under it, and empty pages mean the listing is complete. diff --git a/src/Appwrite/Migration/Version/V25.php b/src/Appwrite/Migration/Version/V25.php index b2c65fd9f8..3ca42d2af3 100644 --- a/src/Appwrite/Migration/Version/V25.php +++ b/src/Appwrite/Migration/Version/V25.php @@ -73,7 +73,7 @@ class V25 extends Migration } /** - * Add the virtual folder `parent` attribute and index to every + * Add the virtual folder `folder` attribute and index to every * per-bucket files collection. * * @return void @@ -86,19 +86,19 @@ class V25 extends Migration Console::log("Migrating Bucket {$bucket->getId()} ({$bucket->getAttribute('name')})"); try { - $this->createAttributeFromCollection($this->dbForProject, $bucketTable, 'parent', 'files'); + $this->createAttributeFromCollection($this->dbForProject, $bucketTable, 'folder', 'files'); } catch (Duplicate) { - Console::warning("'parent' from {$bucketTable}: Column already exists"); + Console::warning("'folder' from {$bucketTable}: Column already exists"); } catch (Throwable $th) { - Console::warning("'parent' from {$bucketTable}: {$th->getMessage()}"); + Console::warning("'folder' from {$bucketTable}: {$th->getMessage()}"); } try { - $this->createIndexFromCollection($this->dbForProject, $bucketTable, '_key_parent', 'files'); + $this->createIndexFromCollection($this->dbForProject, $bucketTable, '_key_folder', 'files'); } catch (Duplicate) { - Console::warning("'_key_parent' from {$bucketTable}: Index already exists"); + Console::warning("'_key_folder' from {$bucketTable}: Index already exists"); } catch (Throwable $th) { - Console::warning("'_key_parent' from {$bucketTable}: {$th->getMessage()}"); + Console::warning("'_key_folder' from {$bucketTable}: {$th->getMessage()}"); } $this->dbForProject->purgeCachedCollection($bucketTable); diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php index be11e4191b..c50718145b 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php @@ -86,7 +86,7 @@ class Create extends Action ->param('fileId', '', new CustomId(), 'File ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.') ->param('file', [], new File(), 'Binary file. Appwrite SDKs provide helpers to handle file input. [Learn about file input](https://appwrite.io/docs/products/storage/upload-download#input-file).', skipValidation: true) ->param('permissions', null, new Nullable(new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE, [Database::PERMISSION_READ, Database::PERMISSION_UPDATE, Database::PERMISSION_DELETE, Database::PERMISSION_WRITE])), 'An array of permission strings. By default, only the current user is granted all permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).', true) - ->param('parent', '', new Folder(), 'Virtual folder to place the file in, for example "photos/2026". Nest folders with `/`. Defaults to the bucket root.', true) + ->param('folder', '', new Folder(), 'Virtual folder to place the file in, for example "photos/2026". Nest folders with `/`. Defaults to the bucket root.', true) ->inject('request') ->inject('response') ->inject('dbForProject') @@ -105,7 +105,7 @@ class Create extends Action string $fileId, mixed $file, ?array $permissions, - string $parent, + string $folder, Request $request, Response $response, Database $dbForProject, @@ -193,7 +193,7 @@ class Create extends Action $contentRange = $request->getHeaderLine('content-range'); $fileId = $fileId === 'unique()' ? ID::unique() : $fileId; - $parent = Folder::normalize($parent); + $folder = Folder::normalize($folder); $chunk = 1; $chunks = 1; @@ -265,7 +265,7 @@ class Create extends Action }; try { - $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $parent, $path, $permissions, $response, &$completed): void { + $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $folder, $path, $permissions, $response, &$completed): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); if (!$file->isEmpty()) { $chunks = $file->getAttribute('chunksTotal', 1); @@ -296,7 +296,7 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, - 'parent' => $parent, + 'folder' => $folder, 'path' => $path, 'signature' => '', 'mimeType' => '', @@ -330,7 +330,7 @@ class Create extends Action return; } - $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $parent, $path, $permissions, $queueForEvents, $response): void { + $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $folder, $path, $permissions, $queueForEvents, $response): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); $uploaded = 0; @@ -433,7 +433,7 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, - 'parent' => $parent, + 'folder' => $folder, 'path' => $path, 'signature' => $fileHash, 'mimeType' => $mimeType, diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php index 93ade4bb32..e4ca2273f0 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php @@ -62,7 +62,7 @@ class XList extends Action ->param('queries', [], new Files(), '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. You may filter on the following attributes: ' . implode(', ', Files::ALLOWED_ATTRIBUTES), true) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) ->param('total', true, new Boolean(true), 'When set to false, the total count returned will be 0 and will not be calculated.', true) - ->param('parent', null, new Nullable(new Folder()), 'Filter results to files directly inside this virtual folder. Pass an empty string for the bucket root. Returns files from all folders when omitted.', true) + ->param('folder', null, new Nullable(new Folder()), 'Filter results to files directly inside this virtual folder. Pass an empty string for the bucket root. Returns files from all folders when omitted.', true) ->inject('response') ->inject('dbForProject') ->inject('mode') @@ -76,7 +76,7 @@ class XList extends Action array $queries, string $search, bool $includeTotal, - ?string $parent, + ?string $folder, Response $response, Database $dbForProject, string $mode, @@ -108,11 +108,11 @@ class XList extends Action $queries[] = Query::search('search', $search); } - if (!\is_null($parent)) { - $parent = Folder::normalize($parent); - $queries[] = $parent === '' - ? Query::or([Query::equal('parent', ['']), Query::isNull('parent')]) - : Query::equal('parent', [$parent]); + if (!\is_null($folder)) { + $folder = Folder::normalize($folder); + $queries[] = $folder === '' + ? Query::or([Query::equal('folder', ['']), Query::isNull('folder')]) + : Query::equal('folder', [$folder]); } $cursor = Query::getCursorQueries($queries, false); diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php index ee69a39a0b..d44d6eb99f 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -53,7 +53,7 @@ class XList extends Action ] )) ->param('bucketId', '', new UID(), 'Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket).') - ->param('parent', '', new Folder(), 'Virtual folder to list the child folders of. Defaults to the bucket root.', true) + ->param('folder', '', new Folder(), 'Virtual folder to list the child folders of. Defaults to the bucket root.', true) ->param('limit', 25, new Range(1, 100), 'Maximum number of folders to return. Must be between 1 and 100. A page shorter than this limit means the listing is complete.', true) ->param('cursor', '', new Folder(), 'Folder path returned last by a previous page, used to continue the listing.', true) ->inject('response') @@ -65,7 +65,7 @@ class XList extends Action public function action( string $bucketId, - string $parent, + string $folder, int $limit, string $cursor, Response $response, @@ -88,7 +88,7 @@ class XList extends Action throw new Exception(Exception::USER_UNAUTHORIZED, $authorization->getDescription()); } - $parent = Folder::normalize($parent); + $parent = Folder::normalize($folder); $cursor = Folder::normalize($cursor); if ($cursor !== '') { @@ -105,12 +105,12 @@ class XList extends Action try { while (\count($folders) < $limit) { $queries = [ - Query::greaterThan('parent', $seek), - Query::orderAsc('parent'), + Query::greaterThan('folder', $seek), + Query::orderAsc('folder'), Query::limit(1), ]; if ($parent !== '') { - $queries[] = Query::startsWith('parent', $parent); + $queries[] = Query::startsWith('folder', $parent); } if ($fileSecurity && !$valid) { @@ -123,7 +123,7 @@ class XList extends Action break; } - $fileParent = $results[0]->getAttribute('parent', ''); + $fileParent = $results[0]->getAttribute('folder', ''); $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; $key = $parent . $segment . '/'; @@ -145,10 +145,10 @@ class XList extends Action } /** - * Smallest string that sorts after every `parent` value inside the given + * Smallest string that sorts after every `folder` value inside the given * folder: the trailing '/' replaced with the next code point ('0'), so a * seek jumps past all of the folder's contents in one indexed query. - * Assumes the database orders `parent` values bytewise (binary collation), + * Assumes the database orders `folder` values bytewise (binary collation), * so nothing sorts between '/' (0x2F) and '0' (0x30). */ private static function seekPast(string $folder): string diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php index da3f12d266..4785e12d58 100644 --- a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php +++ b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php @@ -6,7 +6,7 @@ class Files extends Base { public const ALLOWED_ATTRIBUTES = [ 'name', - 'parent', + 'folder', 'signature', 'mimeType', 'sizeOriginal', diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 029f4defa0..75711d3ea9 100644 --- a/src/Appwrite/Utopia/Response/Model/File.php +++ b/src/Appwrite/Utopia/Response/Model/File.php @@ -49,7 +49,7 @@ class File extends Model 'default' => '', 'example' => 'Pink.png', ]) - ->addRule('parent', [ + ->addRule('folder', [ 'type' => self::TYPE_STRING, 'description' => 'Virtual folder containing the file, with a trailing slash. Empty for the bucket root.', 'default' => '', @@ -57,7 +57,7 @@ class File extends Model ]) ->addRule('key', [ 'type' => self::TYPE_STRING, - 'description' => 'Full virtual path of the file: the parent folder followed by the file name.', + 'description' => 'Full virtual path of the file: the folder followed by the file name.', 'default' => '', 'example' => 'photos/2026/Pink.png', ]) @@ -139,9 +139,9 @@ class File extends Model $encryption = !empty($document->getAttribute('openSSLCipher', '')); $document->setAttribute('encryption', $encryption); - $parent = $document->getAttribute('parent') ?? ''; - $document->setAttribute('parent', $parent); - $document->setAttribute('key', $parent . $document->getAttribute('name', '')); + $folder = $document->getAttribute('folder') ?? ''; + $document->setAttribute('folder', $folder); + $document->setAttribute('key', $folder . $document->getAttribute('name', '')); return $document; } diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index e3c0a7c8b2..fa6aed29c5 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -518,10 +518,10 @@ trait StorageBase ], $this->getHeaders()), [ 'fileId' => ID::unique(), 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'parent' => 'photos/2026', + 'folder' => 'photos/2026', ]); $this->assertEquals(201, $file['headers']['status-code']); - $this->assertEquals('photos/2026/', $file['body']['parent']); + $this->assertEquals('photos/2026/', $file['body']['folder']); $this->assertEquals('photos/2026/logo.png', $file['body']['key']); $this->assertEquals('logo.png', $file['body']['name']); @@ -534,7 +534,7 @@ trait StorageBase 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), ]); $this->assertEquals(201, $rootFile['headers']['status-code']); - $this->assertEquals('', $rootFile['body']['parent']); + $this->assertEquals('', $rootFile['body']['folder']); $this->assertEquals('logo.png', $rootFile['body']['key']); // duplicate keys allowed -- same parent + name, different fileId @@ -544,7 +544,7 @@ trait StorageBase ], $this->getHeaders()), [ 'fileId' => ID::unique(), 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'parent' => 'photos/2026', + 'folder' => 'photos/2026', ]); $this->assertEquals(201, $duplicate['headers']['status-code']); $this->assertEquals('photos/2026/logo.png', $duplicate['body']['key']); @@ -558,7 +558,7 @@ trait StorageBase ], $this->getHeaders()), [ 'fileId' => ID::unique(), 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'parent' => $invalid, + 'folder' => $invalid, ]); $this->assertEquals(400, $res['headers']['status-code']); } @@ -586,7 +586,7 @@ trait StorageBase $chunked = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', \array_merge($headers, $this->getHeaders()), [ 'fileId' => 'unique()', 'file' => $curlFile, - 'parent' => 'videos/2026', + 'folder' => 'videos/2026', ]); $this->assertNotEmpty($chunked['body']['$id']); $id = $chunked['body']['$id']; @@ -594,7 +594,7 @@ trait StorageBase } \fclose($handle); $this->assertEquals(201, $chunked['headers']['status-code']); - $this->assertEquals('videos/2026/', $chunked['body']['parent']); + $this->assertEquals('videos/2026/', $chunked['body']['folder']); $this->assertEquals('videos/2026/large-file.mp4', $chunked['body']['key']); $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ @@ -2023,14 +2023,14 @@ trait StorageBase $this->assertEquals(201, $bucket['headers']['status-code']); $bucketId = $bucket['body']['$id']; - $upload = function (string $parent) use ($bucketId): void { + $upload = function (string $folder) use ($bucketId): void { $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ 'content-type' => 'multipart/form-data', 'x-appwrite-project' => $this->getProject()['$id'], ], $this->getHeaders()), [ 'fileId' => ID::unique(), 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'parent' => $parent, + 'folder' => $folder, 'permissions' => [Permission::read(Role::any())], ]); $this->assertEquals(201, $file['headers']['status-code']); @@ -2053,22 +2053,22 @@ trait StorageBase $this->assertEquals(3, $list([])['total']); // exact match -- immediate children only - $this->assertEquals(1, $list(['parent' => 'photos'])['total']); - $this->assertEquals('photos/', $list(['parent' => 'photos'])['files'][0]['parent']); + $this->assertEquals(1, $list(['folder' => 'photos'])['total']); + $this->assertEquals('photos/', $list(['folder' => 'photos'])['files'][0]['folder']); // root only - $this->assertEquals(1, $list(['parent' => ''])['total']); - $this->assertEquals('', $list(['parent' => ''])['files'][0]['parent']); + $this->assertEquals(1, $list(['folder' => ''])['total']); + $this->assertEquals('', $list(['folder' => ''])['files'][0]['folder']); // recursive via queries - $recursive = $list(['queries' => [Query::startsWith('parent', 'photos/')->toString()]]); + $recursive = $list(['queries' => [Query::startsWith('folder', 'photos/')->toString()]]); $this->assertEquals(2, $recursive['total']); // invalid parent $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ 'content-type' => 'application/json', 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), ['parent' => '/photos']); + ], $this->getHeaders()), ['folder' => '/photos']); $this->assertEquals(400, $response['headers']['status-code']); $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ @@ -2098,14 +2098,14 @@ trait StorageBase $this->assertEquals(201, $bucket['headers']['status-code']); $bucketId = $bucket['body']['$id']; - $upload = function (string $parent) use ($bucketId): string { + $upload = function (string $folder) use ($bucketId): string { $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ 'content-type' => 'multipart/form-data', 'x-appwrite-project' => $this->getProject()['$id'], ], $this->getHeaders()), [ 'fileId' => ID::unique(), 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'parent' => $parent, + 'folder' => $folder, 'permissions' => [Permission::read(Role::any()), Permission::delete(Role::any())], ]); $this->assertEquals(201, $file['headers']['status-code']); @@ -2134,10 +2134,10 @@ trait StorageBase $this->assertEquals(['', ''], \array_column($folders, 'parent')); // nested level -- deep files imply intermediate folders - $folders = $listFolders(['parent' => 'photos']); + $folders = $listFolders(['folder' => 'photos']); $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); - $folders = $listFolders(['parent' => 'photos/2026']); + $folders = $listFolders(['folder' => 'photos/2026']); $this->assertEquals(['photos/2026/july/'], \array_column($folders, 'key')); // pagination @@ -2149,12 +2149,12 @@ trait StorageBase $this->assertCount(0, $page); // nonexistent prefix -- empty list, not 404 - $this->assertCount(0, $listFolders(['parent' => 'missing'])); + $this->assertCount(0, $listFolders(['folder' => 'missing'])); // crafted cursors -- must be an immediate child of parent foreach ([ - ['parent' => 'photos', 'cursor' => 'photos/2026/july'], // grandchild - ['parent' => 'photos', 'cursor' => 'invoices'], // outside parent + ['folder' => 'photos', 'cursor' => 'photos/2026/july'], // grandchild + ['folder' => 'photos', 'cursor' => 'invoices'], // outside parent ] as $params) { $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ 'content-type' => 'application/json', @@ -2169,7 +2169,7 @@ trait StorageBase 'x-appwrite-project' => $this->getProject()['$id'], ], $this->getHeaders())); $this->assertEquals(204, $delete['headers']['status-code']); - $this->assertEquals(['photos/2025/'], \array_column($listFolders(['parent' => 'photos']), 'key')); + $this->assertEquals(['photos/2025/'], \array_column($listFolders(['folder' => 'photos']), 'key')); $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ 'content-type' => 'application/json', diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index 215df8627f..778bf6c2f0 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1622,7 +1622,7 @@ final class StorageCustomClientTest extends Scope $this->assertEquals(201, $bucket['headers']['status-code']); $bucketId = $bucket['body']['$id']; - $upload = function (string $parent, array $permissions) use ($bucketId): void { + $upload = function (string $folder, array $permissions) use ($bucketId): void { $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', [ 'content-type' => 'multipart/form-data', 'x-appwrite-project' => $this->getProject()['$id'], @@ -1630,7 +1630,7 @@ final class StorageCustomClientTest extends Scope ], [ 'fileId' => ID::unique(), 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'parent' => $parent, + 'folder' => $folder, 'permissions' => $permissions, ]); $this->assertEquals(201, $file['headers']['status-code']); From 1164bec4864a702ea199fbd73a159d6fddf359d0 Mon Sep 17 00:00:00 2001 From: fogelito Date: Tue, 7 Jul 2026 16:25:43 +0300 Subject: [PATCH 12/24] skip events --- app/controllers/general.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/controllers/general.php b/app/controllers/general.php index 8e2fd23d46..aa0f6b3864 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -1707,6 +1707,8 @@ Http::get('/v1/ping') $queueForEvents ->setParam('projectId', $project->getId()) ->setPayload($response->output($project, Response::MODEL_PROJECT)); + } else { + $queueForEvents->setEvent(''); } $response->text('Pong!'); From 8f1211c38bef4deb40a5f01f5ccdccd952b65046 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Tue, 7 Jul 2026 17:27:50 +0400 Subject: [PATCH 13/24] Purge metadata cache for bucket tables in V25 migration --- src/Appwrite/Migration/Version/V25.php | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Appwrite/Migration/Version/V25.php b/src/Appwrite/Migration/Version/V25.php index 3ca42d2af3..c66bd0384c 100644 --- a/src/Appwrite/Migration/Version/V25.php +++ b/src/Appwrite/Migration/Version/V25.php @@ -102,6 +102,7 @@ class V25 extends Migration } $this->dbForProject->purgeCachedCollection($bucketTable); + $this->dbForProject->purgeCachedDocument(Database::METADATA, $bucketTable); }); } } From 0f9f0db9dc96cf502c610937550db8453d29486f Mon Sep 17 00:00:00 2001 From: fogelito Date: Tue, 7 Jul 2026 16:52:57 +0300 Subject: [PATCH 14/24] setEvent --- app/controllers/general.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/app/controllers/general.php b/app/controllers/general.php index 48c910188a..c8d266cf8d 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -1664,7 +1664,6 @@ Http::get('/v1/ping') ->groups(['api', 'general']) ->desc('Test the connection between the Appwrite and the SDK.') ->label('scope', 'global') - ->label('event', 'projects.[projectId].ping') ->label('sdk', new Method( namespace: 'ping', group: null, @@ -1699,10 +1698,9 @@ Http::get('/v1/ping') ]))); $queueForEvents + ->setEvent('projects.[projectId].ping') ->setParam('projectId', $project->getId()) ->setPayload($response->output($project, Response::MODEL_PROJECT)); - } else { - $queueForEvents->setEvent(''); } $response->text('Pong!'); From 58e6954c188d48ebb798f9da8cfecf23ff32fe39 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Wed, 8 Jul 2026 07:16:01 +0545 Subject: [PATCH 15/24] feat(projects): add dedicated database create methods to onboarding Track dedicated-database provisioning (mysql/postgresql/mongo) as onboarding stages. The API shutdown hook records each engine's create call under project.onboarding; the console can OR them into a single "created a dedicated database" milestone. CLO-4530 --- app/config/onboarding.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 014301a72e..1a3857a7cc 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -33,6 +33,11 @@ return [ 'databases.create' => true, 'databases.createCollection' => true, 'databases.createDocument' => true, + // Databases — dedicated (cloud, per engine). OR them in the UI for a single + // "created a dedicated database" milestone. + 'mysql.create' => true, + 'postgresql.create' => true, + 'mongo.create' => true, // Storage 'storage.createBucket' => true, From b5608b6b71243cc9bf0a3d3214b5eb6dfc228295 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Wed, 8 Jul 2026 08:13:50 +0545 Subject: [PATCH 16/24] chore: trim onboarding comment to match existing style --- app/config/onboarding.php | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 1a3857a7cc..21a105b878 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -33,8 +33,7 @@ return [ 'databases.create' => true, 'databases.createCollection' => true, 'databases.createDocument' => true, - // Databases — dedicated (cloud, per engine). OR them in the UI for a single - // "created a dedicated database" milestone. + // Databases — dedicated 'mysql.create' => true, 'postgresql.create' => true, 'mongo.create' => true, From d8854fb69a11bdbe4aa273ac1248b6945dcc60e5 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Wed, 8 Jul 2026 10:52:47 +0530 Subject: [PATCH 17/24] Bump auth dependency to 0.8 --- composer.json | 2 +- composer.lock | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/composer.json b/composer.json index aca0e41e97..1f231eddbb 100644 --- a/composer.json +++ b/composer.json @@ -57,7 +57,7 @@ "utopia-php/agents": "2.*", "utopia-php/analytics": "0.15.*", "utopia-php/audit": "2.6.*", - "utopia-php/auth": "^0.7", + "utopia-php/auth": "^0.8", "utopia-php/cache": "^3.0.0", "utopia-php/cli": "^0.24", "utopia-php/compression": "0.1.*", diff --git a/composer.lock b/composer.lock index 99d770e9a8..8bad4622a2 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "17128527d9ef62968ea12eb43a81fdfb", + "content-hash": "091a71ba9518a11bacfa660d4df558ba", "packages": [ { "name": "adhocore/jwt", @@ -3319,16 +3319,16 @@ }, { "name": "utopia-php/auth", - "version": "0.7.0", + "version": "0.8.0", "source": { "type": "git", "url": "https://github.com/utopia-php/auth.git", - "reference": "22a2cf6ca604e5cc6bf10f0f8240195f0baa063a" + "reference": "1d77657e9c91e48e873e6e096f9d4f55f778b11f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/auth/zipball/22a2cf6ca604e5cc6bf10f0f8240195f0baa063a", - "reference": "22a2cf6ca604e5cc6bf10f0f8240195f0baa063a", + "url": "https://api.github.com/repos/utopia-php/auth/zipball/1d77657e9c91e48e873e6e096f9d4f55f778b11f", + "reference": "1d77657e9c91e48e873e6e096f9d4f55f778b11f", "shasum": "" }, "require": { @@ -3336,7 +3336,7 @@ "ext-openssl": "*", "ext-scrypt": "*", "ext-sodium": "*", - "php": ">=8.1" + "php": ">=8.3" }, "type": "library", "autoload": { @@ -3363,9 +3363,9 @@ ], "support": { "issues": "https://github.com/utopia-php/auth/issues", - "source": "https://github.com/utopia-php/auth/tree/0.7.0" + "source": "https://github.com/utopia-php/auth/tree/0.8.0" }, - "time": "2026-06-22T11:58:24+00:00" + "time": "2026-07-08T05:10:32+00:00" }, { "name": "utopia-php/cache", From 796af6f7b5036ebb1860727a9c70bae4e54ce6fd Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Wed, 8 Jul 2026 13:01:52 +0400 Subject: [PATCH 18/24] Remove folder param from listFiles in favor of queries --- .../Storage/Http/Buckets/Files/XList.php | 11 -------- tests/e2e/Services/Storage/StorageBase.php | 28 +++++++++---------- 2 files changed, 13 insertions(+), 26 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php index e4ca2273f0..de61ea5910 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php @@ -7,7 +7,6 @@ use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; -use Appwrite\Utopia\Database\Validator\Folder; use Appwrite\Utopia\Database\Validator\Queries\Files; use Appwrite\Utopia\Response; use Utopia\Database\Database; @@ -23,7 +22,6 @@ use Utopia\Database\Validator\UID; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Boolean; -use Utopia\Validator\Nullable; use Utopia\Validator\Text; class XList extends Action @@ -62,7 +60,6 @@ class XList extends Action ->param('queries', [], new Files(), '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. You may filter on the following attributes: ' . implode(', ', Files::ALLOWED_ATTRIBUTES), true) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) ->param('total', true, new Boolean(true), 'When set to false, the total count returned will be 0 and will not be calculated.', true) - ->param('folder', null, new Nullable(new Folder()), 'Filter results to files directly inside this virtual folder. Pass an empty string for the bucket root. Returns files from all folders when omitted.', true) ->inject('response') ->inject('dbForProject') ->inject('mode') @@ -76,7 +73,6 @@ class XList extends Action array $queries, string $search, bool $includeTotal, - ?string $folder, Response $response, Database $dbForProject, string $mode, @@ -108,13 +104,6 @@ class XList extends Action $queries[] = Query::search('search', $search); } - if (!\is_null($folder)) { - $folder = Folder::normalize($folder); - $queries[] = $folder === '' - ? Query::or([Query::equal('folder', ['']), Query::isNull('folder')]) - : Query::equal('folder', [$folder]); - } - $cursor = Query::getCursorQueries($queries, false); $cursor = \reset($cursor); diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 940ecffc34..1c3007a803 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -491,7 +491,7 @@ trait StorageBase $this->assertNotEmpty($webpView['body']); } - public function testCreateBucketFileWithParent(): void + public function testCreateBucketFileWithFolder(): void { $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ 'content-type' => 'application/json', @@ -2036,7 +2036,7 @@ trait StorageBase $this->assertGreaterThanOrEqual(0, $bucket['body']['totalSize']); } - public function testListFilesByParent(): void + public function testListFilesByFolder(): void { $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ 'content-type' => 'application/json', @@ -2083,25 +2083,23 @@ trait StorageBase // no filter -- all files $this->assertEquals(3, $list([])['total']); - // exact match -- immediate children only - $this->assertEquals(1, $list(['folder' => 'photos'])['total']); - $this->assertEquals('photos/', $list(['folder' => 'photos'])['files'][0]['folder']); + // exact match -- immediate children only, canonical form with trailing slash + $exact = $list(['queries' => [Query::equal('folder', ['photos/'])->toString()]]); + $this->assertEquals(1, $exact['total']); + $this->assertEquals('photos/', $exact['files'][0]['folder']); + + // equality is against the stored canonical form -- no normalization on query values + $this->assertEquals(0, $list(['queries' => [Query::equal('folder', ['photos'])->toString()]])['total']); // root only - $this->assertEquals(1, $list(['folder' => ''])['total']); - $this->assertEquals('', $list(['folder' => ''])['files'][0]['folder']); + $root = $list(['queries' => [Query::equal('folder', [''])->toString()]]); + $this->assertEquals(1, $root['total']); + $this->assertEquals('', $root['files'][0]['folder']); - // recursive via queries + // recursive via prefix $recursive = $list(['queries' => [Query::startsWith('folder', 'photos/')->toString()]]); $this->assertEquals(2, $recursive['total']); - // invalid parent - $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), ['folder' => '/photos']); - $this->assertEquals(400, $response['headers']['status-code']); - $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ 'content-type' => 'application/json', 'x-appwrite-project' => $this->getProject()['$id'], From 52c49a1dafe13f53b31398fb3d0a77394df6d318 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Wed, 8 Jul 2026 16:01:13 +0400 Subject: [PATCH 19/24] Remove storage folder API --- app/init/models.php | 3 - src/Appwrite/Migration/Version/V25.php | 39 --- .../Storage/Http/Buckets/Files/Create.php | 10 +- .../Storage/Http/Buckets/Folders/XList.php | 158 ---------- .../Modules/Storage/Services/Http.php | 4 - .../Database/Validator/Queries/Files.php | 1 - src/Appwrite/Utopia/Response.php | 2 - src/Appwrite/Utopia/Response/Model/File.php | 16 - src/Appwrite/Utopia/Response/Model/Folder.php | 53 ---- tests/e2e/Services/Storage/StorageBase.php | 285 ------------------ .../Storage/StorageCustomClientTest.php | 46 --- 11 files changed, 2 insertions(+), 615 deletions(-) delete mode 100644 src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php delete mode 100644 src/Appwrite/Utopia/Response/Model/Folder.php diff --git a/app/init/models.php b/app/init/models.php index 411f6acc89..cdb2a9b9b6 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -80,7 +80,6 @@ use Appwrite\Utopia\Response\Model\Error; use Appwrite\Utopia\Response\Model\ErrorDev; use Appwrite\Utopia\Response\Model\Execution; use Appwrite\Utopia\Response\Model\File; -use Appwrite\Utopia\Response\Model\Folder; use Appwrite\Utopia\Response\Model\Framework; use Appwrite\Utopia\Response\Model\FrameworkAdapter; use Appwrite\Utopia\Response\Model\Func; @@ -255,7 +254,6 @@ Response::setModel(new BaseList('Identities List', Response::MODEL_IDENTITY_LIST Response::setModel(new BaseList('Notifications List', Response::MODEL_NOTIFICATION_LIST, 'notifications', Response::MODEL_NOTIFICATION)); Response::setModel(new BaseList('Logs List', Response::MODEL_LOG_LIST, 'logs', Response::MODEL_LOG)); Response::setModel(new BaseList('Files List', Response::MODEL_FILE_LIST, 'files', Response::MODEL_FILE)); -Response::setModel(new BaseList('Folders List', Response::MODEL_FOLDER_LIST, 'folders', Response::MODEL_FOLDER, paging: false)); Response::setModel(new BaseList('Buckets List', Response::MODEL_BUCKET_LIST, 'buckets', Response::MODEL_BUCKET)); Response::setModel(new BaseList('Resource Tokens List', Response::MODEL_RESOURCE_TOKEN_LIST, 'tokens', Response::MODEL_RESOURCE_TOKEN)); Response::setModel(new BaseList('Teams List', Response::MODEL_TEAM_LIST, 'teams', Response::MODEL_TEAM)); @@ -391,7 +389,6 @@ Response::setModel(new JWT()); Response::setModel(new Locale()); Response::setModel(new LocaleCode()); Response::setModel(new File()); -Response::setModel(new Folder()); Response::setModel(new Bucket()); Response::setModel(new ResourceToken()); Response::setModel(new Team()); diff --git a/src/Appwrite/Migration/Version/V25.php b/src/Appwrite/Migration/Version/V25.php index c66bd0384c..800b9b451f 100644 --- a/src/Appwrite/Migration/Version/V25.php +++ b/src/Appwrite/Migration/Version/V25.php @@ -7,8 +7,6 @@ use Exception; use Throwable; use Utopia\Console; use Utopia\Database\Database; -use Utopia\Database\Document; -use Utopia\Database\Exception\Duplicate; class V25 extends Migration { @@ -19,9 +17,6 @@ class V25 extends Migration { Console::info('Migrating collections'); $this->migrateCollections(); - - Console::info('Migrating buckets'); - $this->migrateBuckets(); } /** @@ -71,38 +66,4 @@ class V25 extends Migration } } } - - /** - * Add the virtual folder `folder` attribute and index to every - * per-bucket files collection. - * - * @return void - * @throws Throwable - */ - private function migrateBuckets(): void - { - $this->dbForProject->foreach('buckets', function (Document $bucket) { - $bucketTable = "bucket_{$bucket->getSequence()}"; - Console::log("Migrating Bucket {$bucket->getId()} ({$bucket->getAttribute('name')})"); - - try { - $this->createAttributeFromCollection($this->dbForProject, $bucketTable, 'folder', 'files'); - } catch (Duplicate) { - Console::warning("'folder' from {$bucketTable}: Column already exists"); - } catch (Throwable $th) { - Console::warning("'folder' from {$bucketTable}: {$th->getMessage()}"); - } - - try { - $this->createIndexFromCollection($this->dbForProject, $bucketTable, '_key_folder', 'files'); - } catch (Duplicate) { - Console::warning("'_key_folder' from {$bucketTable}: Index already exists"); - } catch (Throwable $th) { - Console::warning("'_key_folder' from {$bucketTable}: {$th->getMessage()}"); - } - - $this->dbForProject->purgeCachedCollection($bucketTable); - $this->dbForProject->purgeCachedDocument(Database::METADATA, $bucketTable); - }); - } } diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php index c50718145b..cf934575c0 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php @@ -13,7 +13,6 @@ use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Database\Validator\CustomId; -use Appwrite\Utopia\Database\Validator\Folder; use Appwrite\Utopia\Response; use Utopia\Compression\Algorithms\GZIP; use Utopia\Compression\Algorithms\Zstd; @@ -86,7 +85,6 @@ class Create extends Action ->param('fileId', '', new CustomId(), 'File ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.') ->param('file', [], new File(), 'Binary file. Appwrite SDKs provide helpers to handle file input. [Learn about file input](https://appwrite.io/docs/products/storage/upload-download#input-file).', skipValidation: true) ->param('permissions', null, new Nullable(new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE, [Database::PERMISSION_READ, Database::PERMISSION_UPDATE, Database::PERMISSION_DELETE, Database::PERMISSION_WRITE])), 'An array of permission strings. By default, only the current user is granted all permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).', true) - ->param('folder', '', new Folder(), 'Virtual folder to place the file in, for example "photos/2026". Nest folders with `/`. Defaults to the bucket root.', true) ->inject('request') ->inject('response') ->inject('dbForProject') @@ -105,7 +103,6 @@ class Create extends Action string $fileId, mixed $file, ?array $permissions, - string $folder, Request $request, Response $response, Database $dbForProject, @@ -193,7 +190,6 @@ class Create extends Action $contentRange = $request->getHeaderLine('content-range'); $fileId = $fileId === 'unique()' ? ID::unique() : $fileId; - $folder = Folder::normalize($folder); $chunk = 1; $chunks = 1; @@ -265,7 +261,7 @@ class Create extends Action }; try { - $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $folder, $path, $permissions, $response, &$completed): void { + $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $path, $permissions, $response, &$completed): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); if (!$file->isEmpty()) { $chunks = $file->getAttribute('chunksTotal', 1); @@ -296,7 +292,6 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, - 'folder' => $folder, 'path' => $path, 'signature' => '', 'mimeType' => '', @@ -330,7 +325,7 @@ class Create extends Action return; } - $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $folder, $path, $permissions, $queueForEvents, $response): void { + $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $path, $permissions, $queueForEvents, $response): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); $uploaded = 0; @@ -433,7 +428,6 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, - 'folder' => $folder, 'path' => $path, 'signature' => $fileHash, 'mimeType' => $mimeType, diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php deleted file mode 100644 index d44d6eb99f..0000000000 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ /dev/null @@ -1,158 +0,0 @@ -setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) - ->setHttpPath('/v1/storage/buckets/:bucketId/folders') - ->desc('List folders') - ->groups(['api', 'storage']) - ->label('scope', 'files.read') - ->label('usage.resource', 'bucket/{request.bucketId}') - ->label('resourceType', RESOURCE_TYPE_BUCKETS) - ->label('sdk', new Method( - namespace: 'storage', - group: 'files', - name: 'listFolders', - description: '/docs/references/storage/list-folders.md', - auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], - responses: [ - new SDKResponse( - code: Response::STATUS_CODE_OK, - model: Response::MODEL_FOLDER_LIST, - ) - ] - )) - ->param('bucketId', '', new UID(), 'Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket).') - ->param('folder', '', new Folder(), 'Virtual folder to list the child folders of. Defaults to the bucket root.', true) - ->param('limit', 25, new Range(1, 100), 'Maximum number of folders to return. Must be between 1 and 100. A page shorter than this limit means the listing is complete.', true) - ->param('cursor', '', new Folder(), 'Folder path returned last by a previous page, used to continue the listing.', true) - ->inject('response') - ->inject('dbForProject') - ->inject('authorization') - ->inject('user') - ->callback($this->action(...)); - } - - public function action( - string $bucketId, - string $folder, - int $limit, - string $cursor, - Response $response, - Database $dbForProject, - Authorization $authorization, - User $user - ) { - $bucket = $authorization->skip(fn () => $dbForProject->getDocument('buckets', $bucketId)); - - $isAPIKey = $user->isKey($authorization->getRoles()); - $isPrivilegedUser = $user->isPrivileged($authorization->getRoles()); - - if ($bucket->isEmpty() || (!$bucket->getAttribute('enabled') && !$isAPIKey && !$isPrivilegedUser)) { - throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); - } - - $fileSecurity = $bucket->getAttribute('fileSecurity', false); - $valid = $authorization->isValid(new Input(Database::PERMISSION_READ, $bucket->getRead())); - if (!$fileSecurity && !$valid) { - throw new Exception(Exception::USER_UNAUTHORIZED, $authorization->getDescription()); - } - - $parent = Folder::normalize($folder); - $cursor = Folder::normalize($cursor); - - if ($cursor !== '') { - $remainder = \substr($cursor, \strlen($parent), -1); - if (!\str_starts_with($cursor, $parent) || $cursor === $parent || \str_contains($remainder, '/')) { - throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, "Folder '{$cursor}' for the 'cursor' value is not an immediate child of '{$parent}'."); - } - } - - $collection = 'bucket_' . $bucket->getSequence(); - $seek = $cursor === '' ? $parent : self::seekPast($cursor); - $folders = []; - - try { - while (\count($folders) < $limit) { - $queries = [ - Query::greaterThan('folder', $seek), - Query::orderAsc('folder'), - Query::limit(1), - ]; - if ($parent !== '') { - $queries[] = Query::startsWith('folder', $parent); - } - - if ($fileSecurity && !$valid) { - $results = $dbForProject->find($collection, $queries); - } else { - $results = $authorization->skip(fn () => $dbForProject->find($collection, $queries)); - } - - if (empty($results)) { - break; - } - - $fileParent = $results[0]->getAttribute('folder', ''); - $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; - $key = $parent . $segment . '/'; - - $folders[] = new Document([ - 'key' => $key, - 'name' => $segment, - 'parent' => $parent, - ]); - - $seek = self::seekPast($key); - } - } catch (NotFoundException) { - throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); - } - - $response->dynamic(new Document([ - 'folders' => $folders, - ]), Response::MODEL_FOLDER_LIST); - } - - /** - * Smallest string that sorts after every `folder` value inside the given - * folder: the trailing '/' replaced with the next code point ('0'), so a - * seek jumps past all of the folder's contents in one indexed query. - * Assumes the database orders `folder` values bytewise (binary collation), - * so nothing sorts between '/' (0x2F) and '0' (0x30). - */ - private static function seekPast(string $folder): string - { - return \substr($folder, 0, -1) . \chr(\ord('/') + 1); - } -} diff --git a/src/Appwrite/Platform/Modules/Storage/Services/Http.php b/src/Appwrite/Platform/Modules/Storage/Services/Http.php index dd7b8a900e..4010918205 100644 --- a/src/Appwrite/Platform/Modules/Storage/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Storage/Services/Http.php @@ -13,7 +13,6 @@ use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Push\Get as GetFileForP use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Update as UpdateFile; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\View\Get as GetFileView; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\XList as ListFiles; -use Appwrite\Platform\Modules\Storage\Http\Buckets\Folders\XList as ListFolders; use Appwrite\Platform\Modules\Storage\Http\Buckets\Get as GetBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\Update as UpdateBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\XList as ListBuckets; @@ -42,8 +41,5 @@ class Http extends Service $this->addAction(GetFileDownload::getName(), new GetFileDownload()); $this->addAction(GetFileView::getName(), new GetFileView()); $this->addAction(GetFileForPush::getName(), new GetFileForPush()); - - // Folders - $this->addAction(ListFolders::getName(), new ListFolders()); } } diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php index 4785e12d58..1941eabcdb 100644 --- a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php +++ b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php @@ -6,7 +6,6 @@ class Files extends Base { public const ALLOWED_ATTRIBUTES = [ 'name', - 'folder', 'signature', 'mimeType', 'sizeOriginal', diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 8494cb3705..e6b713d530 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -157,8 +157,6 @@ class Response extends SwooleResponse public const MODEL_FILE_LIST = 'fileList'; public const MODEL_BUCKET = 'bucket'; public const MODEL_BUCKET_LIST = 'bucketList'; - public const MODEL_FOLDER = 'folder'; - public const MODEL_FOLDER_LIST = 'folderList'; public const MODEL_RESOURCE_TOKEN = 'resourceToken'; public const MODEL_RESOURCE_TOKEN_LIST = 'resourceTokenList'; diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 75711d3ea9..61dd496f52 100644 --- a/src/Appwrite/Utopia/Response/Model/File.php +++ b/src/Appwrite/Utopia/Response/Model/File.php @@ -49,18 +49,6 @@ class File extends Model 'default' => '', 'example' => 'Pink.png', ]) - ->addRule('folder', [ - 'type' => self::TYPE_STRING, - 'description' => 'Virtual folder containing the file, with a trailing slash. Empty for the bucket root.', - 'default' => '', - 'example' => 'photos/2026/', - ]) - ->addRule('key', [ - 'type' => self::TYPE_STRING, - 'description' => 'Full virtual path of the file: the folder followed by the file name.', - 'default' => '', - 'example' => 'photos/2026/Pink.png', - ]) ->addRule('signature', [ 'type' => self::TYPE_STRING, 'description' => 'File MD5 signature.', @@ -139,10 +127,6 @@ class File extends Model $encryption = !empty($document->getAttribute('openSSLCipher', '')); $document->setAttribute('encryption', $encryption); - $folder = $document->getAttribute('folder') ?? ''; - $document->setAttribute('folder', $folder); - $document->setAttribute('key', $folder . $document->getAttribute('name', '')); - return $document; } } diff --git a/src/Appwrite/Utopia/Response/Model/Folder.php b/src/Appwrite/Utopia/Response/Model/Folder.php deleted file mode 100644 index 10bc40837b..0000000000 --- a/src/Appwrite/Utopia/Response/Model/Folder.php +++ /dev/null @@ -1,53 +0,0 @@ -addRule('key', [ - 'type' => self::TYPE_STRING, - 'description' => 'Full folder path, with a trailing slash.', - 'default' => '', - 'example' => 'photos/2026/', - ]) - ->addRule('name', [ - 'type' => self::TYPE_STRING, - 'description' => 'Folder name: the last segment of the path.', - 'default' => '', - 'example' => '2026', - ]) - ->addRule('parent', [ - 'type' => self::TYPE_STRING, - 'description' => 'Parent folder path with a trailing slash. Empty for top-level folders.', - 'default' => '', - 'example' => 'photos/', - ]) - ; - } - - /** - * Get Name - * - * @return string - */ - public function getName(): string - { - return 'Folder'; - } - - /** - * Get Type - * - * @return string - */ - public function getType(): string - { - return Response::MODEL_FOLDER; - } -} diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 1c3007a803..c2d90a2543 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -491,120 +491,6 @@ trait StorageBase $this->assertNotEmpty($webpView['body']); } - public function testCreateBucketFileWithFolder(): void - { - $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ], [ - 'bucketId' => ID::unique(), - 'name' => 'Test Bucket Folders', - 'fileSecurity' => true, - 'permissions' => [ - Permission::read(Role::any()), - Permission::create(Role::any()), - Permission::update(Role::any()), - Permission::delete(Role::any()), - ], - ]); - $this->assertEquals(201, $bucket['headers']['status-code']); - $bucketId = $bucket['body']['$id']; - - // without trailing slash -- normalized on storage - $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => 'photos/2026', - ]); - $this->assertEquals(201, $file['headers']['status-code']); - $this->assertEquals('photos/2026/', $file['body']['folder']); - $this->assertEquals('photos/2026/logo.png', $file['body']['key']); - $this->assertEquals('logo.png', $file['body']['name']); - - // default -- bucket root - $rootFile = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - ]); - $this->assertEquals(201, $rootFile['headers']['status-code']); - $this->assertEquals('', $rootFile['body']['folder']); - $this->assertEquals('logo.png', $rootFile['body']['key']); - - // duplicate keys allowed -- same parent + name, different fileId - $duplicate = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => 'photos/2026', - ]); - $this->assertEquals(201, $duplicate['headers']['status-code']); - $this->assertEquals('photos/2026/logo.png', $duplicate['body']['key']); - $this->assertNotEquals($file['body']['$id'], $duplicate['body']['$id']); - - // invalid values - foreach (['/photos', 'photos//2026', 'photos/../2026', "photos/\x01"] as $invalid) { - $res = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => $invalid, - ]); - $this->assertEquals(400, $res['headers']['status-code']); - } - - // chunked upload -- parent is stored when the document is created - // with the first chunk (pattern from testCreateBucketFile) - $source = __DIR__ . '/../../../resources/disk-a/large-file.mp4'; - $size = \filesize($source); - $chunkSize = 5 * 1024 * 1024; - $handle = @\fopen($source, 'rb'); - $mimeType = \mime_content_type($source); - $counter = 0; - $id = ''; - $chunked = null; - $headers = [ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ]; - while (!\feof($handle)) { - $curlFile = new CURLFile('data://' . $mimeType . ';base64,' . \base64_encode(@\fread($handle, $chunkSize)), $mimeType, 'large-file.mp4'); - $headers['content-range'] = 'bytes ' . ($counter * $chunkSize) . '-' . \min(((($counter * $chunkSize) + $chunkSize) - 1), $size - 1) . '/' . $size; - if (!empty($id)) { - $headers['x-appwrite-id'] = $id; - } - $chunked = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', \array_merge($headers, $this->getHeaders()), [ - 'fileId' => 'unique()', - 'file' => $curlFile, - 'folder' => 'videos/2026', - ]); - $this->assertNotEmpty($chunked['body']['$id']); - $id = $chunked['body']['$id']; - $counter++; - } - \fclose($handle); - $this->assertEquals(201, $chunked['headers']['status-code']); - $this->assertEquals('videos/2026/', $chunked['body']['folder']); - $this->assertEquals('videos/2026/large-file.mp4', $chunked['body']['key']); - - $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ]); - $this->assertEquals(204, $response['headers']['status-code']); - } - public function testCreateBucketFileZstdCompression(): void { $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ @@ -2036,175 +1922,4 @@ trait StorageBase $this->assertGreaterThanOrEqual(0, $bucket['body']['totalSize']); } - public function testListFilesByFolder(): void - { - $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ], [ - 'bucketId' => ID::unique(), - 'name' => 'Test Bucket Parent Filter', - 'fileSecurity' => true, - 'permissions' => [ - Permission::read(Role::any()), - Permission::create(Role::any()), - ], - ]); - $this->assertEquals(201, $bucket['headers']['status-code']); - $bucketId = $bucket['body']['$id']; - - $upload = function (string $folder) use ($bucketId): void { - $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => $folder, - 'permissions' => [Permission::read(Role::any())], - ]); - $this->assertEquals(201, $file['headers']['status-code']); - }; - - $upload(''); - $upload('photos'); - $upload('photos/2026'); - - $list = function (array $params) use ($bucketId): array { - $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), $params); - $this->assertEquals(200, $response['headers']['status-code']); - return $response['body']; - }; - - // no filter -- all files - $this->assertEquals(3, $list([])['total']); - - // exact match -- immediate children only, canonical form with trailing slash - $exact = $list(['queries' => [Query::equal('folder', ['photos/'])->toString()]]); - $this->assertEquals(1, $exact['total']); - $this->assertEquals('photos/', $exact['files'][0]['folder']); - - // equality is against the stored canonical form -- no normalization on query values - $this->assertEquals(0, $list(['queries' => [Query::equal('folder', ['photos'])->toString()]])['total']); - - // root only - $root = $list(['queries' => [Query::equal('folder', [''])->toString()]]); - $this->assertEquals(1, $root['total']); - $this->assertEquals('', $root['files'][0]['folder']); - - // recursive via prefix - $recursive = $list(['queries' => [Query::startsWith('folder', 'photos/')->toString()]]); - $this->assertEquals(2, $recursive['total']); - - $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ]); - $this->assertEquals(204, $response['headers']['status-code']); - } - - public function testListFolders(): void - { - $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ], [ - 'bucketId' => ID::unique(), - 'name' => 'Test Bucket Folder Listing', - 'fileSecurity' => true, - 'permissions' => [ - Permission::read(Role::any()), - Permission::create(Role::any()), - Permission::delete(Role::any()), - ], - ]); - $this->assertEquals(201, $bucket['headers']['status-code']); - $bucketId = $bucket['body']['$id']; - - $upload = function (string $folder) use ($bucketId): string { - $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => $folder, - 'permissions' => [Permission::read(Role::any()), Permission::delete(Role::any())], - ]); - $this->assertEquals(201, $file['headers']['status-code']); - return $file['body']['$id']; - }; - - $upload(''); - $upload('invoices'); - $upload('photos/2025'); - $julyFileId = $upload('photos/2026/july'); - - $listFolders = function (array $params) use ($bucketId): array { - $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), $params); - $this->assertEquals(200, $response['headers']['status-code']); - return $response['body']['folders']; - }; - - // top level, alphabetical - $folders = $listFolders([]); - $this->assertCount(2, $folders); - $this->assertEquals(['invoices/', 'photos/'], \array_column($folders, 'key')); - $this->assertEquals(['invoices', 'photos'], \array_column($folders, 'name')); - $this->assertEquals(['', ''], \array_column($folders, 'parent')); - - // nested level -- deep files imply intermediate folders - $folders = $listFolders(['folder' => 'photos']); - $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); - - $folders = $listFolders(['folder' => 'photos/2026']); - $this->assertEquals(['photos/2026/july/'], \array_column($folders, 'key')); - - // pagination - $page = $listFolders(['limit' => 1]); - $this->assertEquals(['invoices/'], \array_column($page, 'key')); - $page = $listFolders(['limit' => 1, 'cursor' => 'invoices/']); - $this->assertEquals(['photos/'], \array_column($page, 'key')); - $page = $listFolders(['limit' => 1, 'cursor' => 'photos/']); - $this->assertCount(0, $page); - - // nonexistent prefix -- empty list, not 404 - $this->assertCount(0, $listFolders(['folder' => 'missing'])); - - // crafted cursors -- must be an immediate child of parent - foreach ([ - ['folder' => 'photos', 'cursor' => 'photos/2026/july'], // grandchild - ['folder' => 'photos', 'cursor' => 'invoices'], // outside parent - ] as $params) { - $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), $params); - $this->assertEquals(400, $response['headers']['status-code']); - } - - // implicit lifecycle -- deleting the last file removes the folder chain - $delete = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId . '/files/' . $julyFileId, array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders())); - $this->assertEquals(204, $delete['headers']['status-code']); - $this->assertEquals(['photos/2025/'], \array_column($listFolders(['folder' => 'photos']), 'key')); - - $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ]); - $this->assertEquals(204, $response['headers']['status-code']); - } } diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index 778bf6c2f0..32c92626d5 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1607,50 +1607,4 @@ final class StorageCustomClientTest extends Scope $this->assertEquals(204, $response['headers']['status-code']); } - public function testListFoldersFileSecurityVisibility(): void - { - $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ], [ - 'bucketId' => ID::unique(), - 'name' => 'Folder Visibility', - 'fileSecurity' => true, - 'permissions' => [], - ]); - $this->assertEquals(201, $bucket['headers']['status-code']); - $bucketId = $bucket['body']['$id']; - - $upload = function (string $folder, array $permissions) use ($bucketId): void { - $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', [ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ], [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => $folder, - 'permissions' => $permissions, - ]); - $this->assertEquals(201, $file['headers']['status-code']); - }; - - $upload('secret', []); - $upload('shared', [Permission::read(Role::any())]); - - $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders())); - $this->assertEquals(200, $response['headers']['status-code']); - $this->assertSame(['shared/'], \array_column($response['body']['folders'], 'key')); - - $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ]); - $this->assertEquals(204, $response['headers']['status-code']); - } } From c860dfd58de9c4085e76a2f90bde2fd6d07714dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 8 Jul 2026 14:41:32 +0200 Subject: [PATCH 20/24] Improve PR quality --- src/Appwrite/Auth/OAuth2/Oidc.php | 18 ++++++++++++++++-- .../Http/Project/OAuth2/Oidc/Update.php | 2 +- tests/e2e/Services/Project/OAuth2Base.php | 2 +- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Auth/OAuth2/Oidc.php b/src/Appwrite/Auth/OAuth2/Oidc.php index f8d5e6c4e9..296e5f4c79 100644 --- a/src/Appwrite/Auth/OAuth2/Oidc.php +++ b/src/Appwrite/Auth/OAuth2/Oidc.php @@ -38,6 +38,15 @@ class Oidc extends OAuth2 protected array $wellKnownConfiguration = []; + /** + * Memoized decode of the JSON stored in appSecret. Building a single login + * URL reads the secret several times (prompt, max_age, each endpoint), so + * decode once and reuse. + * + * @var array|null + */ + protected ?array $decodedAppSecret = null; + /** * @return string */ @@ -303,7 +312,7 @@ class Oidc extends OAuth2 protected function getUserinfoEndpoint(): string { $secret = $this->getAppSecret(); - $endpoint = $secret['userinfoEndpoint'] ?? ''; + $endpoint = $secret['userInfoEndpoint'] ?? ''; if (!empty($endpoint)) { return $endpoint; } @@ -335,11 +344,16 @@ class Oidc extends OAuth2 */ protected function getAppSecret(): array { + if ($this->decodedAppSecret !== null) { + return $this->decodedAppSecret; + } + try { $secret = \json_decode($this->appSecret, true, 512, JSON_THROW_ON_ERROR); } catch (\Throwable $th) { throw new \Exception('Invalid secret'); } - return $secret; + + return $this->decodedAppSecret = \is_array($secret) ? $secret : []; } } diff --git a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php index c42943072d..dbf18ad6f0 100644 --- a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php +++ b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Oidc/Update.php @@ -146,7 +146,7 @@ class Update extends Base ->param('tokenURL', null, new Nullable(new URL(allowEmpty: true)), 'OpenID Connect token endpoint URL. Required when wellKnownURL is not provided. For example: https://myoauth.com/oauth2/token', optional: true, aliases: ['tokenUrl']) ->param('userInfoURL', null, new Nullable(new URL(allowEmpty: true)), 'OpenID Connect user info endpoint URL. Required when wellKnownURL is not provided. For example: https://myoauth.com/oauth2/userinfo', optional: true, aliases: ['userInfoUrl']) ->param('prompt', null, new Nullable(new ArrayList(new WhiteList(['none', 'login', 'consent', 'select_account'], true), 4)), 'Array of OpenID Connect prompt values controlling the authentication and consent screens. If "none" is included, it must be the only element. "none" means: don\'t display any authentication or consent screens. "login" means: prompt the user to re-authenticate. "consent" means: prompt the user for consent. "select_account" means: prompt the user to select an account.', optional: true, enum: new Enum(name: 'ProjectOAuth2OidcPrompt')) - ->param('maxAge', null, new Nullable(new Range(0, PHP_INT_MAX, Range::TYPE_INTEGER)), 'Maximum authentication age in seconds. When set, the user must have authenticated within this many seconds, otherwise they are prompted to re-authenticate. Set to null or omit to leave unspecified.', optional: true) + ->param('maxAge', null, new Nullable(new Range(0, PHP_INT_MAX, Range::TYPE_INTEGER)), 'Maximum authentication age in seconds. When set, the user must have authenticated within this many seconds, otherwise they are prompted to re-authenticate.', optional: true) ->param('enabled', null, new Nullable(new Boolean()), 'OAuth2 sign-in method status. Set to true to enable new session creation. Setting to true will trigger end-to-end credentials validation, and will throw if the credentials are invalid.', true) ->inject('response') ->inject('dbForPlatform') diff --git a/tests/e2e/Services/Project/OAuth2Base.php b/tests/e2e/Services/Project/OAuth2Base.php index f49ed29a8b..4f6076e581 100644 --- a/tests/e2e/Services/Project/OAuth2Base.php +++ b/tests/e2e/Services/Project/OAuth2Base.php @@ -19,7 +19,7 @@ trait OAuth2Base 'amazon' => ['clientId' => '', 'clientSecret' => '', 'enabled' => false], 'github' => ['clientId' => '', 'clientSecret' => '', 'enabled' => false], 'apple' => ['serviceId' => '', 'keyId' => '', 'teamId' => '', 'p8File' => '', 'enabled' => false], - 'oidc' => ['clientId' => '', 'clientSecret' => '', 'wellKnownURL' => '', 'authorizationURL' => '', 'tokenURL' => '', 'userInfoURL' => '', 'enabled' => false], + 'oidc' => ['clientId' => '', 'clientSecret' => '', 'wellKnownURL' => '', 'authorizationURL' => '', 'tokenURL' => '', 'userInfoURL' => '', 'prompt' => [], 'enabled' => false], 'okta' => ['clientId' => '', 'clientSecret' => '', 'domain' => '', 'authorizationServerId' => '', 'enabled' => false], 'google' => ['clientId' => '', 'clientSecret' => '', 'prompt' => ['consent'], 'enabled' => false], 'dropbox' => ['appKey' => '', 'appSecret' => '', 'enabled' => false], From b16119633ba0abaa8d5559501163d4229cae8544 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 8 Jul 2026 14:49:32 +0200 Subject: [PATCH 21/24] Fix tests --- .../Modules/Project/OAuth2/OAuth2ProviderTest.php | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php index b8eb48f748..4c66222256 100644 --- a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php +++ b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php @@ -91,7 +91,7 @@ final class OAuth2ProviderTest extends TestCase yield 'google' => [GoogleUpdate::class, ['clientId', 'clientSecret', 'prompt']]; yield 'keycloak' => [KeycloakUpdate::class, ['clientId', 'clientSecret', 'endpoint', 'realmName']]; yield 'microsoft' => [MicrosoftUpdate::class, ['applicationId', 'applicationSecret', 'tenant']]; - yield 'oidc' => [OidcUpdate::class, ['clientId', 'clientSecret', 'wellKnownURL', 'authorizationURL', 'tokenURL', 'userInfoURL']]; + yield 'oidc' => [OidcUpdate::class, ['clientId', 'clientSecret', 'wellKnownURL', 'authorizationURL', 'tokenURL', 'userInfoURL', 'prompt', 'maxAge']]; yield 'okta' => [OktaUpdate::class, ['clientId', 'clientSecret', 'domain', 'authorizationServerId']]; } @@ -347,6 +347,8 @@ final class OAuth2ProviderTest extends TestCase null, null, null, + null, + null, true, ]); @@ -365,6 +367,8 @@ final class OAuth2ProviderTest extends TestCase 'https://idp.example/oauth2/authorize', 'https://idp.example/oauth2/token', 'https://idp.example/oauth2/userinfo', + null, + null, true, ]); @@ -389,6 +393,8 @@ final class OAuth2ProviderTest extends TestCase 'https://idp.example/oauth2/authorize', null, 'https://idp.example/oauth2/userinfo', + null, + null, true, ], assertQueueParam: false, @@ -417,6 +423,8 @@ final class OAuth2ProviderTest extends TestCase 'https://idp.example/oauth2/authorize', 'https://idp.example/oauth2/token', 'https://idp.example/oauth2/userinfo', + null, + null, true, ], ); From 002cdf966c00b0d92efd94b9989e8819594e64c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 8 Jul 2026 14:50:23 +0200 Subject: [PATCH 22/24] Fix backwards compatibility --- src/Appwrite/Auth/OAuth2/Oidc.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Auth/OAuth2/Oidc.php b/src/Appwrite/Auth/OAuth2/Oidc.php index 296e5f4c79..d5b54dfc59 100644 --- a/src/Appwrite/Auth/OAuth2/Oidc.php +++ b/src/Appwrite/Auth/OAuth2/Oidc.php @@ -312,7 +312,9 @@ class Oidc extends OAuth2 protected function getUserinfoEndpoint(): string { $secret = $this->getAppSecret(); - $endpoint = $secret['userInfoEndpoint'] ?? ''; + // Read the legacy lowercase `userinfoEndpoint` key as a fallback so that + // OIDC configs stored via the old generic oauth2 PATCH endpoint keep working. + $endpoint = $secret['userInfoEndpoint'] ?? $secret['userinfoEndpoint'] ?? ''; if (!empty($endpoint)) { return $endpoint; } From ceeed2b627aece6763761bb1fac729b52cce8f14 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Wed, 8 Jul 2026 18:11:10 +0100 Subject: [PATCH 23/24] Update notification authentication to require ADMIN role and restrict service platforms to console only --- app/config/services.php | 2 +- .../Modules/Notifications/Http/Notifications/Update.php | 2 +- .../Platform/Modules/Notifications/Http/Notifications/XList.php | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/app/config/services.php b/app/config/services.php index 16a0bd6901..c05a917a58 100644 --- a/app/config/services.php +++ b/app/config/services.php @@ -335,7 +335,7 @@ return [ 'tests' => true, 'optional' => false, 'icon' => '', - 'platforms' => ['client', 'server', 'console'], + 'platforms' => ['console'], ], 'advisor' => [ 'key' => 'advisor', diff --git a/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/Update.php b/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/Update.php index 9ca7b6b683..01f6bb3c85 100644 --- a/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/Update.php +++ b/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/Update.php @@ -37,7 +37,7 @@ class Update extends Action group: null, name: 'update', description: '/docs/references/notifications/update-notification.md', - auth: [AuthType::SESSION, AuthType::JWT], + auth: [AuthType::ADMIN], responses: [ new SDKResponse( code: Response::STATUS_CODE_OK, diff --git a/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/XList.php b/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/XList.php index 558190d99a..1a8c78a546 100644 --- a/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/XList.php +++ b/src/Appwrite/Platform/Modules/Notifications/Http/Notifications/XList.php @@ -39,7 +39,7 @@ class XList extends Action group: null, name: 'list', description: '/docs/references/notifications/list-notifications.md', - auth: [AuthType::SESSION, AuthType::JWT], + auth: [AuthType::ADMIN], responses: [ new SDKResponse( code: Response::STATUS_CODE_OK, From bc97fa76ad17b64cd9c60443cb5c69c6e545b8cf Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Thu, 9 Jul 2026 10:56:02 +0530 Subject: [PATCH 24/24] (fix): remove mode auth scheme from client and server SDK specs --- src/Appwrite/Platform/Tasks/Specs.php | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/Specs.php b/src/Appwrite/Platform/Tasks/Specs.php index 46b217e5a9..8b3b9fc073 100644 --- a/src/Appwrite/Platform/Tasks/Specs.php +++ b/src/Appwrite/Platform/Tasks/Specs.php @@ -171,12 +171,6 @@ class Specs extends Action 'description' => 'The user session to authenticate with', 'in' => 'header', ], - 'Mode' => [ - 'type' => 'apiKey', - 'name' => 'X-Appwrite-Mode', - 'description' => '', - 'in' => 'header', - ], 'DevKey' => [ 'type' => 'apiKey', 'name' => 'X-Appwrite-Dev-Key', @@ -264,12 +258,6 @@ class Specs extends Action 'description' => 'The user session to authenticate with', 'in' => 'header', ], - 'Mode' => [ - 'type' => 'apiKey', - 'name' => 'X-Appwrite-Mode', - 'description' => '', - 'in' => 'header', - ], 'ForwardedUserAgent' => [ 'type' => 'apiKey', 'name' => 'X-Forwarded-User-Agent',