[4.x] feat: Added three new functions to SpatieMediaLibraryFileAttachmentProvider to customize media and their attributes (#17426)

* feat: Added functions to customize SpatieMediaProvider

Added three new functions to SpatieMediaLibraryFileAttachmentProvider to customize media and their attributes Theses functions are:

- preserveFilenames()
- mediaName()
- customProperties()

They allow to change the name of the media in storage, change the name of the media in the database, and add custom properties to the media in the database.

* feat: Edit plugin doc

* Update README.md

* Update SpatieMediaLibraryFileAttachmentProvider.php

* Update SpatieMediaLibraryFileAttachmentProvider.php

---------

Signed-off-by: Dan Harrin <git@danharrin.com>
Co-authored-by: Dan Harrin <git@danharrin.com>

packages/spatie-laravel-media-library-plugin/README.md

@@ -220,6 +220,35 @@ class Post extends Model implements HasRichContent
 }
 ```
 
+You may want to preserve the original filenames of the uploaded files, using the `preserveFilenames()` method:
+
+```php
+use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;
+
+SpatieMediaLibraryFileAttachmentProvider::make()
+    ->preserveFilenames()
+```
+
+You can customize the [media name](https://spatie.be/docs/laravel-medialibrary/api/adding-files#content-usingname) using the `mediaName()` method:
+
+```php
+use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;
+use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
+use Illuminate\Support\Str;
+
+SpatieMediaLibraryFileAttachmentProvider::make()
+    ->mediaName(fn (TemporaryUploadedFile $file): string => Str::random() . '_' . $file->getClientOriginalName())
+```
+
+You may pass in [custom properties](https://spatie.be/docs/laravel-medialibrary/advanced-usage/using-custom-properties) when uploading files using the `customProperties()` method:
+
+```php
+use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;
+
+SpatieMediaLibraryFileAttachmentProvider::make()
+    ->customProperties(['archived' => false])
+```
+
 ## Table column
 
 To use the media library image column:

packages/spatie-laravel-media-library-plugin/src/Forms/Components/RichEditor/FileAttachmentProviders/SpatieMediaLibraryFileAttachmentProvider.php

@@ -2,8 +2,10 @@
 
 namespace Filament\Forms\Components\RichEditor\FileAttachmentProviders;
 
+use Closure;
 use Filament\Forms\Components\RichEditor\FileAttachmentProviders\Contracts\FileAttachmentProvider;
 use Filament\Forms\Components\RichEditor\RichContentAttribute;
+use Filament\Support\Concerns\EvaluatesClosures;
 use Illuminate\Support\Str;
 use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
 use LogicException;
@@ -13,12 +15,23 @@ use Throwable;
 
 class SpatieMediaLibraryFileAttachmentProvider implements FileAttachmentProvider
 {
+    use EvaluatesClosures;
+
     protected MediaCollection $media;
 
     protected RichContentAttribute $attribute;
 
     protected ?string $collection = null;
 
+    protected bool | Closure $shouldPreserveFilenames = false;
+
+    protected string | Closure | null $mediaName = null;
+
+    /**
+     * @var array<string, mixed> | Closure | null
+     */
+    protected array | Closure | null $customProperties = null;
+
     public static function make(): static
     {
         return app(static::class);
@@ -31,6 +44,30 @@ class SpatieMediaLibraryFileAttachmentProvider implements FileAttachmentProvider
         return $this;
     }
 
+    public function preserveFilenames(bool | Closure $condition = true): static
+    {
+        $this->shouldPreserveFilenames = $condition;
+
+        return $this;
+    }
+
+    public function mediaName(string | Closure | null $name): static
+    {
+        $this->mediaName = $name;
+
+        return $this;
+    }
+
+    /**
+     * @param  array<string, mixed> | Closure | null  $properties
+     */
+    public function customProperties(array | Closure | null $properties): static
+    {
+        $this->customProperties = $properties;
+
+        return $this;
+    }
+
     public function attribute(RichContentAttribute $attribute): static
     {
         $this->attribute = $attribute;
@@ -96,7 +133,9 @@ class SpatieMediaLibraryFileAttachmentProvider implements FileAttachmentProvider
     {
         $media = $this->getExistingModel() /** @phpstan-ignore method.notFound */
             ->addMediaFromString($file->get())
-            ->usingFileName(((string) Str::ulid()) . '.' . $file->getClientOriginalExtension())
+            ->usingFileName($this->shouldPreserveFilenames() ? $file->getClientOriginalName() : (Str::ulid() . '.' . $file->getClientOriginalExtension()))
+            ->usingName($this->getMediaName($file) ?? pathinfo($file->getClientOriginalName(), PATHINFO_FILENAME))
+            ->withCustomProperties($this->getCustomProperties())
             ->toMediaCollection($this->getCollection(), diskName: $this->attribute->getFileAttachmentsDiskName() ?? '');
 
         $this->getMedia()->put($media->uuid, $media);
@@ -132,4 +171,24 @@ class SpatieMediaLibraryFileAttachmentProvider implements FileAttachmentProvider
     {
         return $this->collection ?? $this->attribute->getName();
     }
+
+    public function shouldPreserveFilenames(): bool
+    {
+        return (bool) $this->evaluate($this->shouldPreserveFilenames);
+    }
+
+    public function getMediaName(TemporaryUploadedFile $file): ?string
+    {
+        return $this->evaluate($this->mediaName, [
+            'file' => $file,
+        ]);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function getCustomProperties(): array
+    {
+        return $this->evaluate($this->customProperties) ?? [];
+    }
 }