From 5d7594194dd83b61a95bc58bfa740bcaffad9ffe Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:16:47 +0400 Subject: [PATCH] Add parent param to file create and expose parent/key on file model --- .../Storage/Http/Buckets/Files/Create.php | 10 +- src/Appwrite/Utopia/Response/Model/File.php | 16 +++ tests/e2e/Services/Storage/StorageBase.php | 107 ++++++++++++++++++ 3 files changed, 131 insertions(+), 2 deletions(-) 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 cf934575c0..be11e4191b 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\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, diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 61dd496f52..029f4defa0 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('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; } } diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 3f823c38e9..f90a967148 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -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', [