Add parent param to file create and expose parent/key on file model

This commit is contained in:
Torsten Dittmann committed 2026-07-06 20:16:47 +04:00
1 parent eb72169b89
commit 5d7594194d
3 files changed
+131 -2

No files matched your search

@@ -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,
@@ -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;
}
}
+107
View File
@@ -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', [