Plank Laravel Mediable

https://github.com/plank/laravel-mediable
Admin
Plank Laravel Mediable is a package for easily uploading and attaching media files to Eloquent...
Tokens:80,000
Snippets:588
Trust Score:8.3
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Sphinx

Source: https://github.com/plank/laravel-mediable/blob/master/CONTRIBUTING.md

Install Sphinx, the documentation builder, using pip. Required before building the documentation.

```bash
$ pip install Sphinx
```

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

### Media attributes example

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Shows the attributes of a Media instance used in the examples: disk, directory, filename, and extension.

```php
[
        'disk' => 'uploads',
        'directory' => 'foo/bar',
        'filename' => 'picture',
        'extension' => 'jpg'
        // ...
];
```

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

### Pass adapter options with withOptions

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Specify additional option flags for the underlying filesystem adapter, useful for cloud storage like S3. The example sets a Cache-Control header.

```php
<?php
MediaUploader::fromSource($request->file('image'))
    ->withOptions(['Cache-Control' => 'max-age=3600'])
    ->upload();
```

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

### Media path methods and attributes

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Lists the path-related methods and attributes exposed by a Media instance, with example outputs.

```php
<?php
$media->getAbsolutePath();
// /var/www/site/public/uploads/foo/bar/picture.jpg

$media->getDiskPath();
// foo/bar/picture.jpg

$media->directory;
// foo/bar

$media->basename;
// picture.jpg

$media->filename;
// picture

$media->extension;
// jpg
```

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

### Install laravel-mediable via Composer

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/installation.rst

Run this command to add the package to your Laravel application.

```bash
$ composer require plank/laravel-mediable
```

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

### Example of N+1 problem when loading media

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

This example shows how accessing media for each post in a loop can cause the N+1 problem, executing one query for the posts and additional queries for each post's media.

```php
<?php
$posts = Post::limit(10)->get();
foreach($posts as $post){
    echo $post->firstMedia('thumbnail')->getUrl();
}
```

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

### Retrieve media by multiple tags with getMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Pass an array of tags to get media attached to any of them. Set $match_all to true to require all tags, or use the alias getMediaMatchAll().

```php
<?php
$post->getMedia(['header', 'footer']); // get media with either tag
$post->getMedia(['header', 'footer'], true); //get media with both tags
$post->getMediaMatchAll(['header', 'footer']); //alias
```

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

### Get all media grouped by tag with getAllMediaByTag()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Returns all media attached to the model, grouped by tag.

```php
<?php
$post->getAllMediaByTag();
```

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

### Automatic rehydration example with loadMedia and attachMedia

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Shows how loadMedia() reloads media and how attachMedia() marks a tag as dirty, causing getMedia() to reload on next access.

```php
<?php
$post->loadMedia();
$post->getMedia('gallery'); // returns an empty collection
$post->getMedia('thumbnail'); // returns an empty collection
$post->attachMedia($media, 'gallery'); // marks the gallery tag as dirty

$post->getMedia('thumbnail'); // still returns an empty collection
$post->getMedia('gallery'); // performs a `loadMedia()`, returns a collection with $media
```

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

### Import string data using MediaUploader::fromString

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Imports string file data (e.g., an encoded image) into the media library. The example shows converting an image to a JPG string and then uploading it to a destination.

```php
<?php
// Encoded image converted to string
$jpg = Image::make('https://www.plankdesign.com/externaluse/plank.png')->encode('jpg');

MediaUploader::fromString($jpg)
    ->toDestination(...)
    ->upload();
```

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

### Import file from disk using MediaUploader::import

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Creates a media record for a file already on the desired filesystem disk. Use import() with disk, directory, filename, and extension, or importPath() with disk and full path.

```php
<?php
$media = MediaUploader::import($disk, $directory, $filename, $extension);
// or
$media = MediaUploader::importPath($disk, $path);
```

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

### Import media records with media:import

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/commands.rst

Creates a media record in the database for any files on the disk that do not already have a record. Applies any type restrictions in the mediable configuration file.

```bash
$ php artisan media:import [disk]
```

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

### Build documentation with Sphinx

Source: https://github.com/plank/laravel-mediable/blob/master/CONTRIBUTING.md

Build the documentation by changing to the docs directory and running make html. The documentation is written in ReStructuredText.

```bash
$ cd docs/
$ make html
```

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

### Get URL of a variant

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Finds the 'thumbnail' variant of a media item and returns its URL. Useful for retrieving a specific variant's URL.

```php
<?php
$src = $post->getMedia('feature')
    ->findVariant('thumbnail')
    ->getUrl()
```

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

### Basic upload with MediaUploader facade

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Uploads a file from an HTTP request to the root of the default disk. Uses the MediaUploader facade and the fromSource() method with an UploadedFile instance, then calls upload().

```php
<?php
use MediaUploader; //use the facade
$media = MediaUploader::fromSource($request->file('thumbnail'))->upload();
```

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

### MediaUploader::fromSource()->withOptions()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Specifies additional option flags to be passed to the underlying filesystem adapter, useful for cloud storage like S3.

```APIDOC
## MediaUploader::fromSource()->withOptions()

### Description
Specifies additional option flags to be passed to the underlying filesystem adapter, useful for cloud storage like S3.

### Method
withOptions

### Parameters
#### Request Body
- **options** (array) - Required - An associative array of options to pass to the filesystem adapter.

### Request Example
```php
<?php
MediaUploader::fromSource($request->file('image'))
    ->withOptions(['Cache-Control' => 'max-age=3600'])
    ->upload();
```

### Response
No return value documented.
```

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

### Configure model, source adapters, and URL generators in config/mediable.php

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/configuration.rst

Shows the default configuration for the media model, source adapters (class and pattern based), and URL generators for local and S3 disks. The model must extend Plank\Mediable\Media::class. Adapters can map to a class or a regex pattern.

```php
<?php
//...
/*
 * FQCN of the model to use for media
 *
 * Should extend Plank\Mediable\Media::class
 */
'model' => Plank\Mediable\Media::class,

/*
 * List of adapters to use for various source inputs
 *
 * Adapters can map either to a class or a pattern (regex)
 */
'source_adapters' => [
    'class' => [
        Symfony\Component\HttpFoundation\File\UploadedFile::class => Plank\Mediable\SourceAdapters\UploadedFileAdapter::class,
        Symfony\Component\HttpFoundation\File\File::class => Plank\Mediable\SourceAdapters\FileAdapter::class,
        Psr\Http\Message\StreamInterface::class => Plank\Mediable\SourceAdapters\StreamAdapter::class,
    ],
    'pattern' => [
        '^https?://' => Plank\Mediable\SourceAdapters\RemoteUrlAdapter::class,
        '^/' => Plank\Mediable\SourceAdapters\LocalPathAdapter::class
    ],
],

/*
 * List of URL Generators to use for handling various filesystem disks
 */
'url_generators' => [
    'local' => Plank\Mediable\UrlGenerators\LocalUrlGenerator::class,
    's3' => Plank\Mediable\UrlGenerators\S3UrlGenerator::class,
],

```

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

### Run tests with PHPUnit

Source: https://github.com/plank/laravel-mediable/blob/master/CONTRIBUTING.md

Run the test suite using PHPUnit. Execute this command from the project root.

```bash
$ phpunit
```

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

### MediaUploader::import

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Creates a media record for a file already on the desired filesystem disk.

```APIDOC
## MediaUploader::import

### Description
Creates a media record for a file already in place on the desired filesystem disk.

### Method
import

### Parameters
- **$disk** (string) - Required - The filesystem disk name.
- **$directory** (string) - Required - The directory path on the disk.
- **$filename** (string) - Required - The filename without extension.
- **$extension** (string) - Required - The file extension.

### Return Value
Returns a Media instance.

### Example
php
$media = MediaUploader::import($disk, $directory, $filename, $extension);

```

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

### Sync media with media:sync

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/commands.rst

Performs both media:import and media:prune commands together.

```bash
$ php artisan media:sync [disk]
```

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

### Configure filesystem disks in config/filesystems.php

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/configuration.rst

Defines the 'local' and 'uploads' disks for storing media files. The 'uploads' disk is set as the default in the package configuration. Ensure the 'url' and 'visibility' keys are set as shown.

```php
<?php
//...
'disks' => [
    'local' => [
        'driver' => 'local',
        'root'   => storage_path('app'),
        'url' => 'https://example.com/storage/app',
        'visibility' => 'public'
    ],

    'uploads' => [
        'driver' => 'local',
        'root'   => public_path('uploads'),
        'url' => 'https://example.com/uploads',
        'visibility' => 'public'
    ],
]
//...
```

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

### Run migrations for mediable

Source: https://github.com/plank/laravel-mediable/blob/master/README.md

Runs the migrations to add the required tables to the database.

```bash
php artisan migrate
```

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

### Specify disk and directory for upload

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Configures the uploader to use a custom disk and directory before uploading. Shows chaining toDisk(), toDirectory(), and toDestination() methods, with toDestination() as an alternative to specifying both at once.

```php
<?php
$uploader = MediaUploader::fromSource($request->file('thumbnail'))

// specify a disk to use instead of the default
->toDisk('s3');

// place the file in a directory relative to the disk root
->toDirectory('user/john/profile')

// alternatively, specify both the disk and directory at once
->toDestination('s3', 'user/john/profile')

->upload();
```

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

### Retrieve first media with firstMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Shorthand for getMedia('thumbnail')->first(), returns the first Media entity.

```php
<?php
$media = $post->firstMedia('thumbnail');
// shorthand for
$media = $post->getMedia('thumbnail')->first();
```

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

### Run migrations to create mediable tables

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/installation.rst

Run this artisan command to add the required tables to your database.

```bash
$ php artisan migrate
```

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

### Query Media with helper methods

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Shows query builder helpers on the Media class for filtering by directory, path, or basename.

```php
<?php
Media::inDirectory('uploads', 'foo/bar');
Media::inOrUnderDirectory('uploads', 'foo');
Media::forPathOnDisk('uploads', 'foo/bar/picture.jpg');
Media::whereBasename('picture.jpg');
```

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

### Eager load media by specific tags using withMedia() and withMediaMatchAll()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Load only media attached to specific tags. withMedia() loads media attached to either tag, while withMediaMatchAll() loads media attached to both tags.

```php
<?php
$posts = Post::withMedia(['thumbnail', 'featured'])->get(); // attached to either tags
$posts = Post::withMediaMatchAll(['thumbnail', 'featured'])->get(); // attached to both tags
```

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

### Attach media to a model with tags

Source: https://github.com/plank/laravel-mediable/blob/master/README.md

Creates a Post model and attaches the previously uploaded Media with the 'thumbnail' tag.

```php
$post = Post::create($this->request->input());
$post->attachMedia($media, ['thumbnail']);
```

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

### Publish config and migration files with artisan vendor:publish

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/installation.rst

Run this artisan command to publish the package's config file (config/mediable.php) and migration file (database/migrations/####_##_##_######_create_mediable_tables.php).

```bash
$ php artisan vendor:publish --provider="Plank\Mediable\MediableServiceProvider"
```

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

### Eager load media and variants using withMediaAndVariants()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Eager load media along with its variants. Use withMediaAndVariants() for either tag match, or withMediaAndVariantsMatchAll() for both tags match.

```php
<?php
Post::withMediaAndVariants($tags)->get();
Post::withMediaAndVariantsMatchAll($tags)->get();
```

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

### Load and display media URL

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/installation.rst

Load a model with its media and output the URL of the first media item in the 'thumbnail' tag.

```php
<?php
$post = Post::withMedia()->find($postId);
echo $post->getMedia('thumbnail')->first()->getUrl();
```

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

### MediaUploader::fromSource()->upload() with validation

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Demonstrates how to configure validation options and upload a file. Throws Plank\Mediable\MediaUploadException if validation fails.

```APIDOC
## MediaUploader::fromSource()->upload()

### Description
Uploads a file after performing validation checks. If any validation fails, a `Plank\Mediable\MediaUploadException` is thrown.

### Method
upload

### Endpoint
MediaUploader::fromSource($source)->upload()

### Parameters
#### Fluent Methods
- **setModelClass** (string) - Optional - The model class to use for the media.
- **setMaximumSize** (int) - Optional - Maximum filesize in bytes.
- **setStrictTypeChecking** (bool) - Optional - Whether the aggregate type must match both MIME type and extension.
- **setAllowUnrecognizedTypes** (bool) - Optional - Whether to allow the 'other' aggregate type.
- **setAllowedMimeTypes** (array) - Optional - Only allow files of specific MIME types.
- **setAllowedExtensions** (array) - Optional - Only allow files of specific extensions.
- **setAllowedAggregateTypes** (array) - Optional - Only allow files of specific aggregate types.
- **validateHash** (string, string) - Optional - Ensure file contents match a provided hash. First argument is the hash, second is the algorithm (supports any algorithm supported by PHP's hash() function).

### Request Example
```php
<?php
$media = MediaUploader::fromSource($request->file('image'))
    ->setModelClass(MediaSubclass::class)
    ->setMaximumSize(99999)
    ->setStrictTypeChecking(true)
    ->setAllowUnrecognizedTypes(true)
    ->setAllowedMimeTypes(['image/jpeg'])
    ->setAllowedExtensions(['jpg', 'jpeg'])
    ->setAllowedAggregateTypes(['image'])
    ->validateHash('3ef5e70366086147c2695325d79a25cc', 'md5')
    ->validateHash('5e96e1fa58067853219c4cb6d3c1ce01cc5cc8ce', 'sha1')
    ->upload();
```

### Response
#### Success Response
- Returns a `Media` instance.

#### Error Handling
- Throws `Plank\Mediable\MediaUploadException` with a message indicating why the file was rejected.
```

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

### Set output format methods

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Lists the fluent methods to set the output format for a manipulation. If not specified, the original file's format is used based on mime_type and extension.

```php
<?php
$manipulation->outputJpegFormat();
$manipulation->outputPngFormat();
$manipulation->outputGifFormat();
$manipulation->outputTiffFormat();
$manipulation->outputBmpFormat();
$manipulation->outputWebpFormat();
$manipulation->outputHeicFormat();
$manipulation->setOutputFormat($format);
```

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

### Move and rename media files

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Shows methods to move a media file to a new directory, optionally with a new filename, and to rename the file.

```php
<?php
$media->move('new/directory');
$media->move('new/directory', 'new-filename');
$media->rename('new-filename');
$media->moveToDisk('uploads', 'new/directory', 'new-filename');
```

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

### MediaUploader::importPath

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Creates a media record for a file already in place on the desired filesystem disk using a full path.

```APIDOC
## MediaUploader::importPath

### Description
Creates a media record for a file already in place on the desired filesystem disk using a full path.

### Method
importPath

### Parameters
- **$disk** (string) - Required - The filesystem disk name.
- **$path** (string) - Required - The full path to the file on the disk.

### Return Value
Returns a Media instance.

### Example
php
$media = MediaUploader::importPath($disk, $path);

```

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

### Configure validation and upload with MediaUploader

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Sets validation options on the MediaUploader and uploads the file. Throws Plank\Mediable\MediaUploadException if validation fails.

```php
<?php
$media = MediaUploader::fromSource($request->file('image'))

    // model class to use
    ->setModelClass(MediaSubclass::class)

    // maximum filesize in bytes
    ->setMaximumSize(99999)

    // whether the aggregate type must match both the MIME type and extension
    ->setStrictTypeChecking(true)

    // whether to allow the 'other' aggregate type
    ->setAllowUnrecognizedTypes(true)

    // only allow files of specific MIME types
    ->setAllowedMimeTypes(['image/jpeg'])

    // only allow files of specific extensions
    ->setAllowedExtensions(['jpg', 'jpeg'])

    // only allow files of specific aggregate types
    ->setAllowedAggregateTypes(['image'])

    // ensure that the file contents match a provided hash
    // second argument is the hash algorithm to use
    // supports any algorithm supported by PHP's hash() function
    ->validateHash('3ef5e70366086147c2695325d79a25cc', 'md5')
    ->validateHash('5e96e1fa58067853219c4cb6d3c1ce01cc5cc8ce', 'sha1')

    ->upload();
```

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

### Eager load media using with() or withMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Use the with() method or the withMedia() alias to eager load the media relationship and avoid the N+1 problem.

```php
<?php
$posts = Post::with('media')->get();
// or
$posts = Post::withMedia()->get();
```

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

### Copy media with copyTo() and copyToDisk()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Duplicates a media file to a new location, creating a new Media record. If no filename is given, the original filename is used.

```php
<?php
$newMedia = $media->copyTo('new/directory');
$newMedia = $media->copyTo('new/directory', 'new-filename');
$newMedia = $media->copyToDisk('uploads', 'new/directory', 'new-filename');
```

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

### moveToDisk($disk, $directory, $filename = null, $options = [])

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Moves the media file to a different disk and directory, optionally renaming it.

```APIDOC
## moveToDisk($disk, $directory, $filename = null, $options = [])

### Description
Moves the media file to a different disk and directory, optionally renaming it.

### Method
`moveToDisk($disk, $directory, $filename = null, $options = [])`

### Parameters
- **$disk** (string) - Required - The destination disk name.
- **$directory** (string) - Required - The destination directory.
- **$filename** (string|null) - Optional - The new filename without extension.
- **$options** (array) - Optional - Additional flags to pass to the underlying filesystem adapter.

### Return Value
- **void** - No return value.

### Example
```php
$media->moveToDisk('uploads', 'new/directory', 'new-filename');
```
```

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

### Add Data URL source adapter to config/mediable.php

Source: https://github.com/plank/laravel-mediable/blob/master/UPGRADING.md

Add this entry to the `source_adapters.pattern` field in `config/mediable.php` to enable support for data URLs in the MediaUploader.

```php
'^data:/?/?[^,]*,' => Plank\Mediable\SourceAdapters\DataUrlAdapter::class,
```

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

### Retrieve media by tag with getMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Returns a collection of all media assigned to the specified tag.

```php
<?php
$media = $post->getMedia('thumbnail');
```

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

### Set media visibility with makePublic() and makePrivate()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Updates the visibility of a Media record's file to public or private.

```php
<?php
$media->makePublic();
$media->makePrivate();
```

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

### copyToDisk($disk, $directory, $filename = null, $options = [])

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Duplicates the media file to a different disk and directory, creating a new Media record.

```APIDOC
## copyToDisk($disk, $directory, $filename = null, $options = [])

### Description
Duplicates the media file to a different disk and directory, creating a new Media record.

### Method
`copyToDisk($disk, $directory, $filename = null, $options = [])`

### Parameters
- **$disk** (string) - Required - The destination disk name.
- **$directory** (string) - Required - The destination directory.
- **$filename** (string|null) - Optional - The new filename without extension.
- **$options** (array) - Optional - Additional flags to pass to the underlying filesystem adapter.

### Return Value
- **Media** - The new Media record.

### Example
```php
$newMedia = $media->copyToDisk('uploads', 'new/directory', 'new-filename');
```
```

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

### move($directory, $filename = null)

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Moves the media file to a new directory and optionally renames it.

```APIDOC
## move($directory, $filename = null)

### Description
Moves the media file to a new directory and optionally renames it.

### Method
`move($directory, $filename = null)`

### Parameters
- **$directory** (string) - Required - The destination directory.
- **$filename** (string|null) - Optional - The new filename without extension.

### Return Value
- **void** - No return value.

### Example
```php
$media->move('new/directory');
$media->move('new/directory', 'new-filename');
```
```

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

### Generate public URL with getUrl()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Generates a URL for a Media record on a public disk with public visibility. Throws an exception if the file or disk is private.

```php
$media->getUrl();
// http://localhost/uploads/foo/bar/picture.jpg
```

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

### copyTo($directory, $filename = null)

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Duplicates the media file to a new directory and creates a new Media record.

```APIDOC
## copyTo($directory, $filename = null)

### Description
Duplicates the media file to a new directory and creates a new Media record. If a filename is not provided, the new file will copy the original filename.

### Method
`copyTo($directory, $filename = null)`

### Parameters
- **$directory** (string) - Required - The destination directory.
- **$filename** (string|null) - Optional - The new filename without extension.

### Return Value
- **Media** - The new Media record.

### Example
```php
$newMedia = $media->copyTo('new/directory');
$newMedia = $media->copyTo('new/directory', 'new-filename');
```
```

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

### Upload file to destination with MediaUploader

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/installation.rst

Upload a file from a request and convert it into a Media record, storing it in the specified disk and directory.

```php
<?php
$media = MediaUploader::fromSource($request->file('thumbnail'))
    ->toDestination('s3', 'posts/thumbnails')
    ->upload();
```

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

### Set output destination and filename

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Customizes the output disk, directory, and filename for variants. Includes shorthand toDestination() and filename options like useHashForFilename() with default md5.

```php
<?php
$manipulation->toDisk('uploads');
$manipulation->toDirectory('files/variants');

// shorthand for the above
$manipulation->toDestination('uploads', 'files/variants');

$manipulation->useFilename('my-custom-filename');
$manipulation->useHashForFilename(); // defaults to md5
$manipulation->useHashForFilename('sha1');
$manipulation->useOriginalFilename(); //restore default behaviour
```

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

### Lazy eager load media by specific tags using loadMedia() and loadMediaMatchAll()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Load only media attached to specific tags on an already loaded collection. loadMedia() loads media attached to either tag, while loadMediaMatchAll() loads media attached to both tags.

```php
<?php
$posts->loadMedia(['thumbnail', 'featured']); // attached to either tag
$posts->loadMediaMatchAll(['thumbnail', 'featured']); // attached to both tags
```

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

### Lazy eager load media using load() or loadMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

If models are already loaded, use the load() method or the loadMedia() alias to eager load the media relationship.

```php
<?php
$posts = Post::all();
// ...

$posts->load('media');
// or
$posts->loadMedia();
```

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

### MediaUploader::fromString

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Imports string file data and uploads it to a destination.

```APIDOC
## MediaUploader::fromString

### Description
Imports string file data and uploads it to a destination.

### Method
fromString

### Parameters
- **$data** (string) - Required - The string file data.

### Return Value
Returns a builder instance that supports chaining methods like `toDestination()` and `upload()`.

### Example
php
$jpg = Image::make('https://www.plankdesign.com/externaluse/plank.png')->encode('jpg');

MediaUploader::fromString($jpg)
    ->toDestination(...)
    ->upload();

```

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

### Configure duplicate handling with onDuplicate* methods

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Configures how the uploader responds when a file with a matching name already exists. Options include incrementing, updating, replacing, replacing with variants, or throwing an error.

```php
<?php

// keep both, append incrementing counter to new file name
$uploader->onDuplicateIncrement();

// replace old file with new one, update existing Media record, maintain associations
$uploader->onDuplicateUpdate();

// replace old file and media record with new ones, break associations
$uploader->onDuplicateReplace();

// replace old file and media record with new ones, break associations
// will also delete any existing variants of the replaced media record
$uploader->onDuplicateReplaceWithVariants();

// cancel upload, throw an exception
$uploader->onDuplicateError();
```

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

### Create a single variant synchronously

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Creates a new file derived from applying the manipulation to the original, and a new Media record. This operation may be time-consuming for large files.

```php
<?php
use Plank\Mediable\Facades\ImageManipulator;

$variantMedia = ImageManipulator::createImageVariant($originalMedia, 'thumbnail');
```

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

### Retrieve media URL by tag

Source: https://github.com/plank/laravel-mediable/blob/master/README.md

Retrieves the first media attached with the 'thumbnail' tag and returns its URL.

```php
$post->getMedia('thumbnail')->first()->getUrl();
```

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

### Attach media to a model with a tag

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Attaches a single media item to a model under a specified tag. The tag is a string that defines the relationship.

```php
<?php
$post = Post::first();
$post->attachMedia($media, 'thumbnail');
```

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

### Set variant file visibility

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Use these methods to set the visibility of the variant file. By default, variants use the destination disk's default visibility. `matchOriginalVisibility()` copies the visibility of the original media file.

```php
<?php
$manipulation->makePrivate();
$manipulation->makePublic();
// to copy the visibility of the original media file
$manipulation->matchOriginalVisibility();
```

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

### Eager load media and variants

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Eager load media and variants from a collection of Mediable records or a single Mediable model to avoid N+1 queries. Includes methods for matching all tags.

```php
<?php
// eager load
$posts = Post::withMediaAndVariants($tags)->get();
$posts = Post::withMediaAndVariantsMatchAll($tags)->get();

// lazy eager load from a collection of Mediables
$posts->loadMediaAndVariants($tags);
$posts->loadMediaAndVariantsMatchAll($tags);

// lazy eager load from a single Mediable model
$post->loadMediaAndVariants($tags);
$post->loadMediaAndVariantsMatchAll($tags);
```

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

### Reorder media with syncMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Manipulate the collection and commit changes with syncMedia() to reorder or insert media for a tag.

```php
<?php
$media = $post->getMedia('gallery');
$media = $media->prepend($new_media);
$post->syncMedia($media, 'gallery');
```

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

### Add alt text with withAltAttribute()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Records alt text for the media record by calling the withAltAttribute() method.

```php
<?php
MediaUploader::fromSource(…)
    ->withAltAttribute(‘This is the alt text’)
    ->upload();
```

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

### makePublic()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Updates the visibility of the media file to public.

```APIDOC
## makePublic()

### Description
Updates the visibility of the media file to public.

### Method
`makePublic()`

### Parameters
None

### Return Value
- **void** - No return value.

### Example
```php
$media->makePublic();
```
```

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

### Lazy eager load media on a model instance using loadMedia()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

The loadMedia() method is available on model instances via the Mediable trait. Use it to load media attached to either tag or both tags.

```php
<?php
$post = Post::first();
$post->loadMedia();
$post->loadMedia(['thumbnail', 'featured']); // attached to either tag
$post->loadMediaMatchAll(['thumbnail', 'featured']); // attached to both tags
```

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

### onDuplicateReplace

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Configures the uploader to replace the old file and media record with new ones, breaking associations.

```APIDOC
## onDuplicateReplace

### Description
Configures the uploader to replace the old file and media record with new ones, breaking associations.

### Method
onDuplicateReplace

### Example
```php
$uploader->onDuplicateReplace();
```
```

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

### Authorize disks in config/mediable.php

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/configuration.rst

Sets the default disk to 'uploads' and lists the allowed disks ('local' and 'uploads') for media storage. This configuration is required after defining the disks in filesystems.php.

```php
<?php
//...
/*
 * Filesystem disk to use if none is specified
 */
'default_disk' => 'uploads',

/*
 * Filesystems that can be used for media storage
 */
'allowed_disks' => [
    'local',
    'uploads',
],
//...
```

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

### Set file visibility with makePrivate and makePublic

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Use MediaUploader::fromSource() to upload a file and control its public access. makePrivate() disables public access, while makePublic() is the default behavior.

```php
<?php
MediaUploader::fromSource($request->file('image'))
    ->makePrivate() // Disable public access
    ->makePublic() // Default behaviour
    ->upload()
```

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

### withAltAttribute

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Records alt text attribute for the media record.

```APIDOC
## withAltAttribute

### Description
Records alt text attribute for the media record.

### Method
withAltAttribute

### Parameters
- **altText** (string) - Required - The alt text to record.

### Example
```php
MediaUploader::fromSource(...)
    ->withAltAttribute('This is the alt text')
    ->upload();
```
```

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

### Attach media to model

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/installation.rst

Attach the uploaded media record to a model instance using the attachMedia method.

```php
<?php
$post = Post::find($postId);
$post->attachMedia($media, 'thumbnail');
```

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

### Configure image optimization

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Methods to enable or disable optimization for a manipulation. The optimize() method can accept an array of optimizer classes with arguments. Warning: never pass untrusted user input to optimizer arguments as they are executed as shell commands.

```php
<?php
// disable optimization for this manipulation
$manipulation->noOptimization();

// enable optimization for this manipulation
$manipulation->optimize();

// enable optimization but override the optimizers to be applied
$manipulation->optimize([Pngquant::class => ['--quality=65']]);
```

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

### Generate filename with hash using useHashForFilename()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Generates a filename using a hashing algorithm on the file's contents. Supports any algorithm supported by PHP's hash() function. Default is 'md5'.

```php
<?php
MediaUploader::fromSource(...)
    ->useHashForFilename() // default is 'md5'
    ->useHashForFilename('sha1')
    ->upload();
```

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

### onDuplicateReplaceWithVariants

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Configures the uploader to replace the old file and media record with new ones, breaking associations, and also delete any existing variants of the replaced media record.

```APIDOC
## onDuplicateReplaceWithVariants

### Description
Configures the uploader to replace the old file and media record with new ones, breaking associations, and also delete any existing variants of the replaced media record.

### Method
onDuplicateReplaceWithVariants

### Example
```php
$uploader->onDuplicateReplaceWithVariants();
```
```

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

### onDuplicateUpdate

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Configures the uploader to replace the old file with the new one, update the existing Media record, and maintain associations.

```APIDOC
## onDuplicateUpdate

### Description
Configures the uploader to replace the old file with the new one, update the existing Media record, and maintain associations.

### Method
onDuplicateUpdate

### Example
```php
$uploader->onDuplicateUpdate();
```
```

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

### Configure media upload validation in config/mediable.php

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/configuration.rst

Provides default validation settings for media uploads, including max file size, duplicate handling, strict type checking, MIME/extension restrictions, and remote URL validation. These defaults can be overridden per MediaUploader instance.

```php
<?php
//...
/*
 * The maximum file size in bytes for a single uploaded file
 */
'max_size' => 1024 * 1024 * 10,

/*
 * What to do if a duplicate file is uploaded. Options include:
 *
 * * 'increment': the new file's name is given an incrementing suffix
 * * 'replace' : the old file and media model is deleted
 * * 'error': an Exception is thrown
 *
 */
'on_duplicate' => Plank\Mediable\MediaUploader::ON_DUPLICATE_INCREMENT,

/*
 * Reject files unless both their mime and extension are recognized and both match a single aggregate type
 */
'strict_type_checking' => false,

/*
 * Reject files whose mime type or extension is not recognized
 * if true, files will be given a type of `'other'`
 */
'allow_unrecognized_types' => false,

/*
* Only allow files with specific MIME type(s) to be uploaded
* If blank, all MIME types will be allowed, unless it is forbidden by the `forbidden_mime_types` config
*/
allowed_mime_types' => [],

*
* Reject files with specific MIME types from being uploaded
*/
forbidden_mime_types' => [],

*
* Only allow files with specific file extension(s) to be uploaded
* If blank, all file extensions will be allowed, unless it is forbidden by the `forbidden_extensions` config
*/
allowed_extensions' => [],

*
* Reject files with specific file extensions from being uploaded
* This is intended to be used as a security measure to prevent potentially executable files from being uploaded, even if they are disguised with an allowed MIME type
* This list should include any file extension which is configured to be executable from your Apache or Nginx configuration
*
* This is verified both on the source file and the intended destination filename
*/
forbidden_extensions' => [
   'php',
   // ...
,

/*
* Only allow remote files to be imported from specific host(s)
* If empty, will allow any host that is not a private IP address or localhost
*/
'allowed_remote_hosts' => [],

*
* Only allow remote files to be imported from URLs with specific scheme(s)
* If empty, will allow any scheme supported by the application.
* If modifying this value, be sure to also update the pattern matching in `source_adapters` as well
*/
'allowed_remote_schemes' => ['https'],

/*
 * Whether allowed_remote_hosts, allowed_remote_schemes, and private IP address
 * validation should be applied to each step of a redirect chain
 */
'validate_remote_url_redirects' => true,

/*
 * Maximum number of redirects permitted for remote URLs
 * Only applied if validate_remote_url_redirects is enabled
 */
'max_remote_url_redirects' => 5,

/*
 * Only allow files matching specific aggregate type(s) to be uploaded
 */
'allowed_aggregate_types' => [],
//...
```

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

### getUrl()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Generates a public URL for the media file. Throws an exception if the file or disk is private.

```APIDOC
## getUrl()

### Description
Generates a public URL for the media file. Throws an exception if the file or disk is private.

### Method
`getUrl()`

### Parameters
None

### Return Value
- **string** - The public URL, e.g., `http://localhost/uploads/foo/bar/picture.jpg`

### Exceptions
- Throws an exception if the file or its disk has private visibility.

### Example
```php
$media->getUrl();
// http://localhost/uploads/foo/bar/picture.jpg
```
```

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

### Media::inOrUnderDirectory($disk, $directory)

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Query media records that are in a directory or any subdirectory on a given disk.

```APIDOC
## Media::inOrUnderDirectory($disk, $directory)

### Description
Query media records that are in a directory or any subdirectory on a given disk.

### Method
`Media::inOrUnderDirectory($disk, $directory)`

### Parameters
- **$disk** (string) - Required - The disk name.
- **$directory** (string) - Required - The directory path.

### Return Value
- **Builder** - A query builder instance.

### Example
```php
Media::inOrUnderDirectory('uploads', 'foo');
```
```

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

### Media::whereBasename($basename)

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Query media records by their basename (filename with extension).

```APIDOC
## Media::whereBasename($basename)

### Description
Query media records by their basename (filename with extension).

### Method
`Media::whereBasename($basename)`

### Parameters
- **$basename** (string) - Required - The basename, e.g., `picture.jpg`.

### Return Value
- **Builder** - A query builder instance.

### Example
```php
Media::whereBasename('picture.jpg');
```
```

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

### getMedia

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Retrieves a collection of media attached to a model by tag. Accepts a single tag or an array of tags, with an optional $match_all parameter to require all tags.

```APIDOC
## getMedia

### Description
Retrieves a collection of media attached to a model by tag. Accepts a single tag or an array of tags, with an optional $match_all parameter to require all tags.

### Method
PHP method

### Signature
`getMedia($tags, $match_all = false)`

### Parameters
- **$tags** (string|array) - Required - The tag or array of tags to filter media by.
- **$match_all** (bool) - Optional - If true, only return media attached to all specified tags. Defaults to false.

### Example
```php
$media = $post->getMedia('thumbnail');
$post->getMedia(['header', 'footer']); // get media with either tag
$post->getMedia(['header', 'footer'], true); //get media with both tags
```

### Returns
Collection of Media entities.
```

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

### stream()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Returns a stream resource for reading the media file content.

```APIDOC
## stream()

### Description
Returns a stream resource for reading the media file content, useful for streaming downloads.

### Method
`stream()`

### Parameters
None

### Return Value
- **resource** - A stream resource that can be read.

### Example
```php
$stream = $media->stream();
while($bytes = $stream->read(1024)) {
    echo $bytes;
}
```
```

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

### Add prefer_client_mime_type config to config/mediable.php

Source: https://github.com/plank/laravel-mediable/blob/master/UPGRADING.md

Add this entry to `config/mediable.php` to control whether the client-provided MIME type is used when available. Defaults to `false`, meaning the MIME type is always inferred from file contents.

```php
'prefer_client_mime_type' => false,
```

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

### Attach media to multiple tags

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Assigns a single media item to multiple tags in one call by passing an array of tags as the second argument.

```php
<?php
$post->attachMedia($media, ['gallery', 'featured']);
```

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

### Queue variant creation with CreateImageVariants job

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Use the `CreateImageVariants` job to process variant creation asynchronously. It accepts a single Media or a Collection of Media records and one or more variant names. The first call produces one variant; the second produces four variants (two per media).

```php
<?php
use Plank\Mediable\Jobs\CreateImageVariants;
use Illuminate\Database\Eloquent\Collection;

// will produce one variant
CreateImageVariants::dispatch($media, ['square']);

// will produce 4 variants (2 of each media)
CreateImageVariants::dispatch(
    new Collection([$media1, $media2]),
    ['square', 'bw-square']
);
```

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

### Promote a variant to original

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Makes a variant an original, clearing its variant name and detaching it from its former variant family.

```php
<?php
$variant->makeOriginal()->save();
```

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

### Navigate between variants

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Methods to find the original, a specific variant, or check if a variant exists. If the requested variant is the current one, it returns itself.

```php
<?php
$original = $media->findOriginal();
$variant = $media->findVariant('thumbnail');
$bool = $media->hasVariant('thumbnail');
```

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

### Bind Intervention/image driver (>=3.0) in AppServiceProvider

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/variants.rst

Manually bind the Intervention\Image\Interfaces\DriverInterface to either the GD or Imagick driver in a service provider. Use this when not using the recommended intervention/image-laravel package. Only one binding should be active; the commented lines show the alternative driver.

```php
<?php
class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        // if using GD
        $app->bind(Intervention\Image\Interfaces\DriverInterface::class,
            \Intervention\Image\Drivers\Gd\Driver::class
        );

        // if using Imagick
        $app->bind(Intervention\Image\Interfaces\DriverInterface::class,
            \Intervention\Image\Drivers\Imagick\Driver::class
        );
    }
}
```

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

### getAllMediaByTag

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/mediable.rst

Retrieves all media attached to a model, grouped by tag.

```APIDOC
## getAllMediaByTag

### Description
Retrieves all media attached to a model, grouped by tag.

### Method
PHP method

### Signature
`getAllMediaByTag()`

### Example
```php
$post->getAllMediaByTag();
```

### Returns
Collection of media grouped by tag.
```

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

### MediaUploader::fromSource()->makePublic()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/uploader.rst

Sets the uploaded file to public, which is the default behavior.

```APIDOC
## MediaUploader::fromSource()->makePublic()

### Description
Sets the uploaded file to public, which is the default behavior.

### Method
makePublic

### Parameters
None

### Request Example
```php
<?php
MediaUploader::fromSource($request->file('image'))
    ->makePublic() // Default behaviour
    ->upload()
```

### Response
No return value documented.
```

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

### Stream private file download with response()->streamDownload()

Source: https://github.com/plank/laravel-mediable/blob/master/docs/source/media.rst

Streams a private file to authorized users by reading and echoing the stream in chunks. Sets Content-Type and Content-Length headers.

```php
<?php
return response()->streamDownload(
    function() use ($media) {
        $stream = $media->stream();
        while($bytes = $stream->read(1024)) {
            echo $bytes;
        }
    },
    $media->basename,
    [
        'Content-Type' => $media->mime_type,
        'Content-Length' => $media->size
    ]
);
```
Tokens:
Raw