Rename public folder attribute and params from parent to folder

This commit is contained in:
Torsten Dittmann committed 2026-07-07 12:20:44 +04:00
1 parent ef9581e4c7
commit 99ee9714c9
10 files changed
+65 -65

No files matched your search

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