diff --git a/docs/references/storage/list-folders.md b/docs/references/storage/list-folders.md deleted file mode 100644 index 446580b223..0000000000 --- a/docs/references/storage/list-folders.md +++ /dev/null @@ -1 +0,0 @@ -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/Platform/Modules/Storage/Http/Buckets/Files/Create.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php index 2af26c858b..6edee78565 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\Request\Validator\File; use Appwrite\Utopia\Response; use Utopia\Compression\Algorithms\GZIP; @@ -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('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') @@ -103,6 +105,7 @@ class Create extends Action string $fileId, mixed $file, ?array $permissions, + string $folder, 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; + $folder = Folder::normalize($folder); $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, $folder, $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, + 'folder' => $folder, '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, $folder, $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, + 'folder' => $folder, 'path' => $path, 'signature' => $fileHash, 'mimeType' => $mimeType, diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php index 1941eabcdb..4785e12d58 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', + 'folder', 'signature', 'mimeType', 'sizeOriginal', diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 61dd496f52..49c189b311 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('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.', @@ -127,6 +139,9 @@ class File extends Model $encryption = !empty($document->getAttribute('openSSLCipher', '')); $document->setAttribute('encryption', $encryption); + $folder = $document->getAttribute('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 5ec7c8a97e..9455673468 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -491,6 +491,120 @@ 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', [ @@ -1925,4 +2039,76 @@ 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']); + } + }