Laravel Medialibrary

https://github.com/spatie/laravel-medialibrary
Admin
A package that allows you to associate files with Eloquent models, offering a simple API for...
Tokens:148,164
Snippets:977
Trust Score:10
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install optimizers on Ubuntu with snap

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Alternative installation for Ubuntu using snap instead of npm for SVGO.

```bash
sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
sudo snap install svgo
```

--------------------------------

### Install optimizers on Ubuntu with npm

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Installs all required image optimization tools on Ubuntu using apt and npm.

```bash
sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
npm install -g svgo
```

--------------------------------

### Install optimizers on macOS with Homebrew

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Installs all required image optimization tools on macOS using Homebrew.

```bash
brew install jpegoptim
brew install optipng
brew install pngquant
brew install svgo
brew install gifsicle
brew install libavif
```

--------------------------------

### Install base package via Composer

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Use this command to install the base Media Library package if you are not using the Pro version.

```bash
composer require "spatie/laravel-medialibrary"
```

--------------------------------

### Install optimizers on Alpine Linux

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Installs all required image optimization tools on Alpine Linux using apk and npm.

```bash
apk add jpegoptim optipng pngquant gifsicle libavif-apps
npm install -g svgo
```

--------------------------------

### Model Setup

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Shows how to implement HasMedia and use InteractsWithMedia, including registering media collections and conversions.

```APIDOC
## Model Setup

### Description
Implement the HasMedia interface and use the InteractsWithMedia trait to enable media functionality on an Eloquent model. Register media collections and conversions in the corresponding methods.

### Method
PHP class implementation

### Code Example
```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);
    }
}
```
```

--------------------------------

### Install PHP-FFMpeg via Composer

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/converting-other-file-types/using-image-generators.md

Command to install the PHP-FFMpeg package required for video conversions.

```bash
composer require php-ffmpeg/php-ffmpeg
```

--------------------------------

### addMediaFromString method signature and usage example

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Adds a file containing the given string. The file is named 'text.txt' by default; use usingFileName to set a custom name. The example shows chaining usingFileName and toMediaCollection.

```php
/**
 * Add a file to the media library that contains the given string.
 *
 * @param string string
 *
 * @return \Spatie\MediaLibrary\MediaCollections\FileAdder
 */
 public function addMediaFromString(string $string): FileAdder
```

```php
$model
    ->addMediaFromString('my string')
    ->usingFileName('custom-filename.txt')
    ->toMediaCollection();
```

--------------------------------

### addMultipleMediaFromRequest method signature and usage example

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Adds multiple files from the current request. Returns a Collection of FileAdder instances, so you must loop over each FileAdder to apply middle methods. The example shows using each() to call toMediaCollection().

```php
/**
 * Add multiple files from the current request to the media library.
 *
 * @param string[] $keys
 *
 * @return Collection
 *
 * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded
 */
public function addMultipleMediaFromRequest(array $keyNames): Collection
```

```php
$fileAdders = $this->model
    ->addMultipleMediaFromRequest(['file-one', 'file-two'])
    ->each(function ($fileAdder) {
        $fileAdder->toMediaCollection();
    });
```

--------------------------------

### Model setup with HasMedia and InteractsWithMedia

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Implement HasMedia and use InteractsWithMedia to enable media functionality. Register a media collection and a conversion for thumbnails.

```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);
    }
}
```

--------------------------------

### Example implementation of TinyPlaceholderGenerator (Blurred)

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/responsive-images/generating-your-own-tiny-placeholder.md

An example implementation that generates a blurred tiny placeholder. It loads the source image, resizes it to 32 pixels wide, applies a blur of 5, and saves it to the destination path. The generated image must be a JPG.

```php
namespace App;

use Spatie\Image\Image;

class Blurred implements TinyPlaceholderGenerator
{
    public function generateTinyPlaceholder(string $sourceImagePath, string $tinyImageDestinationPath)
    {
        $sourceImage = Image::load($sourceImagePath);

        $sourceImage->width(32)->blur(5)->save($tinyImageDestinationPath);
    }
}
```

--------------------------------

### addMediaFromStream method signature and usage example

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Adds a file from a stream. The file is named 'text.txt' by default; use usingFileName to set a custom name. The example shows chaining usingFileName and toMediaCollection.

```php
/**
 * Add a file to the media library from a stream.
 *
 * @param $stream
 *
 * @return \Spatie\MediaLibrary\MediaCollections\FileAdder
 */
 public function addMediaFromStream($stream): FileAdder
```

```php
$model
    ->addMediaFromStream($stream)
    ->usingFileName('custom-filename.txt')
    ->toMediaCollection();
```

--------------------------------

### Using with API Resources

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Example of a Laravel API resource that includes media URLs and metadata.

```APIDOC
## Using with API Resources

### Description
Shows how to include media URLs and metadata in a Laravel API resource.

### Methods
- `getFirstMediaUrl($collectionName, $conversionName = '')` - Returns the URL of the first media item in a collection.
- `getMedia($collectionName)` - Returns a collection of media items.
- `$media->getUrl($conversionName = '')` - Returns the URL of a media item.

### Usage Example
```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,
                ];
            }),
        ];
    }
}
```
```

--------------------------------

### Regenerate starting from a specific ID

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/converting-images/regenerating-images.md

Use the `--starting-from-id` option to regenerate images starting at a specific ID (inclusive). Can be combined with `--exclude-starting-id` or `-X` to start after the provided ID.

```bash
php artisan media-library:regenerate --starting-from-id=1
```

```bash
php artisan media-library:regenerate --starting-from-id=1 --exclude-starting-id
```

```bash
php artisan media-library:regenerate --starting-from-id=1 -X
```

--------------------------------

### toMediaCollection

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Set the target media collection to default and start the import process. Returns the created Media model.

```APIDOC
## toMediaCollection

### Description
Set the target media collection to default. Will also start the import process.

### Method
toMediaCollection

### Signature
```php
public function toMediaCollection($collectionName = 'default', $diskName = '')
```

### Parameters
- `$collectionName` (string) - Optional - The name of the media collection. Defaults to 'default'.
- `$diskName` (string) - Optional - The name of the disk to use. Defaults to empty string.

### Returns
- `Media` - The created Media model.

### Throws
- `\Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded` - If the file cannot be added.
```

--------------------------------

### Implement HasMedia and InteractsWithMedia on a model

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/SKILL.md

Required setup for any Eloquent model that should have media. The model must implement the HasMedia interface and use the InteractsWithMedia trait.

```php
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class BlogPost extends Model implements HasMedia
{
    use InteractsWithMedia;
}
```

--------------------------------

### addAllMediaFromRequest method signature

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Adds all files from the current request. Returns a Collection of FileAdder instances, requiring a loop to use middle methods. See addMultipleMediaFromRequest for an example.

```php
/**
 * Add all files from the current request to the media library.
 *
 * @return Collection
 *
 * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded
 */
public function addAllMediaFromRequest(): Collection
```

--------------------------------

### Example directory structure

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/using-a-custom-file-removal-strategy.md

Shows a custom directory structure where the default file remover would delete the entire '2023' directory.

```text
media
---- 2023/09
------ file.jpg
------ second.jpg
------ conversions
--------- file-small.jpg
--------- file-medium.jpg
--------- file-big.jpg
--------- second-small.jpg
--------- second-medium.jpg
--------- second-big.jpg
...
```

--------------------------------

### Retrieve media URLs and paths

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/SKILL.md

Get the URL of the first media item in a collection, optionally for a specific conversion, or get all media in a collection.

```php
$url = $model->getFirstMediaUrl('images');
$thumbUrl = $model->getFirstMediaUrl('images', 'thumb');
$allMedia = $model->getMedia('images');
```

--------------------------------

### Get first media and its URL with getFirstMedia() and getFirstMediaUrl()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/retrieving-media.md

Convenience methods to retrieve the first media item and its URL directly from the model.

```php
$media = $yourModel->getFirstMedia();
$url = $yourModel->getFirstMediaUrl();
```

--------------------------------

### Combine --starting-from-id with modelType argument

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/converting-images/regenerating-images.md

The `--starting-from-id` option can be combined with the `modelType` argument to regenerate images for a specific model starting from a given ID.

```bash
php artisan media-library:regenerate "App\Models\Post" --starting-from-id=1
```

--------------------------------

### Methods to work with custom properties

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/using-custom-properties.md

Shows methods to check, get, set, and forget custom properties on a media item.

```php
$mediaItem->hasCustomProperty('primaryColor'); // returns true
$mediaItem->getCustomProperty('primaryColor'); // returns 'red'

$mediaItem->hasCustomProperty('does not exist'); // returns false
$mediaItem->getCustomProperty('does not exist'); // returns null

$mediaItem->setCustomProperty('name', 'value'); // adds a new custom property
$mediaItem->forgetCustomProperty('name'); // removes a custom property
```

--------------------------------

### Get media paths

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Retrieve the disk path of the first media item, optionally for a conversion.

```php
$path     = $model->getFirstMediaPath('images');
$thumbPath = $model->getFirstMediaPath('images', 'thumb');
```

--------------------------------

### Import MediaLibrary Event Classes

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Imports the event classes used to listen to media lifecycle events. These are required before using the Event::listen examples.

```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;
```

--------------------------------

### Get, set, check, and forget custom properties on existing media

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Use setCustomProperty(), getCustomProperty(), hasCustomProperty(), and forgetCustomProperty() on a media instance. Remember to call save() after setting or forgetting to persist changes.

```php
// 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();
```

--------------------------------

### Add media with custom properties and preserving original

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Use this snippet to add a file to the media library with custom properties and preserve the original file. The starting method is addMedia(), middle methods are withCustomProperties() and preservingOriginal(), and the finishing method is toMediaCollection().

```php
$yourModel
    ->addMedia($pathToFile) //starting method
    ->withCustomProperties(['mime-type' => 'image/jpeg']) //middle method
    ->preservingOriginal() //middle method
    ->toMediaCollection(); //finishing method
```

--------------------------------

### DefaultFileNamer implementation

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/naming-files.md

Example implementation of the FileNamer class with methods for original, conversion, and responsive file names. Extend this class and override the methods to customize naming.

```php
namespace Spatie\MediaLibrary\Support\FileNamer;

use Spatie\MediaLibrary\Conversions\Conversion;

class DefaultFileNamer extends FileNamer
{
    public function originalFileName(string $fileName): string
    {
        return pathinfo($fileName, PATHINFO_FILENAME);
    }

    public function conversionFileName(string $fileName, Conversion $conversion): string
    {
        $strippedFileName = pathinfo($fileName, PATHINFO_FILENAME);

        return "{$strippedFileName}-{$conversion->getName()}";
    }

    public function responsiveFileName(string $fileName): string
    {
        return pathinfo($fileName, PATHINFO_FILENAME);
    }
}
```

--------------------------------

### Set FFMPEG and FFProbe binary paths

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Defines the paths to FFMPEG and FFProbe binaries, used only when generating video thumbnails and having the php-ffmpeg/php-ffmpeg dependency installed. Defaults to /usr/bin/ffmpeg and /usr/bin/ffprobe.

```php
    /*
     * FFMPEG & FFProbe binaries paths, only used if you try to generate video
     * thumbnails and have installed the php-ffmpeg/php-ffmpeg composer
     * dependency.
     */
    'ffmpeg_path' => env('FFMPEG_PATH', '/usr/bin/ffmpeg'),
    'ffprobe_path' => env('FFPROBE_PATH', '/usr/bin/ffprobe'),
```

--------------------------------

### API Resource with media URLs

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Example of a Laravel API resource that includes media URLs and metadata.

```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,
                ];
            }),
        ];
    }
}
```

--------------------------------

### Add media using parent model connection

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/customising-database-connections.md

When adding media, the FileAdder automatically uses the parent model's database connection if set. This example shows the addMedia call.

```php
$model
    ->addMedia($path)
    ->toMediaCollection();
```

--------------------------------

### Create a listener class for MediaHasBeenAddedEvent

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/consuming-events.md

This listener logs the path of added media when the MediaHasBeenAddedEvent is fired. It uses the $event->media property to get the media object and its path.

```php
namespace App\Listeners;

use Log;
use Spatie\MediaLibrary\MediaCollections\Events\MediaHasBeenAddedEvent;

class MediaLogger
{
    public function handle(MediaHasBeenAddedEvent $event)
    {
        $media = $event->media;
        $path = $media->getPath();
        Log::info("file {$path} has been saved for media {$media->id}");
    }
}
```

--------------------------------

### Define media conversions in registerMediaConversions()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Example of defining multiple media conversions in the `registerMediaConversions()` method, including thumbnails, previews, banners, conditional conversions, format preservation, PDF page rendering, and video frame extraction.

```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);
}
```

--------------------------------

### Reorder media with Media::setNewOrder

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/ordering-media.md

Reorders media records by passing an array of IDs to Media::setNewOrder. The first ID gets the starting order (defaults to 1), the second gets startOrder + 1, and so on. An optional starting order number can be supplied.

```php
 /**
  * This function reorders the records: the record with the first id in the array
  * will get the starting order (defaults to 1), the record with the second id
  * will get the starting order + 1, and so on.
  *
  * A starting order number can be optionally supplied.
  *
  * @param array $ids
  * @param int $startOrder
  */
Media::setNewOrder([11, 2, 26]);
```

--------------------------------

### Use a conversion as an attachment with mailAttachment()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/attaching-media-in-mails.md

Call mailAttachment() on a Media model to get an Attachment for a Mailable. Pass the conversion name to get an attachable conversion, as shown in this BlogPostThumbnailMail example.

```php
namespace App\Mails;

use Illuminate\Mail\Mailable;
use Spatie\MediaLibrary\MediaCollections\Models\Media;
use App\Models\BlogPost;

class BlogPostThumbnailMail extends Mailable
{
    public function __construct(public BlogPost $blogPost)
    {

    }

    public function build()
    {
        /** @var \Spatie\MediaLibrary\MediaCollections\Models\Media $mediaItem */
        $mediaItem = $this->blogPost->getFirstMedia();
        
        // pass the conversion name
        $thumbnailAttachment = $mediaItem->mailAttachment('thumbnail');
    
        return $this
            ->view('mails/blogpostThumbnail')
            ->attach($thumbnailAttachment);
    }
}
```

--------------------------------

### Register multiple media conversions and get URLs

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/converting-images/defining-conversions.md

Registers multiple media conversions (thumb, old-picture, thumb-cropped) in the model's registerMediaConversions method, then shows how to retrieve their URLs using getUrl().

```php
// in your model
use Spatie\Image\Enums\BorderType;
use Spatie\Image\Enums\CropPosition;

// ...

    public function registerMediaConversions(?Media $media = null): void
    {
        $this->addMediaConversion('thumb')
              ->width(368)
              ->height(232)
              ->sharpen(10);

        $this->addMediaConversion('old-picture')
              ->sepia()
              ->border(10, BorderType::Overlay, 'black');
              
        $this->addMediaConversion('thumb-cropped')
            ->crop(400, 400, CropPosition::Center); // Trim or crop the image to the center for specified width and height.
    }
```

```php
$media->getUrl('thumb') // the url to the thumbnail
$media->getUrl('old-picture') // the url to the sepia, bordered version
```

--------------------------------

### Disable CDN and manually include Sortable

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/disable-cdn.md

Set the 'include_sortable_cdn_script' option to false in the media-library.php config file to disable the automatic CDN loading of the Sortable library. Then, manually install Sortable via npm and include it globally in your app.js file with `import Sortable from 'sortablejs'` and assign it to `window.Sortable`. This setup ensures that Sortable is available for Media Library Pro components when the CDN is disabled.

```php
    ...
    /*
     * When disabling this option, Media Library Pro don't include a script tag to load the Sortable library via a CDN.
     * You have to include the Sortable library by yourself!
     */
    'include_sortable_cdn_script' => false,
    ...
```

```js
import Sortable from 'sortablejs'

window.Sortable = Sortable
```

--------------------------------

### Add media to a specific disk using toMediaCollection

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/working-with-multiple-filesystems.md

Use the second parameter of `toMediaCollection` to specify the disk where the file should be stored. In this example, the file is stored on a disk named 's3'.

```php
// Will be stored on a disk named s3
$yourModel->addMedia($pathToAFile)->toMediaCollection('images', 's3');
```

--------------------------------

### FileAdder chainable options before toMediaCollection()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Shows all chainable methods available on the FileAdder when adding media, including usingName, usingFileName, setOrder, withCustomProperties, withManipulations, withResponsiveImages, storingConversionsOnDisk, and addCustomHeaders. 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');
```

--------------------------------

### Get URL, full URL, path, and temporary S3 URL

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/retrieving-media.md

Use getUrl(), getFullUrl(), getPath(), and getTemporaryUrl() on a Media instance. getTemporaryUrl is for S3 only and accepts a Carbon expiration time; pass null to use default expiration.

```php
$publicUrl = $mediaItems[0]->getUrl();
$publicFullUrl = $mediaItems[0]->getFullUrl(); // URL including domain
$fullPathOnDisk = $mediaItems[0]->getPath();
$temporaryS3Url = $mediaItems[0]->getTemporaryUrl(Carbon::now()->addMinutes(5)); // Temporary S3 url (Keep first parameter null to use default expiration time)
```

--------------------------------

### Use Media model methods

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Access URL, path, full URL, temporary URL, and check conversion generation directly on a Media instance.

```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
```

--------------------------------

### Custom Media Model with tenant connection

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/customising-database-connections.md

Create a custom media model extending the base Media class and set the $connection property to 'tenant' to use a different database connection.

```php
<?php

namespace App\Models;

use Spatie\MediaLibrary\MediaCollections\Models\Media as BaseMedia;

class Media extends BaseMedia {

    protected $connection = 'tenant';

}
```

--------------------------------

### FileAdder Options

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Chainable methods to configure a media addition before calling toMediaCollection().

```APIDOC
## FileAdder Options

### Description
All methods are chainable before calling `toMediaCollection()`. They allow you to set the display name, file name, order, custom properties, manipulations, responsive images, conversion disk, and custom headers for the media being added.

### Methods
- **usingName(string $name)** - Sets the display name of the media.
- **usingFileName(string $fileName)** - Sets the file name on disk.
- **setOrder(int $order)** - Sets the order within the collection.
- **withCustomProperties(array $properties)** - Adds custom properties to the media.
- **withManipulations(array $manipulations)** - Sets manipulations for conversions.
- **withResponsiveImages()** - Generates responsive image variants.
- **storingConversionsOnDisk(string $disk)** - Stores conversions on a different disk.
- **addCustomHeaders(array $headers)** - Adds custom headers for the media.

### Example
```php
$model->addMedia($file)
    ->usingName('Custom Name')
    ->usingFileName('custom-name.jpg')
    ->setOrder(3)
    ->withCustomProperties(['alt' => 'A landscape photo'])
    ->withManipulations(['thumb' => ['filter' => 'greyscale']])
    ->withResponsiveImages()
    ->storingConversionsOnDisk('s3')
    ->addCustomHeaders(['CacheControl' => 'max-age=31536000'])
    ->toMediaCollection('images');
```

### Store on cloud disk
```php
$model->addMedia($file)->toMediaCollectionOnCloudDisk('images');
```
```

--------------------------------

### Run migrations

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Executes the published migrations to create the necessary database tables.

```bash
php artisan migrate
```

--------------------------------

### Define media collections in registerMediaCollections()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Shows how to define media collections with various options: basic, singleFile, onlyKeepLatest, useDisk, storeConversionsOnDisk, acceptsMimeTypes, acceptsFile, useFallbackUrl/Path, withResponsiveImages, and registerMediaConversions. All methods are chainable on the collection.

```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);
        });
}
```

--------------------------------

### Download file with response()->download()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/downloading-media/downloading-a-single-file.md

Use this more verbose approach when you need more control over the download. It uses the media item's path and file name.

```php
use Spatie\MediaLibrary\MediaCollections\Models\Media;

class DownloadMediaController
{
   public function show(Media $mediaItem)
   {
       return response()->download($mediaItem->getPath(), $mediaItem->file_name);
   }
}
```

--------------------------------

### getSrcset

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Gets the srcset string for responsive images.

```APIDOC
## getSrcset

### Description
Gets the srcset string for responsive images, optionally for a specific conversion.

### Method
Media::getSrcset

### Parameters
- **conversionName** (string) - Optional - The conversion name.

### Request Example
```blade
<img src="{{ $media->getUrl() }}" srcset="{{ $media->getSrcset() }}" />
<img src="{{ $media->getUrl('hero') }}" srcset="{{ $media->getSrcset('hero') }}" />
```

### Response
Returns a string containing the srcset.
```

--------------------------------

### getFallbackMediaUrl

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Gets the fallback URL for a given collection.

```APIDOC
## getFallbackMediaUrl

### Description
Gets the fallback URL for the specified collection. This is used when no media is present.

### Method
PHP method

### Endpoint
`$model->getFallbackMediaUrl($collectionName)`

### Parameters
- **$collectionName** (string) - Required - The name of the media collection.

### Request Example
```php
$url = $model->getFallbackMediaUrl('avatar');
```

### Response
Returns a string URL.

```

--------------------------------

### getPlaceholderSvg

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Gets a tiny blurred base64 placeholder SVG for responsive images.

```APIDOC
## getPlaceholderSvg

### Description
Gets a tiny blurred base64 placeholder SVG for responsive images.

### Method
ResponsiveImages::getPlaceholderSvg

### Parameters
None.

### Request Example
```php
$svg = $media->responsiveImages()->getPlaceholderSvg();
```

### Response
Returns a string containing the SVG data URI.
```

--------------------------------

### getLastMediaUrl

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Gets the URL of the last media item in a collection, optionally for a specific conversion.

```APIDOC
## getLastMediaUrl

### Description
Gets the URL of the last media item in the specified collection. Optionally, you can specify a conversion name to get the URL for that conversion.

### Method
PHP method

### Endpoint
`$model->getLastMediaUrl($collectionName, $conversionName = '')`

### Parameters
- **$collectionName** (string) - Required - The name of the media collection.
- **$conversionName** (string) - Optional - The name of the conversion (e.g., 'thumb').

### Request Example
```php
$lastUrl = $model->getLastMediaUrl('images', 'thumb');
```

### Response
Returns a string URL.

```

--------------------------------

### Retrieve media from all collections with getMedia("*")

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/retrieving-media.md

Pass "*" to getMedia() to retrieve files from all collections. Returns a collection of Media objects.

```php
$mediaItems = $yourModel->getMedia("*");
```

--------------------------------

### getFirstMediaUrl

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Gets the URL of the first media item in a collection, optionally for a specific conversion.

```APIDOC
## getFirstMediaUrl

### Description
Gets the URL of the first media item in the specified collection. Optionally, you can specify a conversion name to get the URL for that conversion.

### Method
PHP method

### Endpoint
`$model->getFirstMediaUrl($collectionName, $conversionName = '')`

### Parameters
- **$collectionName** (string) - Required - The name of the media collection.
- **$conversionName** (string) - Optional - The name of the conversion (e.g., 'thumb').

### Request Example
```php
$url = $model->getFirstMediaUrl('images');
$thumbUrl = $model->getFirstMediaUrl('images', 'thumb');
```

### Response
Returns a string URL.

```

--------------------------------

### Enable responsive images on FileAdder, conversion, and collection

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Call withResponsiveImages() on the FileAdder, on a media conversion, or on a collection to generate multiple image sizes for optimal loading.

```php
// On the FileAdder
$model->addMedia($file)
    ->withResponsiveImages()
    ->toMediaCollection('images');
```

```php
// On a conversion
$this->addMediaConversion('hero')
    ->fit(Fit::Max, 1200, 800)
    ->withResponsiveImages();
```

```php
// On a collection
$this->addMediaCollection('photos')
    ->withResponsiveImages();
```

--------------------------------

### getFirstMediaPath

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Gets the disk path of the first media item in a collection, optionally for a specific conversion.

```APIDOC
## getFirstMediaPath

### Description
Gets the disk path of the first media item in the specified collection. Optionally, you can specify a conversion name to get the path for that conversion.

### Method
PHP method

### Endpoint
`$model->getFirstMediaPath($collectionName, $conversionName = '')`

### Parameters
- **$collectionName** (string) - Required - The name of the media collection.
- **$conversionName** (string) - Optional - The name of the conversion (e.g., 'thumb').

### Request Example
```php
$path = $model->getFirstMediaPath('images');
$thumbPath = $model->getFirstMediaPath('images', 'thumb');
```

### Response
Returns a string path.

```

--------------------------------

### Get media URLs

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Retrieve the original URL, a conversion URL, or the last media URL.

```php
$url     = $model->getFirstMediaUrl('images');           // original URL
$thumbUrl = $model->getFirstMediaUrl('images', 'thumb'); // conversion URL
$lastUrl  = $model->getLastMediaUrl('images', 'thumb');
```

--------------------------------

### Retrieve the mime type

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/retrieving-media.md

Access the mime_type property to get the file's MIME type.

```php
$mediaItems[0]->mime_type; // Returns the mime type
```

--------------------------------

### Get custom property with default value

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/using-custom-properties.md

Specify a default value when retrieving a custom property.

```php
$mediaItem->getCustomProperty('isPublic', false);
```

--------------------------------

### addMediaFromDisk method signature

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Adds a file from a specified disk. The disk parameter defaults to null, which likely uses the default disk.

```php
/**
 * Add a file from the given disk.
 *
 * @param string $key
 * @param string $disk
 *
 * @return \Spatie\MediaLibrary\MediaCollections\FileAdder
 */
public function addMediaFromDisk(string $key, string $disk = null): FileAdder
```

--------------------------------

### Get fallback media URL

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Retrieve the fallback URL for a media collection, used when no media exists.

```php
$url = $model->getFallbackMediaUrl('avatar');
```

--------------------------------

### Get media items from a collection

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Retrieve all media items, the first, last, or check existence in a named collection.

```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
```

--------------------------------

### Define a media collection with withResponsiveImages

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/working-with-media-collections/defining-media-collections.md

Define a media collection named 'my-collection' and enable responsive image generation by calling withResponsiveImages() on the collection.

```php
// in your model

public function registerMediaCollections(): void
{
    $this
        ->addMediaCollection('my-collection')
        ->withResponsiveImages();
}
```

--------------------------------

### Retrieve file size and human-readable size

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/retrieving-media.md

Use the size property to get bytes and human_readable_size for a human-readable format.

```php
$mediaItems[0]->size; // Returns the size in bytes
$mediaItems[0]->human_readable_size; // Returns the size in a human readable format (eg. 1,5 MB)
```

--------------------------------

### Force responsive images regeneration with --with-responsive-images

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/converting-images/regenerating-images.md

Use the `--with-responsive-images` option to force responsive images to be regenerated.

```bash
php artisan media-library:regenerate --with-responsive-images
```

--------------------------------

### addMediaFromUrl

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/api/adding-files.md

Adds a remote file to the media library from a URL. Only accepts URLs starting with http:// or https://.

```APIDOC
## addMediaFromUrl

### Description
Add a remote file to the media library from a URL. Only URLs starting with `http://` or `https://` are accepted.

### Method
addMediaFromUrl

### Signature
```php
public function addMediaFromUrl(string $url)
```

### Parameters
- **$url** (string) - Required - The URL of the remote file.

### Returns
- **mixed** - The result of the operation.

### Exceptions
- **\Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded** - Thrown when the file cannot be added.

### Security Note
This method fetches whatever URL you pass to it from your server. It validates only that the URL starts with `http://` or `https://`, not that the destination is safe to reach. Passing user supplied URLs directly exposes your application to server side request forgery (SSRF). Only call this method with URLs you control or have validated against an allowlist of hosts.
```

--------------------------------

### Get last media and its URL with getLastMedia() and getLastMediaUrl()

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/retrieving-media.md

Similar convenience methods to retrieve the last media item and its URL.

```php
$media = $yourModel->getLastMedia();
$url = $yourModel->getLastMediaUrl();
```

--------------------------------

### Media Library Configuration Options

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Key configuration options for the media-library.php config file. Includes disk name, max file size, queue settings, and class references for customization.

```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
];
```

--------------------------------

### Add media with custom properties

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/advanced-usage/using-custom-properties.md

Pass an array of custom properties when adding a file to the media library using the withCustomProperties method.

```php
$mediaItem = $yourModel
    ->addMedia($pathToFile)
    ->withCustomProperties(['primaryColor' => 'red'])
    ->toMediaCollection();
```

--------------------------------

### Use video thumbnail in HTML video tag

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/converting-other-file-types/using-image-generators.md

Example of using the generated thumbnail as a poster in an HTML video element.

```html
<video controls poster="{{ $video->getUrl('thumb') }}">
  <source src="{{ $video->getUrl() }}" type="video/mp4">
  Your browser does not support the video tag.
</video>
```

--------------------------------

### Add preview conversion with registerMediaConversions

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/basic-usage/preparing-your-model.md

Define a media conversion named 'preview' that fits the image to 300x300 pixels and is non-queued. This is required to generate a preview thumbnail for the Collection component.

```php
use Spatie\Image\Enums\Fit;
use Spatie\MediaLibrary\MediaCollections\Models\Media;

public function registerMediaConversions(?Media $media = null): void
{
    $this
        ->addMediaConversion('preview')
        ->fit(Fit::Contain, 300, 300)
        ->nonQueued();
}
```

--------------------------------

### Get placeholder SVG for responsive images

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Retrieve a tiny blurred base64 placeholder SVG from the responsive images of a media item.

```php
$svg = $media->responsiveImages()->getPlaceholderSvg(); // tiny blurred base64 placeholder
```

--------------------------------

### Default configuration file content

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Displays the default settings for the Media Library, including disk storage, file size limits, and queue configurations.

```php
return [

    /*
     * The disk on which to store added files and derived images by default. Choose
     * one or more of the disks you've configured in config/filesystems.php.
     */
    'disk_name' => env('MEDIA_DISK', 'public'),

    /*
     * The maximum file size of an item in bytes.
     * Adding a larger file will result in an exception.
     */
    'max_file_size' => 1024 * 1024 * 10,
    
    /*
     * This queue connection will be used to generate derived and responsive images.
     * Leave empty to use the default queue connection.
     */
    'queue_connection_name' => '',

    /*
     * This queue will be used to generate derived and responsive images.
     * Leave empty to use the default queue.
     */
    'queue_name' => '',

    /*
     * By default all conversions will be performed on a queue.
     */
    'queue_conversions_by_default' => env('QUEUE_CONVERSIONS_BY_DEFAULT', true),

    /*
     * The fully qualified class name of the media model.
     */
    'media_model' => Spatie\MediaLibrary\MediaCollections\Models\Media::class,

    /*
     * The fully qualified class name of the model used for temporary uploads.
     *
     * This model is only used in Media Library Pro (https://medialibrary.pro)
     */
    'temporary_upload_model' => Spatie\MediaLibraryPro\Models\TemporaryUpload::class,

    /*
     * When enabled, Media Library Pro will only process temporary uploads there were uploaded
     * in the same session. You can opt to disable this for stateless usage of
     * the pro components.
     */
    'enable_temporary_uploads_session_affinity' => true,

    /*
     * When enabled, Media Library pro will generate thumbnails for uploaded file.
     */
    'generate_thumbnails_for_temporary_uploads' => true,

    /*
     * This is the class that is responsible for naming generated files.
     */
    'file_namer' => Spatie\MediaLibrary\Support\FileNamer\DefaultFileNamer::class,

    /*
     * The class that contains the strategy for determining a media file's path.
     */
    'path_generator' => Spatie\MediaLibrary\Support\PathGenerator\DefaultPathGenerator::class,

    /*
     * When urls to files get generated, this class will be called. Use the default
     * if your files are stored locally above the site root or on s3.
     */
    'url_generator' => Spatie\MediaLibrary\Support\UrlGenerator\DefaultUrlGenerator::class,

    /*
     * Whether to activate versioning when urls to files get generated.
     * When activated, this attaches a ?v=xx query string to the URL.
     */
    'version_urls' => false,
];
```

--------------------------------

### Get temporary URL for S3

Source: https://github.com/spatie/laravel-medialibrary/blob/main/resources/boost/skills/medialibrary-development/references/medialibrary-guide.md

Generate a temporary URL for a media item, typically for S3 storage, with a specified expiration time.

```php
$tempUrl = $model->getFirstTemporaryUrl(
    now()->addMinutes(30),
    'images',
    'thumb'
);
```

--------------------------------

### Get a derived image URL

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/introduction.md

Retrieves the URL of a derived image (e.g., thumbnail) from the first media item in the 'images' collection.

```php
$yourModel->getMedia('images')->first()->getUrl('thumb');
```

--------------------------------

### Publish migrations

Source: https://github.com/spatie/laravel-medialibrary/blob/main/docs/installation-setup.md

Publishes the migration file required to create the media table in your database.

```bash
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
```
Tokens:
Raw