support svg placeholder

Author: QuentinGab

README.md

@@ -44,6 +44,10 @@ I developed this package with the highest degree of flexibility possible and I h
     - [Manually generate conversions](#manually-generate-conversions)
     - [Format Media Url](#format-media-url)
 
+1. [Conversions Presets](#conversions-presets)
+
+    - [Image Placeholder](#image-placeholder)
+
 1. [Customization](#customization)
 
     - [Custom Media Model](#custom-media-model)
@@ -733,6 +737,73 @@ This package comes with 3 formatters out of the box:
 
 Feel free to implement your own formatter by extending `\Elegantly\Media\UrlFormatters\AbstractUrlFormatter`.
 
+## Conversions Presets
+
+### Image Placeholder
+
+When loading images on the web, it’s common to show a low-resolution blurred placeholder first, then swap it with the full-resolution image once it’s ready. This improves perceived performance, reduces layout shifts, and gives a polished feel to your UI.
+
+This package includes a ready-to-use preset for generating these placeholders in Base64-encoded format. The placeholder is tiny in size, quick to load, and designed to be displayed while the actual image is being fetched.
+
+#### Defining the Placeholder Conversion
+
+To create a placeholder, simply define a media conversion using the `MediaImagePlaceholderConverter`:
+
+```php
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Elegantly\Media\Concerns\HasMedia;
+use Elegantly\Media\Contracts\InteractWithMedia;
+use Elegantly\Media\MediaCollection;
+use Elegantly\Media\MediaConversionDefinition;
+use Elegantly\Media\Converters\MediaImagePlaceholderConverter;
+
+class User extends Model implements InteractWithMedia
+{
+    use HasMedia;
+
+    public function registerMediaCollections(): array;
+    {
+        return [
+            new MediaCollection(
+                name: 'avatar',
+                single: true,
+                conversions: [
+                    new MediaConversionDefinition(
+                        name: 'placeholder',
+                        converter: fn ($media) => new MediaImagePlaceholderConverter($media),
+                    ),
+                ]
+            )
+        ];
+    }
+}
+```
+
+#### Using the Placeholder in Your Views
+
+If you’re using the built-in <x-media::img> Blade component, you can directly specify the placeholder conversion name:
+
+```html
+<x-media::img
+    :media="$user->getFirstMedia('avatar')"
+    placeholder="placeholder"
+/>
+```
+
+This will automatically load the blurred placeholder as a background-image.
+
+#### Retrieving the Base64 Value Directly
+
+If you need to manually work with the placeholder (e.g., for API responses or inline styles), you can retrieve it like this:
+
+```php
+$placeholder = $media->getConversion('placeholder');
+
+$base64Image = $placeholder?->contents;
+```
+
 ## Customization
 
 ### Custom Media Model

resources/views/components/img.blade.php

@@ -8,9 +8,16 @@
     'src' => null,
     'width' => null,
     'height' => null,
+    'placeholder' => null,
 ])
 
+@php
+    $placeholder = $placeholder === true ? 'placeholder' : $placeholder;
+    $placeholderValue = $placeholder ? $media->getConversion($placeholder)?->contents : null;
+@endphp
+
 <img {!! $attributes !!} loading="{{ $loading }}" src="{!! $src ?? $media->getUrl($conversion, $fallback, $parameters) !!}"
     height="{{ $height ?? $media->getHeight($conversion, $fallback) }}"
     width="{{ $width ?? $media->getWidth($conversion, $fallback) }}"
-    alt="{{ $alt ?? $media->getName($conversion, $fallback) }}">
+    alt="{{ $alt ?? $media->getName($conversion, $fallback) }}"
+    @if ($placeholderValue) style="background-size:cover;background-image: url(data:image/jpeg;base64,{{ $placeholderValue }})" @endif>

src/Converters/Image/MediaSvgPlaceholderConverter.php renamed to src/Converters/Image/MediaImagePlaceholderConverter.php

@@ -15,11 +15,11 @@
 use Spatie\Image\Image;
 use Spatie\TemporaryDirectory\TemporaryDirectory as SpatieTemporaryDirectory;
 
-class MediaSvgPlaceholderConverter extends MediaConverter
+class MediaImagePlaceholderConverter extends MediaConverter
 {
     public function __construct(
         public readonly Media $media,
-        public int $blur = 50,
+        public int $blur = 20,
         public int $width = 20,
         public ?int $height = 20,
     ) {}

tests/Models/TestConverters.php

@@ -7,7 +7,7 @@
 use Elegantly\Media\Converters\Audio\MediaMp3Converter;
 use Elegantly\Media\Converters\Audio\MediaWavConverter;
 use Elegantly\Media\Converters\Image\MediaImageConverter;
-use Elegantly\Media\Converters\Image\MediaSvgPlaceholderConverter;
+use Elegantly\Media\Converters\Image\MediaImagePlaceholderConverter;
 use Elegantly\Media\Converters\Pdf\MediaPdfToImageConverter;
 use Elegantly\Media\Converters\Video\MediaFrameConverter;
 use Elegantly\Media\Converters\Video\MediaMp4Converter;
@@ -80,7 +80,7 @@ public function registerMediaCollections(): Arrayable|iterable|null
                         name: 'svg',
                         immediate: false,
                         queued: false,
-                        converter: fn ($media) => new MediaSvgPlaceholderConverter(
+                        converter: fn ($media) => new MediaImagePlaceholderConverter(
                             media: $media,
                         )
                     ),