Added option to set a limit for MediaCollections (#1533)

* Added option to set a limit for MediaCollections with BC for singleFile() method

* Stylefix

* Changed type declaration for

* Changed type declaration for

* Small change to the docs to improve a sentence

* Updated docs: now has a seperate example for onlyKeepLatest

* Assert that the first file no longer is in the collection after adding the Nth+1 file

* Stylefix

docs/working-with-media-collections/defining-media-collections.md

@@ -127,6 +127,35 @@ $yourModel->getMedia('avatar')->count(); // returns 1
 $yourModel->getFirstMediaUrl('avatar'); // will return an url to the `$anotherPathToImage` file
 ```
 
+## Limited file collections
+
+Whenever you want to limit the amount of files inside a collection you can use the `onlyKeepLatests(n)` method. Whenever you add a file to a collection and exceed the given limit, Medialibrary will delete the oldest file(s) and keep the collection size at `n`.
+
+```php
+// in your model
+
+public function registerMediaCollections()
+{
+    $this
+        ->addMediaCollection('limited-collection')
+        ->onlyKeepLatests(3);
+}
+```
+
+For the first 3 files, nothing strange happens. The files get added to the collection and the collection now holds all 3 files. Whenever you decide to add a 4th file, Medialibrary deletes the first file and keeps the latest 3.
+
+```php
+$yourModel->addMedia($firstFile)->toMediaCollection('limited-collection');
+$yourModel->getMedia('avatar')->count(); // returns 1
+$yourModel->addMedia($secondFile)->toMediaCollection('limited-collection');
+$yourModel->getMedia('avatar')->count(); // returns 2
+$yourModel->addMedia($thirdFile)->toMediaCollection('limited-collection');
+$yourModel->getMedia('avatar')->count(); // returns 3
+$yourModel->addMedia($fourthFile)->toMediaCollection('limited-collection');
+$yourModel->getMedia('avatar')->count(); // returns 3
+$yourModel->getFirstMediaUrl('avatar'); // will return an url to the `$secondFile` file
+```
+
 ## Registering media conversions
 
 It's recommended that your first read the section on [converting images](/laravel-medialibrary/v7/converting-images/defining-conversions) before reading the following paragraphs.

src/FileAdder/FileAdder.php

@@ -325,8 +325,12 @@ protected function processMediaItem(HasMedia $model, Media $media, self $fileAdd
             dispatch($job);
         }
 
-        if (optional($this->getMediaCollection($media->collection_name))->singleFile) {
-            $model->clearMediaCollectionExcept($media->collection_name, $media);
+        if ($collectionSizeLimit = optional($this->getMediaCollection($media->collection_name))->collectionSizeLimit) {
+            $collectionMedia = $this->subject->fresh()->getMedia($media->collection_name);
+
+            if ($collectionMedia->count() > $collectionSizeLimit) {
+                $model->clearMediaCollectionExcept($media->collection_name, $collectionMedia->reverse()->take($collectionSizeLimit));
+            }
         }
     }
 

src/MediaCollection/MediaCollection.php

@@ -20,8 +20,8 @@ class MediaCollection
     /** @var callable */
     public $acceptsFile;
 
-    /** @var bool */
-    public $singleFile = false;
+    /** @var int */
+    public $collectionSizeLimit = false;
 
     /** @var string */
     public $fallbackUrl = '';
@@ -62,7 +62,12 @@ public function acceptsFile(callable $acceptsFile): self
 
     public function singleFile(): self
     {
-        $this->singleFile = true;
+        return $this->onlyKeepLatest(1);
+    }
+
+    public function onlyKeepLatest(int $int): self
+    {
+        $this->collectionSizeLimit = $int;
 
         return $this;
     }

tests/Feature/FileAdder/MediaConversions/MediaCollectionTest.php

@@ -170,9 +170,35 @@ public function registerMediaCollections()
 
         $model = $testModel::create(['name' => 'testmodel']);
 
+        $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
         $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
         $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
 
         $this->assertCount(1, $model->getMedia('images'));
     }
+
+    /** @test */
+    public function if_the_only_keeps_latest_method_is_specified_it_will_delete_all_other_media_and_will_only_keep_the_latest_n_ones()
+    {
+        $testModel = new class extends TestModelWithConversion {
+            public function registerMediaCollections()
+            {
+                $this
+                    ->addMediaCollection('images')
+                    ->onlyKeepLatest(3);
+            }
+        };
+
+        $model = $testModel::create(['name' => 'testmodel']);
+
+        $firstFile = $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
+        $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
+        $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
+        $model->addMedia($this->getTestJpg())->preservingOriginal()->toMediaCollection('images');
+
+        $this->assertFalse($model->getMedia('images')->contains(function ($model) use ($firstFile) {
+            return $model->is($firstFile);
+        }));
+        $this->assertCount(3, $model->getMedia('images'));
+    }
 }