Spatie Media Library Deletes Entire Collection on S3 Instead of Single File

If your media collection is defined with the singleFile() method, adding a new file to this collection will trigger the deletion of the existing file. if the deletion process is not correctly handled, especially in an S3 environment, it might lead to unintended consequences, such as the removal of the entire directory or collection.

Recommended Actions:

Review Collection Configuration: Ensure that the media collection is configured appropriately. If you intend to allow multiple files, avoid using the singleFile() method. Conversely, if only one file should be present, ensure that the deletion logic is correctly implemented.

Check Deletion Logic: When deleting a media item, confirm that only the intended file is targeted for deletion. This involves verifying that the correct media instance is selected and that the deletion command is executed properly. S3 Configuration:

Amazon S3 treats each file as an individual object and doesn't inherently recognize directories in the traditional sense. Ensure that your application's logic accounts for this, preventing the deletion of pseudo-directories or multiple files unintentionally.

Update Dependencies: Ensure that you're using the latest versions of Laravel, Spatie's Media Library, and the AWS SDK. Updates often include fixes for known issues and improvements in handling file operations. Consult Documentation and Community:

Refer to Spatie's official documentation for best practices in managing media collections and deletions. Engaging with the community through forums or GitHub discussions can also provide insights and solutions from others who have faced similar challenges.

Thank you for your detailed response! I really appreciate your insights. Let me clarify a few things to give you more context about my setup:

My Media Collection Setup

• I have a one-to-many relationship between the skus table and the sku_gallery media collection.
• Each SKU can have multiple images stored under sku_gallery collection.
• The collection is not using singleFile(). I can confirm that multiple images are correctly uploaded and retrieved without any issues.

Deletion Behavior Issue

• The problem occurs when I try to delete a single media item within the collection using $media->delete();.
• Instead of deleting just that one file, Spatie deletes the entire collection folder from S3, including the conversions folder.
• The database records remain correct, meaning the media table correctly reflects the expected number of remaining images.

S3 Storage Structure

I've attached screenshots in the thread that show the directory layers on S3. Spatie correctly structures the media files inside their respective folders. However, after invoking $media->delete();, the whole folder (including its conversion images) disappears from S3, even though only one image was meant to be deleted.

What I’ve Verified

✅ Media collection is not using singleFile()
✅ Able to retrieve multiple images without any issues
✅ Deletion command is targeting the correct media instance (verified by id, uuid, and other queries)
✅ No custom event listeners interfering with the delete operation
✅ Storage disk is correctly configured for S3 in filesystems.php
✅ Database records remain correct after deletion, but files on S3 disappear

Next Steps

Do you think this might be related to how Spatie Media Library interacts with S3’s object structure? I suspect that it might be incorrectly interpreting the deletion operation at the folder level instead of the file level. Have you encountered anything similar?

Thanks again for your time and suggestions! Let me know if you need more details. 🙏

Solution Found ✅

I found the solution in one of my team members' source codes, which aligns with the implementation in the DefaultFileRemover class of the Spatie Media Library package in a specific version. It correctly ensures that only the specific media file and its related conversions/responsive images are deleted, without affecting other media files within the same collection.

If anyone faces a similar issue, I recommend checking the latest updates in the package or using a custom implementation based on the DefaultFileRemover class.

Updated Implementation

<?php

namespace App\MediaLibrary;

use Exception;
use Illuminate\Contracts\Filesystem\Factory;
use Illuminate\Support\Str;
use Spatie\MediaLibrary\MediaCollections\Filesystem;
use Spatie\MediaLibrary\MediaCollections\Models\Media;
use Spatie\MediaLibrary\Support\FileRemover\FileRemover;

class CustomFileRemover implements FileRemover
{
    public function __construct(protected Filesystem $mediaFileSystem, protected Factory $filesystem) {}

    public function removeAllFiles(Media $media): void
    {

        if ($media->conversions_disk && $media->disk !== $media->conversions_disk) {
            $this->removeFromConversionsDirectory($media, $media->conversions_disk);
            $this->removeFromMediaDirectory($media, $media->conversions_disk);
        }

        $this->removeFromConversionsDirectory($media, $media->disk);
        $this->removeFromMediaDirectory($media, $media->disk);
    }

    public function removeFromMediaDirectory(Media $media, string $disk): void
    {
        $mediaDirectory = $this->mediaFileSystem->getMediaDirectory($media);

        collect([$mediaDirectory])
            ->each(function (string $directory) use ($media, $disk) {
                try {
                    $allFilePaths = $this->filesystem->disk($disk)->allFiles($directory);
                    $imagePaths = array_filter(
                        $allFilePaths,
                        static fn(string $path) => Str::afterLast($path, '/') === $media->file_name
                    );
                    foreach ($imagePaths as $imagePath) {
                        $this->filesystem->disk($disk)->delete($imagePath);
                    }

                    if (! $this->filesystem->disk($disk)->allFiles($directory)) {
                        $this->filesystem->disk($disk)->deleteDirectory($directory);
                    }
                } catch (Exception $exception) {
                    report($exception);
                }
            });
    }

    public function removeFromConversionsDirectory(Media $media, string $disk): void
    {
        $conversionsDirectory = $this->mediaFileSystem->getMediaDirectory($media, 'conversions');

        collect([$conversionsDirectory])
            ->each(function (string $directory) use ($media, $disk) {
                try {
                    $allFilePaths = $this->filesystem->disk($disk)->allFiles($directory);
                    $conversions = $media->getMediaConversionNames() ?: [];
                    $conversionsFilePaths = array_map(
                        static fn(string $conversion) => $media->getPathRelativeToRoot($conversion),
                        $conversions,
                    );
                    $imagePaths = array_intersect($allFilePaths, $conversionsFilePaths);
                    foreach ($imagePaths as $imagePath) {
                        $this->filesystem->disk($disk)->delete($imagePath);
                    }

                    if (! $this->filesystem->disk($disk)->allFiles($directory)) {
                        $this->filesystem->disk($disk)->deleteDirectory($directory);
                    }
                } catch (Exception $exception) {
                    report($exception);
                }
            });
    }

    public function removeResponsiveImages(Media $media, string $conversionName): void
    {
        $responsiveImagesDirectory = $this->mediaFileSystem->getResponsiveImagesDirectory($media);

        $allFilePaths = $this->filesystem->disk($media->disk)->allFiles($responsiveImagesDirectory);

        $responsiveImagePaths = array_filter(
            $allFilePaths,
            fn(string $path) => Str::contains($path, $conversionName)
        );

        $this->filesystem->disk($media->disk)->delete($responsiveImagePaths);
    }

    public function removeFile(string $path, string $disk): void
    {
        $this->filesystem->disk($disk)->delete($path);
    }
}

Resolution

Marking this as resolved. 🚀

Hope this helps anyone facing a similar issue!