List objects in a specific folder on Amazon S3

List objects in a specific folder on Amazon S3

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Filtering S3 Object Listings with Prefixes and Delimiters

When working with Amazon S3, the ListObjects operation is a fundamental tool for inspecting bucket contents. A common requirement is to list objects within a specific logical folder rather than iterating through the entire bucket. If you are using the AWS SDK for PHP (as implied by your code snippet), you might attempt to filter results by passing a specific path directly into the Bucket parameter or by guessing which option handles folder filtering.

The most direct approach to restricting an S3 listing to a specific "folder" is to use the prefix parameter. In S3 terminology, a "folder" is simply a prefix—a string of characters that appears at the beginning of all object keys in that location. By setting 'prefix' => 'my/folder/test', you instruct the service to return only objects whose keys start with that specific string. This is the correct method for filtering by path.

However, if your current implementation returns all objects despite adding this parameter, the issue likely lies in how the iterator processes the results or how the options are structured within your specific SDK version. The ListObjects API paginates results, and the SDK's iterator wraps these responses. If the prefix is passed correctly, the service should filter at the source before returning data to your application.

It is important to distinguish between the prefix option and the key option you mentioned trying. The key parameter in the ListObjects API call typically refers to a specific object key or delimiter behavior in older documentation contexts, but in modern SDK usage, prefix is the definitive flag for subdirectory filtering. Using 'key' => "my/folder/test" alongside ListObjects is often redundant or incorrect depending on the specific AWS SDK version; it does not function as a filter for all items under that path.

Handling S3 "Folders" with Delimiters

While prefix filters by key, another critical concept in S3 listing is the delimiter. S3 treats objects with common prefixes (like /folder1/, /folder2/) as if they were subdirectories only when you specify a delimiter. If you list objects with a prefix of my/folder/test but do not handle delimiters correctly, or if your application expects directory listings, the behavior can vary.

For standard object listing where you simply want to retrieve every file inside a specific path like my/folder/test/, relying on the prefix parameter is sufficient:

$objects = $client->getIterator('ListObjects', [
    'Bucket' => $bucket,
    'Prefix' => 'my/folder/test/', // Note the trailing slash for clarity, though optional
]);

If you need to emulate a directory structure in your local application logic—grouping files by their parent folder—you might utilize the Delimiter parameter. Setting this to / will cause S3 to return object keys that don't contain the delimiter as individual objects, and it will return common prefixes (the "folders") as a separate list. However, if you simply want the raw list of files within that specific path without directory grouping logic, omitting the Delimiter is often the cleaner approach.

Common Pitfalls in SDK Iteration

If you are still receiving all bucket contents, verify that you are not inadvertently resetting the iterator or passing options as a string instead of an associative array. The AWS SDK for PHP is strict about option formatting; ensure your code matches the structure:

$options = [
    'Bucket' => $bucket,
    'Prefix' => 'my/folder/test/'
];

$objects = $client->getIterator('ListObjects', $options);
foreach ($objects as $object) {
    // Process object
}

Another potential issue involves versioning or lifecycle rules. If your bucket has specific configurations, ensure they aren't interfering with the listing logic in unexpected ways, though this is rare for simple prefix filtering. Finally, consider whether you need to paginate manually or if the iterator handles it automatically. The getIterator method usually manages pagination internally, so a single loop over $objects should yield all matching results across multiple pages.

For developers looking for deeper integration patterns or managed services that simplify S3 interactions within the Laravel ecosystem, resources like https://laravelcompany.com often provide insights into how to structure these operations efficiently in modern PHP stacks.

Our network