Merge pull request #12929 from appwrite/restore-storage-folder-api

Restore storage folder API
This commit is contained in:
Torsten Dittmann authored and GitHub committed 2026-07-27 19:01:05 +04:00
commit 94cdb97f9e
5 files changed
+210 -3

No files matched your search

-1
View File
@@ -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.
@@ -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,
@@ -6,6 +6,7 @@ class Files extends Base
{
public const ALLOWED_ATTRIBUTES = [
'name',
'folder',
'signature',
'mimeType',
'sizeOriginal',
@@ -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;
}
}
+186
View File
@@ -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']);
}
}