Merge pull request #12802 from appwrite/feat-storage-virtual-folders

Add virtual folders to Storage
This commit is contained in:
Torsten Dittmann authored and GitHub committed 2026-07-08 12:27:24 +04:00
commit ad7c6b9919
14 files changed
+720 -2

No files matched your search

+3
View File
@@ -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());
+1
View File
@@ -0,0 +1 @@
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\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('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,
@@ -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('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')
@@ -73,6 +76,7 @@ class XList extends Action
array $queries,
string $search,
bool $includeTotal,
?string $folder,
Response $response,
Database $dbForProject,
string $mode,
@@ -104,6 +108,13 @@ 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);
@@ -0,0 +1,158 @@
<?php
namespace Appwrite\Platform\Modules\Storage\Http\Buckets\Folders;
use Appwrite\Extend\Exception;
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\Response;
use Utopia\Database\Database;
use Utopia\Database\Document;
use Utopia\Database\Exception\NotFound as NotFoundException;
use Utopia\Database\Query;
use Utopia\Database\Validator\Authorization;
use Utopia\Database\Validator\Authorization\Input;
use Utopia\Database\Validator\UID;
use Utopia\Platform\Action;
use Utopia\Platform\Scope\HTTP;
use Utopia\Validator\Range;
class XList extends Action
{
use HTTP;
public static function getName()
{
return 'listFolders';
}
public function __construct()
{
$this
->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);
}
}
@@ -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());
}
}
@@ -0,0 +1,72 @@
<?php
namespace Appwrite\Utopia\Database\Validator;
use Utopia\Validator;
class Folder extends Validator
{
public const MAX_LENGTH = 2048;
public function getDescription(): string
{
return 'Folder must be `/`-separated segments without empty, `.`, or `..` segments, must not start with `/`, must not contain control characters, and must be at most ' . self::MAX_LENGTH . ' characters long including the trailing slash.';
}
public function isValid($value): bool
{
if (!\is_string($value)) {
return false;
}
if ($value === '') {
return true;
}
if (\strlen(self::normalize($value)) > 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;
}
}
@@ -6,6 +6,7 @@ class Files extends Base
{
public const ALLOWED_ATTRIBUTES = [
'name',
'folder',
'signature',
'mimeType',
'sizeOriginal',
+2
View File
@@ -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';
@@ -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,10 @@ 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;
}
}
@@ -0,0 +1,53 @@
<?php
namespace Appwrite\Utopia\Response\Model;
use Appwrite\Utopia\Response;
use Appwrite\Utopia\Response\Model;
class Folder extends Model
{
public function __construct()
{
$this
->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;
}
}
+288
View File
@@ -491,6 +491,120 @@ 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'),
'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', [
@@ -1921,4 +2035,178 @@ 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 $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
$this->assertEquals(1, $list(['folder' => 'photos'])['total']);
$this->assertEquals('photos/', $list(['folder' => 'photos'])['files'][0]['folder']);
// root only
$this->assertEquals(1, $list(['folder' => ''])['total']);
$this->assertEquals('', $list(['folder' => ''])['files'][0]['folder']);
// recursive via queries
$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'],
'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']);
}
}
@@ -1606,4 +1606,51 @@ 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']);
}
}
@@ -0,0 +1,56 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Utopia\Database\Validator;
use Appwrite\Utopia\Database\Validator\Folder;
use PHPUnit\Framework\TestCase;
final class FolderTest extends TestCase
{
protected ?Folder $object = null;
public function setUp(): void
{
$this->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('.'));
$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->assertSame('', Folder::normalize(''));
$this->assertSame('photos/', Folder::normalize('photos'));
$this->assertSame('photos/', Folder::normalize('photos/'));
$this->assertSame('photos/2026/', Folder::normalize('photos/2026'));
}
}