@mohammadhprp/system-prompt 0.10.1

package/framework/skills/laravel-best-practices/references/spatie-medialibrary.md

@@ -0,0 +1,672 @@
+# Media Library Development
+
+## Overview
+
+Use spatie/laravel-medialibrary to associate files with Eloquent models. Supports image/video conversions, responsive images, multiple collections, and various storage disks.
+
+## When to Activate
+
+- Activate when working with file uploads, media attachments, or image processing in Laravel.
+- Activate when code references `HasMedia`, `InteractsWithMedia`, the `Media` model, or media collections/conversions.
+- Activate when the user wants to add, retrieve, convert, or manage files attached to Eloquent models.
+
+## Scope
+
+- In scope: media uploads, collections, conversions, responsive images, custom properties, file retrieval, path/URL generation.
+- Out of scope: general file storage without Eloquent association, non-Laravel frameworks.
+
+## Workflow
+
+1. Identify the task (model setup, adding media, defining conversions, retrieving files, etc.).
+2. Read `Laravel Media Library Reference` and focus on the relevant section.
+3. Apply the patterns from the reference, keeping code minimal and Laravel-native.
+
+## Core Concepts
+
+### Model Setup
+
+Every model that should have media must implement `HasMedia` and use the `InteractsWithMedia` trait:
+
+```php
+use Spatie\MediaLibrary\HasMedia;
+use Spatie\MediaLibrary\InteractsWithMedia;
+
+class BlogPost extends Model implements HasMedia
+{
+    use InteractsWithMedia;
+}
+```
+
+### Adding Media
+
+```php
+$blogPost->addMedia($file)->toMediaCollection('images');
+$blogPost->addMediaFromUrl($url)->toMediaCollection('images');
+$blogPost->addMediaFromRequest('file')->toMediaCollection('images');
+```
+
+### Defining Collections
+
+```php
+public function registerMediaCollections(): void
+{
+    $this->addMediaCollection('avatar')->singleFile();
+    $this->addMediaCollection('downloads')->useDisk('s3');
+}
+```
+
+### Defining Conversions
+
+```php
+use Spatie\MediaLibrary\MediaCollections\Models\Media;
+use Spatie\Image\Enums\Fit;
+
+public function registerMediaConversions(?Media $media = null): void
+{
+    $this->addMediaConversion('thumb')
+        ->fit(Fit::Contain, 300, 300)
+        ->nonQueued();
+}
+```
+
+### Retrieving Media
+
+```php
+$url = $model->getFirstMediaUrl('images');
+$thumbUrl = $model->getFirstMediaUrl('images', 'thumb');
+$allMedia = $model->getMedia('images');
+```
+
+## Do and Don't
+
+Do:
+- Always implement the `HasMedia` interface alongside the `InteractsWithMedia` trait.
+- Use `?Media $media = null` as the parameter for `registerMediaConversions()`.
+- Call `->toMediaCollection()` to finalize adding media.
+- Use `->nonQueued()` for conversions that should run synchronously.
+- Use `->singleFile()` on collections that should only hold one file.
+- Use `Spatie\Image\Enums\Fit` enum values for fit methods.
+
+Don't:
+- Don't forget to run `php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"` before migrating.
+- Don't use `env()` for disk configuration; use `config()` or set it in `config/media-library.php`.
+- Don't call `addMedia()` without calling `toMediaCollection()` — the media won't be saved.
+- Don't reference conversion names that aren't registered in `registerMediaConversions()`.
+
+# Laravel Media Library Reference
+
+Complete reference for `spatie/laravel-medialibrary`. Full documentation: https://spatie.be/docs/laravel-medialibrary
+
+## Model Setup
+
+Implement `HasMedia` and use `InteractsWithMedia`:
+
+```php
+use Illuminate\Database\Eloquent\Model;
+use Spatie\MediaLibrary\HasMedia;
+use Spatie\MediaLibrary\InteractsWithMedia;
+
+class BlogPost extends Model implements HasMedia
+{
+    use InteractsWithMedia;
+
+    public function registerMediaCollections(): void
+    {
+        $this->addMediaCollection('images');
+    }
+
+    public function registerMediaConversions(?Media $media = null): void
+    {
+        $this->addMediaConversion('thumb')
+            ->fit(Fit::Contain, 300, 300);
+    }
+}
+```
+
+## Adding Media
+
+### From uploaded file
+
+```php
+$model->addMedia($request->file('image'))->toMediaCollection('images');
+```
+
+### From request (shorthand)
+
+```php
+$model->addMediaFromRequest('image')->toMediaCollection('images');
+```
+
+### From URL
+
+```php
+$model->addMediaFromUrl('https://example.com/image.jpg')->toMediaCollection('images');
+```
+
+### From string content
+
+```php
+$model->addMediaFromString('raw content')->usingFileName('file.txt')->toMediaCollection('files');
+```
+
+### From base64
+
+```php
+$model->addMediaFromBase64($base64Data)->usingFileName('photo.jpg')->toMediaCollection('images');
+```
+
+### From stream
+
+```php
+$model->addMediaFromStream($stream)->usingFileName('file.pdf')->toMediaCollection('files');
+```
+
+### From existing disk
+
+```php
+$model->addMediaFromDisk('path/to/file.jpg', 's3')->toMediaCollection('images');
+```
+
+### Multiple files from request
+
+```php
+$model->addMultipleMediaFromRequest(['images'])->each(function ($fileAdder) {
+    $fileAdder->toMediaCollection('images');
+});
+
+$model->addAllMediaFromRequest()->each(function ($fileAdder) {
+    $fileAdder->toMediaCollection('images');
+});
+```
+
+### Copy instead of move
+
+```php
+$model->copyMedia($pathToFile)->toMediaCollection('images');
+// or
+$model->addMedia($pathToFile)->preservingOriginal()->toMediaCollection('images');
+```
+
+## FileAdder Options
+
+All methods are chainable before calling `toMediaCollection()`:
+
+```php
+$model->addMedia($file)
+    ->usingName('Custom Name')              // display name
+    ->usingFileName('custom-name.jpg')      // filename on disk
+    ->setOrder(3)                           // order within collection
+    ->withCustomProperties(['alt' => 'A landscape photo'])
+    ->withManipulations(['thumb' => ['filter' => 'greyscale']])
+    ->withResponsiveImages()                // generate responsive variants
+    ->storingConversionsOnDisk('s3')         // put conversions on different disk
+    ->addCustomHeaders(['CacheControl' => 'max-age=31536000'])
+    ->toMediaCollection('images');
+```
+
+### Store on cloud disk
+
+```php
+$model->addMedia($file)->toMediaCollectionOnCloudDisk('images');
+```
+
+## Media Collections
+
+Define in `registerMediaCollections()`:
+
+```php
+public function registerMediaCollections(): void
+{
+    // Basic collection
+    $this->addMediaCollection('images');
+
+    // Single file (replacing previous on new upload)
+    $this->addMediaCollection('avatar')
+        ->singleFile();
+
+    // Keep only latest N items
+    $this->addMediaCollection('recent_photos')
+        ->onlyKeepLatest(5);
+
+    // Specific disk
+    $this->addMediaCollection('downloads')
+        ->useDisk('s3');
+
+    // With conversions disk
+    $this->addMediaCollection('photos')
+        ->useDisk('s3')
+        ->storeConversionsOnDisk('s3-thumbnails');
+
+    // MIME type restriction
+    $this->addMediaCollection('documents')
+        ->acceptsMimeTypes(['application/pdf', 'application/zip']);
+
+    // Custom validation
+    $this->addMediaCollection('images')
+        ->acceptsFile(function ($file) {
+            return $file->mimeType === 'image/jpeg';
+        });
+
+    // Fallback URL/path when collection is empty
+    $this->addMediaCollection('avatar')
+        ->singleFile()
+        ->useFallbackUrl('/images/default-avatar.jpg')
+        ->useFallbackPath(public_path('/images/default-avatar.jpg'));
+
+    // Enable responsive images for entire collection
+    $this->addMediaCollection('hero_images')
+        ->withResponsiveImages();
+
+    // Collection-specific conversions
+    $this->addMediaCollection('photos')
+        ->registerMediaConversions(function () {
+            $this->addMediaConversion('card')
+                ->fit(Fit::Crop, 400, 400);
+        });
+}
+```
+
+## Media Conversions
+
+Define in `registerMediaConversions()`:
+
+```php
+use Spatie\MediaLibrary\MediaCollections\Models\Media;
+use Spatie\Image\Enums\Fit;
+
+public function registerMediaConversions(?Media $media = null): void
+{
+    $this->addMediaConversion('thumb')
+        ->fit(Fit::Contain, 300, 300)
+        ->nonQueued();
+
+    $this->addMediaConversion('preview')
+        ->fit(Fit::Crop, 500, 500)
+        ->withResponsiveImages()
+        ->queued();
+
+    $this->addMediaConversion('banner')
+        ->fit(Fit::Max, 1200, 630)
+        ->performOnCollections('images', 'headers')
+        ->nonQueued()
+        ->sharpen(10);
+
+    // Conditional conversion based on media properties
+    if ($media?->mime_type === 'image/png') {
+        $this->addMediaConversion('png-thumb')
+            ->fit(Fit::Contain, 150, 150);
+    }
+
+    // Keep original format instead of converting to jpg
+    $this->addMediaConversion('web')
+        ->fit(Fit::Max, 800, 800)
+        ->keepOriginalImageFormat();
+
+    // PDF page rendering
+    $this->addMediaConversion('pdf-preview')
+        ->pdfPageNumber(1)
+        ->fit(Fit::Contain, 400, 400);
+
+    // Video frame extraction
+    $this->addMediaConversion('video-thumb')
+        ->extractVideoFrameAtSecond(5)
+        ->fit(Fit::Crop, 300, 300);
+}
+```
+
+### Image Manipulation Methods (via spatie/image)
+
+Resizing and fitting:
+- `width(int)`, `height(int)` — constrain dimensions
+- `fit(Fit, int, int)` — fit within bounds using `Fit::Contain`, `Fit::Max`, `Fit::Fill`, `Fit::Stretch`, `Fit::Crop`
+- `crop(int, int)` — crop to exact dimensions
+
+Effects:
+- `sharpen(int)`, `blur(int)`, `pixelate(int)`
+- `greyscale()`, `sepia()`
+- `brightness(int)`, `contrast(int)`, `colorize(int, int, int)`
+
+Orientation:
+- `orientation(int)`, `flip(string)`, `rotate(int)`
+
+Format:
+- `format(string)` — `'jpg'`, `'png'`, `'webp'`, `'avif'`
+- `quality(int)` — 1-100
+
+Other:
+- `border(int, string, string)`, `watermark(string)`
+- `optimize()`, `nonOptimized()`
+
+### Conversion Configuration
+
+- `performOnCollections('col1', 'col2')` — limit to specific collections
+- `queued()` / `nonQueued()` — run async or sync
+- `withResponsiveImages()` — also generate responsive variants for this conversion
+- `keepOriginalImageFormat()` — preserve png/webp/gif instead of converting to jpg
+- `pdfPageNumber(int)` — which PDF page to render
+- `extractVideoFrameAtSecond(int)` — video thumbnail timing
+
+## Retrieving Media
+
+### Getting media items
+
+```php
+$media = $model->getMedia('images');                    // all in collection
+$first = $model->getFirstMedia('images');               // first item
+$last  = $model->getLastMedia('images');                // last item
+$has   = $model->hasMedia('images');                    // boolean check
+```
+
+### Getting URLs
+
+```php
+$url     = $model->getFirstMediaUrl('images');           // original URL
+$thumbUrl = $model->getFirstMediaUrl('images', 'thumb'); // conversion URL
+$lastUrl  = $model->getLastMediaUrl('images', 'thumb');
+```
+
+### Getting paths
+
+```php
+$path     = $model->getFirstMediaPath('images');
+$thumbPath = $model->getFirstMediaPath('images', 'thumb');
+```
+
+### Temporary URLs (S3)
+
+```php
+$tempUrl = $model->getFirstTemporaryUrl(
+    now()->addMinutes(30),
+    'images',
+    'thumb'
+);
+```
+
+### Fallback URLs
+
+```php
+$url = $model->getFallbackMediaUrl('avatar');
+```
+
+### From the Media model
+
+```php
+$media = $model->getFirstMedia('images');
+
+$media->getUrl();                    // original URL
+$media->getUrl('thumb');             // conversion URL
+$media->getPath();                   // disk path
+$media->getFullUrl();                // full URL with domain
+$media->getTemporaryUrl(now()->addMinutes(30));
+$media->hasGeneratedConversion('thumb');  // check if conversion exists
+```
+
+### Filtering media
+
+```php
+$media = $model->getMedia('images', function (Media $media) {
+    return $media->getCustomProperty('featured') === true;
+});
+
+$media = $model->getMedia('images', ['mime_type' => 'image/jpeg']);
+```
+
+## Custom Properties
+
+Store arbitrary metadata on media items:
+
+```php
+// When adding
+$model->addMedia($file)
+    ->withCustomProperties([
+        'alt' => 'Descriptive text',
+        'credits' => 'Photographer Name',
+    ])
+    ->toMediaCollection('images');
+
+// Get/set on existing media
+$media->setCustomProperty('alt', 'Updated text');
+$media->save();
+
+$alt = $media->getCustomProperty('alt');
+$has = $media->hasCustomProperty('alt');
+$media->forgetCustomProperty('alt');
+$media->save();
+```
+
+## Responsive Images
+
+Generate multiple sizes for optimal loading:
+
+```php
+// On the FileAdder
+$model->addMedia($file)
+    ->withResponsiveImages()
+    ->toMediaCollection('images');
+
+// On a conversion
+$this->addMediaConversion('hero')
+    ->fit(Fit::Max, 1200, 800)
+    ->withResponsiveImages();
+
+// On a collection
+$this->addMediaCollection('photos')
+    ->withResponsiveImages();
+```
+
+### Using in Blade
+
+```blade
+{{-- Renders img tag with srcset --}}
+{{ $media->toHtml() }}
+
+{{-- With attributes --}}
+{{ $media->img()->attributes(['class' => 'w-full', 'alt' => 'Photo']) }}
+
+{{-- Get srcset string --}}
+<img src="{{ $media->getUrl() }}" srcset="{{ $media->getSrcset() }}" />
+
+{{-- Responsive conversion --}}
+<img src="{{ $media->getUrl('hero') }}" srcset="{{ $media->getSrcset('hero') }}" />
+```
+
+### Placeholder SVG
+
+```php
+$svg = $media->responsiveImages()->getPlaceholderSvg(); // tiny blurred base64 placeholder
+```
+
+## Managing Media
+
+### Clear a collection
+
+```php
+$model->clearMediaCollection('images');
+```
+
+### Clear except specific items
+
+```php
+$model->clearMediaCollectionExcept('images', $mediaToKeep);
+```
+
+### Delete specific media
+
+```php
+$model->deleteMedia($mediaId);
+```
+
+### Delete all media
+
+```php
+$model->deleteAllMedia();
+```
+
+### Delete model but keep media files
+
+```php
+$model->deletePreservingMedia();
+```
+
+### Reorder media
+
+```php
+Media::setNewOrder([3, 1, 2]); // media IDs in desired order
+```
+
+### Move/copy media between models
+
+```php
+$media->move($otherModel, 'images');
+$media->copy($otherModel, 'images');
+```
+
+## Events
+
+```php
+use Spatie\MediaLibrary\MediaCollections\Events\MediaHasBeenAddedEvent;
+use Spatie\MediaLibrary\Conversions\Events\ConversionWillStartEvent;
+use Spatie\MediaLibrary\Conversions\Events\ConversionHasBeenCompletedEvent;
+use Spatie\MediaLibrary\MediaCollections\Events\CollectionHasBeenClearedEvent;
+```
+
+Listen to these events to hook into the media lifecycle:
+```php
+Event::listen(MediaHasBeenAddedEvent::class, function ($event) {
+    $event->media; // the added Media model
+});
+
+Event::listen(ConversionHasBeenCompletedEvent::class, function ($event) {
+    $event->media;
+    $event->conversion;
+});
+```
+
+## Configuration
+
+Key `config/media-library.php` options:
+
+```php
+return [
+    'disk_name' => 'public',                    // default disk
+    'max_file_size' => 1024 * 1024 * 10,         // 10MB
+    'queue_connection_name' => '',                // queue connection
+    'queue_name' => '',                          // queue name
+    'queue_conversions_by_default' => true,       // queue conversions
+    'media_model' => Spatie\MediaLibrary\MediaCollections\Models\Media::class,
+    'file_namer' => Spatie\MediaLibrary\Support\FileNamer\DefaultFileNamer::class,
+    'path_generator' => Spatie\MediaLibrary\Support\PathGenerator\DefaultPathGenerator::class,
+    'url_generator' => Spatie\MediaLibrary\Support\UrlGenerator\DefaultUrlGenerator::class,
+    'image_driver' => 'gd',                      // 'gd', 'imagick', or 'vips'
+    'image_optimizers' => [/* optimizer config */],
+    'version_urls' => true,                       // cache busting
+    'default_loading_attribute_value' => null,     // 'lazy' for lazy loading
+];
+```
+
+### Custom Path Generator
+
+```php
+use Spatie\MediaLibrary\Support\PathGenerator\PathGenerator;
+
+class CustomPathGenerator implements PathGenerator
+{
+    public function getPath(Media $media): string
+    {
+        return md5($media->id) . '/';
+    }
+
+    public function getPathForConversions(Media $media): string
+    {
+        return $this->getPath($media) . 'conversions/';
+    }
+
+    public function getPathForResponsiveImages(Media $media): string
+    {
+        return $this->getPath($media) . 'responsive/';
+    }
+}
+```
+
+### Custom File Namer
+
+```php
+use Spatie\MediaLibrary\Support\FileNamer\FileNamer;
+
+class CustomFileNamer extends FileNamer
+{
+    public function originalFileName(string $fileName): string
+    {
+        return Str::slug(pathinfo($fileName, PATHINFO_FILENAME));
+    }
+
+    public function conversionFileName(string $fileName, Conversion $conversion): string
+    {
+        return $this->originalFileName($fileName) . '-' . $conversion->getName();
+    }
+
+    public function responsiveFileName(string $fileName): string
+    {
+        return pathinfo($fileName, PATHINFO_FILENAME);
+    }
+}
+```
+
+### Custom Media Model
+
+```php
+use Spatie\MediaLibrary\MediaCollections\Models\Media as BaseMedia;
+
+class Media extends BaseMedia
+{
+    // Add custom methods, scopes, or override behavior
+}
+```
+
+Register in config: `'media_model' => App\Models\Media::class`
+
+## Downloading Media
+
+### Single file
+
+```php
+return $media->toResponse($request); // download
+return $media->toInlineResponse($request); // display inline
+return $media->stream(); // stream
+```
+
+### ZIP download of collection
+
+```php
+use Spatie\MediaLibrary\Support\MediaStream;
+
+return MediaStream::create('photos.zip')
+    ->addMedia($model->getMedia('images'));
+```
+
+## Using with API Resources
+
+```php
+class PostResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'id' => $this->id,
+            'title' => $this->title,
+            'image' => $this->getFirstMediaUrl('images'),
+            'thumb' => $this->getFirstMediaUrl('images', 'thumb'),
+            'media' => $this->getMedia('images')->map(function ($media) {
+                return [
+                    'id' => $media->id,
+                    'url' => $media->getUrl(),
+                    'thumb' => $media->getUrl('thumb'),
+                    'name' => $media->name,
+                    'size' => $media->size,
+                    'type' => $media->mime_type,
+                ];
+            }),
+        ];
+    }
+}
+```