Add parent filter to list files and whitelist parent queries

This commit is contained in:
Torsten Dittmann committed 2026-07-06 20:21:48 +04:00
1 parent 5d7594194d
commit 4037de3eb5
3 files changed
+79

No files matched your search

@@ -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('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)
->inject('response')
->inject('dbForProject')
->inject('mode')
@@ -73,6 +76,7 @@ class XList extends Action
array $queries,
string $search,
bool $includeTotal,
?string $parent,
Response $response,
Database $dbForProject,
string $mode,
@@ -104,6 +108,13 @@ 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]);
}
$cursor = Query::getCursorQueries($queries, false);
$cursor = \reset($cursor);
@@ -6,6 +6,7 @@ class Files extends Base
{
public const ALLOWED_ATTRIBUTES = [
'name',
'parent',
'signature',
'mimeType',
'sizeOriginal',
@@ -1997,4 +1997,71 @@ 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 $parent) 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,
'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(['parent' => 'photos'])['total']);
$this->assertEquals('photos/', $list(['parent' => 'photos'])['files'][0]['parent']);
// root only
$this->assertEquals(1, $list(['parent' => ''])['total']);
$this->assertEquals('', $list(['parent' => ''])['files'][0]['parent']);
// recursive via queries
$recursive = $list(['queries' => [Query::startsWith('parent', '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->assertEquals(400, $response['headers']['status-code']);
}
}