Laravel Advanced Nova Media Library

https://github.com/ebess/advanced-nova-media-library
Admin
An extension for Laravel Nova that integrates Spatie's Media Library, enabling advanced media...
Tokens:47,439
Snippets:367
Trust Score:8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install package via Composer

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Run this command to install the advanced-nova-media-library package via Composer.

```bash
composer require ebess/advanced-nova-media-library
```

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

### Configure media conversions and collections on a model

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Example methods to add to a model using Spatie Media Library. Defines a 'thumb' conversion (130x130) and a single-file 'main' collection plus a multi-file 'my_multi_collection'.

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

public function registerMediaConversions(Media $media = null): void
{
    $this->addMediaConversion('thumb')
        ->width(130)
        ->height(130);
}

public function registerMediaCollections(): void
{
    $this->addMediaCollection('main')->singleFile();
    $this->addMediaCollection('my_multi_collection');
}
```

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

### Media::make with conversionOnIndexView and conversionOnDetailView

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/traits.md

Example usage of the conversion configuration methods on a Media field.

```php
Media::make('Images', 'main')
    ->conversionOnIndexView('thumb')
    ->conversionOnDetailView('medium-size');
```

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

### Usage example for customProperties with dynamic value

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/traits.md

Shows how to set static custom properties on a Files field. The provided key-value map is applied to every newly added media item.

```php
Files::make('Multiple files', 'multiple_files')
    ->customProperties(['foo' => auth()->user()->foo]);
```

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

### croppingConfigs usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/images.md

Example of enforcing a 4:3 crop ratio using croppingConfigs.

```php
Images::make('Gallery')
    ->croppingConfigs(['aspectRatio' => 4 / 3]); // enforced crop ratio 4:3
```

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

### showDimensions usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/images.md

Example of using the showDimensions alias to show dimensions.

```php
Images::make('Gallery')->showDimensions();
```

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

### MediaResource response item JSON example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/http.md

Shows the structure of each item in the paginated response, including the '__media_urls__' object with conversion URLs.

```json
{
  "id": 8,
  "name": "sunset",
  "file_name": "sunset.jpg",
  "mime_type": "image/jpeg",
  "collection_name": "gallery",
  "uuid": "8c8e5d67-...",
  "custom_properties": {},
  "__media_urls__": {
    "__original__": "https://…",
    "indexView": "https://…",
    "detailView": "https://…",
    "form": "https://…",
    "preview": "https://…"
  }
}
```

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

### showStatistics usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/images.md

Example of enabling statistics display on an images field.

```php
Images::make('Gallery')->showStatistics();
```

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

### GET /nova-vendor/ebess/advanced-nova-media-library/media

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/endpoints.md

Retrieves a paginated list of media items for the existing-media search modal. Supports optional search text, pagination, and respects hidden collections and feature configuration.

```APIDOC
## [GET] /nova-vendor/ebess/advanced-nova-media-library/media

### Description
Retrieves a paginated list of media items for the existing-media search modal. Supports optional search text, pagination, and respects hidden collections and feature configuration.

### Method
GET

### Endpoint
/nova-vendor/ebess/advanced-nova-media-library/media

### Parameters
#### Query Parameters
- **search_text** (string) - Optional - Search term matched against `name` and `file_name` (LIKE) or via the media model's Scout `search()` method.
- **page** (numeric) - Optional - Pagination page. Default: 1.
- **per_page** (numeric) - Optional - Items per page. Default: 18.

### Request Example
GET /nova-vendor/ebess/advanced-nova-media-library/media?search_text=sunset&page=1&per_page=18

### Response
#### Success Response (200)
- **data** (array) - List of media resources.
- **links** (object) - Pagination links.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "data": [
    {
      "id": 8,
      "model_type": "App\\Models\\Post",
      "model_id": 12,
      "collection_name": "gallery",
      "name": "sunset",
      "file_name": "sunset.jpg",
      "mime_type": "image/jpeg",
      "disk": "public",
      "size": 48213,
      "manipulations": [],
      "custom_properties": {},
      "responsive_images": [],
      "order_column": 1,
      "created_at": "2024-01-01T12:00:00.000000Z",
      "updated_at": "2024-01-01T12:00:00.000000Z",
      "uuid": "8c8e5d67-8e5d-4c94-8e5d-8c8e5d67abcd",
      "__media_urls__": {
        "__original__": "https://…/sunset.jpg",
        "indexView": "https://…/sunset.jpg",
        "detailView": "https://…/sunset.jpg",
        "form": "https://…/sunset.jpg",
        "preview": "https://…/sunset.jpg"
      }
    }
  ],
  "links": { "first": "…", "last": "…", "prev": null, "next": "…" },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "links": [ "…" ],
    "path": "/nova-vendor/ebess/advanced-nova-media-library/media",
    "per_page": 18,
    "to": 18,
    "total": 180
  }
}

### Error Responses
- **422** - Validation failure of `search_text`/`page`/`per_page`.
- **500** - `enable-existing-media` config is false (generic `Exception` thrown).
```

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

### mustCrop usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/images.md

Example of forcing a 4:3 aspect ratio on every image using mustCrop and croppingConfigs.

```php
Images::make('Gallery')
    ->mustCrop()
    ->croppingConfigs(['aspectRatio' => 4 / 3]);
```

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

### setName() usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Sets a callback that returns an MD5 hash of the original filename as the media name. The callback receives the original filename and the model.

```php
Media::make('Image', 'img1')
    ->setName(function ($originalFilename, $model) {
        return md5($originalFilename);
    });
```

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

### Set filename to MD5 hash using setFileName

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Use setFileName to override the default original filename. The callback receives $originalFilename, $extension, and $model, and returns the new filename. This example returns the MD5 hash of the original filename with its extension.

```php
// Set the filename to the MD5 Hash of original filename
Images::make('Image 1', 'img1')
    ->setFileName(function($originalFilename, $extension, $model){
        return md5($originalFilename) . '.' . $extension;
    });
```

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

### Route prefix for AdvancedNovaMediaLibrary

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/endpoints.md

The route prefix under which the package's GET routes are mounted, beneath the 'nova' middleware group.

```text
nova-vendor/ebess/advanced-nova-media-library
```

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

### setFileName() usage example with error handling

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Sets a callback that throws a RuntimeException when the model has no name, otherwise returns a slugified filename with the extension. The callback receives the original filename, the extension, and the model.

```php
Media::make('Image', 'img1')
    ->setFileName(function ($originalFilename, $extension, $model) {
        if (! $model->name) {
            throw new RuntimeException('Cannot derive file name: the model has no name.');
        }

        return str_slug($model->name) . '.' . $extension;
    });
```

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

### GET /nova-vendor/ebess/advanced-nova-media-library/download/{media}

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/http.md

Downloads or retrieves a media item by its ID, requiring a matching UUID query parameter for authorization. Returns the media model as JSON.

```APIDOC
## [GET] /nova-vendor/ebess/advanced-nova-media-library/download/{media}

### Description
Downloads or retrieves a media item by its ID, requiring a matching UUID query parameter for authorization. Returns the media model as JSON.

### Method
GET

### Endpoint
/nova-vendor/ebess/advanced-nova-media-library/download/{media}

### Parameters
#### Path Parameters
- **media** (numeric) - Required - The media ID.

#### Query Parameters
- **uuid** (string) - Required - The media UUID; must match the item's UUID or a 403 error is returned.

### Response
#### Success Response (200)
- Returns the serialized Media model as JSON.

#### Response Example
```json
{
  "id": 1,
  "uuid": "...",
  "model_type": "...",
  "model_id": 1,
  "collection_name": "...",
  "name": "...",
  "file_name": "...",
  "mime_type": "...",
  "disk": "...",
  "size": 12345,
  "manipulations": [],
  "custom_properties": [],
  "responsive_images": [],
  "order_column": 1,
  "created_at": "...",
  "updated_at": "..."
}
```

### Error Handling
- **403** - When the `uuid` query parameter is missing or does not match the media item's UUID.
- **500** - When the media ID does not exist (not explicitly handled).
```

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

### uploadsToVapor() usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Enables Vapor-upload mode for the field. The frontend will upload files client-side via Vapor.store() and send upload metadata instead of binary data.

```php
Media::make('Gallery')->uploadsToVapor();
```

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

### temporary() usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Sets a temporary URL expiry of 5 minutes from now. Requires importing Illuminate\Support\Carbon. The field will generate temporary signed URLs for all media.

```php
use Illuminate\Support\Carbon;

Media::make('Image', 'img1')
    ->temporary(Carbon::now()->addMinutes(5));
```

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

### setMaxFileSize() usage example with server-side limit

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Sets a client-side maximum file size of 5 MB and a matching server-side rule of max:5120 kilobytes. The client-side check rejects files before upload; the server-side rule enforces the limit on the server.

```php
Media::make('Document')
    ->setMaxFileSize(5120) // client-side: 5 MB
    ->singleMediaRules('max:5120'); // server-side: 5 MB
```

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

### Usage example for customPropertiesFields with Boolean and Markdown fields

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/traits.md

Shows how to attach custom property fields to an Images field. The fields are rendered in the 'Edit custom properties' modal and values are stored under custom_properties-><attribute>.

```php
Images::make('Gallery')
    ->customPropertiesFields([
        Boolean::make('Active'),
        Markdown::make('Description'),
    ]);
```

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

### boot() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/service-provider.md

Public boot method that registers package infrastructure including config publishing, deferred routes, translations, and Nova serving callback.

```php
public function boot()
```

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

### Publish package assets

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Run this command to publish the package's assets (e.g., configuration, views) using the nova-media-library tag.

```bash
php artisan vendor:publish --tag=nova-media-library
```

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

### croppable usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/images.md

Example of disabling the crop UI on an images field.

```php
Images::make('Gallery')->croppable(false);
```

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

### Publish config files for existing media feature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Publishes the package configuration files if not already done. Run this command before enabling the existing media feature.

```bash
artisan vendor:publish --tag=nova-media-library
```

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

### withResponsiveImages($responsive = true)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Enables responsive image generation on new uploads by calling FileAdder::withResponsiveImages().

```APIDOC
## withResponsiveImages($responsive = true)

### Description
Enables responsive image generation on new uploads by calling FileAdder::withResponsiveImages().

### Method
builder method

### Parameters
- **$responsive** (bool) - Optional - Default: `true` - Whether to enable responsive images.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Banner')->withResponsiveImages()
```
```

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

### singleImageRules usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/images.md

Example of using singleImageRules to set per-image validation rules, such as minimum width.

```php
Images::make('Gallery', 'my_multi_collection')
    ->singleImageRules(['dimensions:min_width=100']);
```

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

### bootTranslations() implementation

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/service-provider.md

Reads the current locale and registers both package and override JSON translation files with Nova.

```php
$locale = $this->app->getLocale();
Nova::translations(__DIR__ . "/../resources/lang/{$locale}.json");
Nova::translations(lang_path("vendor/advanced-nova-media-library/$locale.json"));
```

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

### Enable responsive images with withResponsiveImages

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Call withResponsiveImages() on the model to enable Spatie MediaLibrary responsive image functionality.

```php
Images::make('Image 1', 'img1')
    ->withResponsiveImages();
```

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

### bootTranslations() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/service-provider.md

Protected method that registers package and application override translation files with Nova.

```php
protected function bootTranslations()
```

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

### Media::make()->conversionOnIndexView()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Specifies the media conversion to use for the index view. This method is called on a Media field instance.

```APIDOC
## Media::make()->conversionOnIndexView()

### Description
Specifies the media conversion to use for the index view.

### Method
`conversionOnIndexView(string $conversion)`

### Parameters
- **$conversion** (string) - Required - The name of the media conversion to use.

### Return Value
Returns the field instance for chaining.

### Example
```php
Media::make('Gallery')
    ->conversionOnIndexView('thumb');
```
```

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

### Route definitions in routes/api.php

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/endpoints.md

The two GET routes registered by the package, defined in routes/api.php lines 7-9. Both are consumed exclusively by the package's own frontend components.

```php
Route::get('/download/{media}', [DownloadMediaController::class, 'show']);
Route::get('/media', [MediaController::class, 'index']);
```

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

### Enable existing media feature in config

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Configuration file config/nova-media-library must set 'enable-existing-media' to true to allow selecting existing media. This exposes a search endpoint to all users; do not enable if media is confidential.

```php
return [
    'enable-existing-media' => true,
];
```

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

### enableExistingMedia()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Shows the search modal button to pick existing media. Only active when config 'enable-existing-media' is true.

```APIDOC
## enableExistingMedia()

### Description
Shows the search modal button to pick existing media. Only active when config 'enable-existing-media' is true.

### Method
builder method

### Parameters
None

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Gallery')->enableExistingMedia()
```
```

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

### showStatistics(bool) / showDimensions(bool)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Shows size, dimensions, ratio, MIME under each item.

```APIDOC
## showStatistics(bool) / showDimensions(bool)

### Description
Shows size, dimensions, ratio, MIME under each item.

### Method
builder method

### Parameters
- **bool** (bool) - Optional - Default: `false` - Whether to show statistics/dimensions.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photo')->showStatistics()
```
```

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

### conversionOnPreview(string)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets the conversion used when opening the preview.

```APIDOC
## conversionOnPreview(string)

### Description
Sets the conversion used when opening the preview.

### Method
builder method

### Parameters
- **string** (string) - Required - Conversion name.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photo')->conversionOnPreview('zoom')
```
```

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

### DownloadMediaController show method

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/http.md

Handles download requests, validates UUID, and returns the media model. Aborts with 403 on UUID mismatch.

```php
class DownloadMediaController extends Controller
{
    public function show($mediaId)
    {
        $model = config('media-library.media_model') ?: Media;
        $file = $model::find($mediaId);

        abort_unless($file->uuid === request()->get('uuid'), 403);

        return $file;
    }
}
```

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

### withResponsiveImages

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Enables responsive image functionality from the Spatie MediaLibrary on the model.

```APIDOC
## withResponsiveImages

### Description
Enables responsive image functionality from the Spatie MediaLibrary on the model.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
Images::make('Image 1', 'img1')
    ->withResponsiveImages();
```

### Response
#### Success Response
Returns the modified field instance to allow chaining.

#### Response Example
N/A
```

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

### conversionOnIndexView(string)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets the conversion used on the index view.

```APIDOC
## conversionOnIndexView(string)

### Description
Sets the conversion used on the index view.

### Method
builder method

### Parameters
- **string** (string) - Required - Conversion name.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photo')->conversionOnIndexView('thumb')
```
```

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

### setMaxFileSize(int $maxSize)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets the maximum file size in kilobytes for client-side rejection. Needs matching server rule.

```APIDOC
## setMaxFileSize(int $maxSize)

### Description
Sets the maximum file size in kilobytes for client-side rejection. Needs matching server rule.

### Method
builder method

### Parameters
- **$maxSize** (int) - Required - Maximum file size in kB.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('File')->setMaxFileSize(2048)
```
```

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

### setAllowedFileTypes() usage example

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Restricts uploads to video files by setting the allowed file types to ['video']. The frontend validates the file type before upload using the MIME type prefix.

```php
Media::make('Video', 'video')
    ->setAllowedFileTypes(['video']);
```

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

### fullSize()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Renders the field full width on the form.

```APIDOC
## fullSize()

### Description
Renders the field full width on the form.

### Method
builder method

### Parameters
None

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Banner')->fullSize()
```
```

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

### routes() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/service-provider.md

Protected method that registers API routes unless routes are cached. Uses Nova middleware and a custom prefix.

```php
protected function routes()
```

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

### customProperties(array $keyValue)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Writes a key/value map onto every newly added media item.

```APIDOC
## customProperties(array $keyValue)

### Description
Writes a key/value map onto every newly added media item.

### Method
builder method

### Parameters
- **$keyValue** (array) - Required - Associative array of custom properties.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('File')->customProperties(['author' => 'Admin'])
```
```

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

### conversionOnDetailView(string)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets the conversion used on the detail view.

```APIDOC
## conversionOnDetailView(string)

### Description
Sets the conversion used on the detail view.

### Method
builder method

### Parameters
- **string** (string) - Required - Conversion name.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photo')->conversionOnDetailView('large')
```
```

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

### Configure multiple image upload with Images field

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Enables multiple image upload with drag-and-drop ordering. The second parameter sets the media collection name. Use conversionOnPreview, conversionOnDetailView, conversionOnIndexView, and conversionOnForm to specify conversions for different views. fullSize() makes the column full width. rules() applies validation to the collection, and singleImageRules() applies validation to each individual image.

```php
use Ebess\AdvancedNovaMediaLibrary\Fields\Images;

public function fields(Request $request)
{
    return [
        Images::make('Images', 'my_multi_collection') // second parameter is the media collection name
            ->conversionOnPreview('medium-size') // conversion used to display the "original" image
            ->conversionOnDetailView('thumb') // conversion used on the model's view
            ->conversionOnIndexView('thumb') // conversion used to display the image on the model's index page
            ->conversionOnForm('thumb') // conversion used to display the image on the model's form
            ->fullSize() // full size column
            ->rules('required', 'size:3') // validation rules for the collection of images
            // validation rules for the collection of images
            ->singleImageRules('dimensions:min_width=100'),
    ];
}
```

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

### Default configuration file content

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

The published config file returns an array with three keys: default-croppable (bool, default true), enable-existing-media (bool, default false), and hide-media-collections (array, default empty). These control cropper availability, the existing-media feature, and collection filtering respectively.

```php
return [
    'default-croppable' => true,
    'enable-existing-media' => false,
    'hide-media-collections' => [],
];
```

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

### Images::make()->showStatistics()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Enables the display of image statistics (size, dimensions, type) for the media field. This method is called on an Images field instance.

```APIDOC
## Images::make()->showStatistics()

### Description
Enables the display of image statistics (size, dimensions, type) for the media field.

### Method
`showStatistics()`

### Parameters
None

### Return Value
Returns the field instance for chaining.

### Example
```php
Images::make('Gallery')
    ->showStatistics();
```
```

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

### temporary(Carbon $until)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Makes all frontend URLs signed URLs expiring at the given time. Incompatible with existing media.

```APIDOC
## temporary(Carbon $until)

### Description
Makes all frontend URLs signed URLs expiring at the given time. Incompatible with existing media.

### Method
builder method

### Parameters
- **$until** (Illuminate\Support\Carbon) - Required - Expiration time for signed URLs.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Private')->temporary(now()->addDay())
```
```

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

### serializeMediaUsing(callable)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets a custom serialization callback for each media item. The callback receives a Media instance and returns an array.

```APIDOC
## serializeMediaUsing(callable)

### Description
Sets a custom serialization callback for each media item. The callback receives a Media instance and returns an array.

### Method
builder method

### Parameters
- **callable** (callable) - Required - Callback signature: `(Media $media): array`.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Gallery')->serializeMediaUsing(fn($media) => ['id' => $media->id])
```
```

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

### Enable existing media selection on Images field

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Adds the enableExistingMedia() method to the Images field to allow selecting existing media. Selecting an existing media copies it. This feature does not support temporary URLs.

```php
Images::make('Image')->enableExistingMedia(),
```

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

### enableExistingMedia() implementation

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/traits.md

Full implementation of enableExistingMedia(). Returns the current instance with the 'existingMedia' meta flag set to the boolean value of the 'nova-media-library.enable-existing-media' config. The frontend shows the 'Add Existing Media' button when enabled. Security note: exposes the search endpoint to all users; do not enable if media/custom properties are confidential. Does not support temporary URLs (secureUntil).

```php
public function enableExistingMedia(): self
{
    return $this->withMeta(['existingMedia' => (bool) config('nova-media-library.enable-existing-media')]);
}
```

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

### Disable cropping by default in config/nova-media-library.php

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Sets the default-croppable configuration to false, disabling cropping for all images by default. Place this in the config/nova-media-library.php file.

```php
return [
    'default-croppable' => false,
];
```

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

### rules($rules)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets validation rules for the entire media collection on save. Accepts a string, Rule instance, or array of rules.

```APIDOC
## rules($rules)

### Description
Sets validation rules for the entire media collection on save. Accepts a string, Rule instance, or array of rules.

### Method
builder method

### Parameters
- **$rules** (string | Rule | array) - Required - Validation rules for the collection.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Gallery')->rules('required|array')
```
```

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

### Set cropping configuration with croppingConfigs

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Sets cropping configuration options, such as aspectRatio, for the vue-js-clipper component. Available configurations are listed in the vue-js-clipper documentation.

```php
Images::make('Gallery')->croppingConfigs(['aspectRatio' => 4/3]);
```

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

### serializeMediaUsing basic use

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

The callback receives the Media model and must return an array, which is merged with a __media_urls__ key in resolve().

```php
Media::make('Video', 'video')
    ->serializeMediaUsing(function ($media) {
        return [
            'id' => $media->id,
            'custom' => ['view_count' => $media->getCustomProperty('views')],
        ];
    });
```

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

### uploadsToVapor(bool $uploadsToVapor = true)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Enables client-side upload via Vapor.store() and server re-imports from S3.

```APIDOC
## uploadsToVapor(bool $uploadsToVapor = true)

### Description
Enables client-side upload via Vapor.store() and server re-imports from S3.

### Method
builder method

### Parameters
- **$uploadsToVapor** (bool) - Optional - Default: `true` - Whether to enable Vapor uploads.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Video')->uploadsToVapor()
```
```

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

### setName($callback)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets a custom callback to generate the Media 'name' attribute. The callback receives the original filename and model.

```APIDOC
## setName($callback)

### Description
Sets a custom callback to generate the Media 'name' attribute. The callback receives the original filename and model.

### Method
builder method

### Parameters
- **$callback** (callable) - Required - Callback signature: `($originalFilename, $model)`.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Avatar')->setName(fn($name) => strtoupper($name))
```
```

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

### mustCrop(bool)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Forces the cropper on new uploads; only 'Update' (crop-and-save) is offered.

```APIDOC
## mustCrop(bool)

### Description
Forces the cropper on new uploads; only 'Update' (crop-and-save) is offered.

### Method
builder method

### Parameters
- **bool** (bool) - Optional - Default: `false` - Whether cropping is mandatory.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Avatar')->mustCrop()
```
```

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

### conversionOnForm(string)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets the conversion used on the edit form.

```APIDOC
## conversionOnForm(string)

### Description
Sets the conversion used on the edit form.

### Method
builder method

### Parameters
- **string** (string) - Required - Conversion name.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photo')->conversionOnForm('preview')
```
```

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

### croppingConfigs(array)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets vue-advanced-cropper stencil-props for crop configuration.

```APIDOC
## croppingConfigs(array)

### Description
Sets vue-advanced-cropper stencil-props for crop configuration.

### Method
builder method

### Parameters
- **array** (array) - Required - Configuration array, e.g., `['aspectRatio' => 4/3]`.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photo')->croppingConfigs(['aspectRatio' => 16/9])
```
```

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

### withResponsiveImages method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Enables or disables Spatie's responsive images for files added through this field.

```php
public function withResponsiveImages($responsive = true)
```

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

### Media::make()->singleMediaRules()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Sets validation rules for single media uploads. This method is called on a Media field instance.

```APIDOC
## Media::make()->singleMediaRules()

### Description
Sets validation rules for single media uploads.

### Method
`singleMediaRules(string $rules)`

### Parameters
- **$rules** (string) - Required - Validation rules string, e.g., 'max:5000'.

### Return Value
Returns the field instance for chaining.

### Example
```php
Media::make('Gallery')
    ->singleMediaRules('max:5000');
```
```

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

### Class declaration for AdvancedNovaMediaLibraryServiceProvider

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/service-provider.md

Declares the package service provider class extending Illuminate\Support\ServiceProvider. Located at src/AdvancedNovaMediaLibraryServiceProvider.php:10.

```php
class AdvancedNovaMediaLibraryServiceProvider extends ServiceProvider
```

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

### withResponsiveImages

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Enables (or disables) Spatie's responsive images for files added through this field. When truthy, `FileAdder::withResponsiveImages()` is called on every new upload. No declared return type; returns `$this`.

```APIDOC
## withResponsiveImages($responsive = true)

### Description
Enables (or disables) Spatie's responsive images for files added through this field. When truthy, `FileAdder::withResponsiveImages()` is called on every new upload. No declared return type; returns `$this`.

### Method
withResponsiveImages

### Signature
```php
public function withResponsiveImages($responsive = true)
```

### Parameters
- `$responsive` (bool) - Optional - Enable/disable responsive image generation (default: `true`)

### Returns
`$this` (fluent).

### Example
```php
Media::make('Hero')->withResponsiveImages();
```
```

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

### singleMediaRules($rules) / singleImageRules($rules)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets validation rules for each uploaded file. For Images, adds 'image' rule by default.

```APIDOC
## singleMediaRules($rules) / singleImageRules($rules)

### Description
Sets validation rules for each uploaded file. For Images, adds 'image' rule by default.

### Method
builder method

### Parameters
- **$rules** (string | Rule | array) - Required - Validation rules for each file.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Images::make('Photos')->singleImageRules('mimes:jpg,png')
```
```

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

### MediaRequest authorize() method

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/http.md

Always returns true; the actual authorization is enforced by the 'nova' route middleware group.

```php
public function authorize()
{
    return true;
}
```

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

### conversionOnPreview method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/traits.md

Declares the conversion used for the lightbox preview. Returns $this (fluent).

```php
public function conversionOnPreview(string $conversionOnPreview): self
```

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

### enableExistingMedia(): self method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/traits.md

Public method signature for enabling existing media support. Sets the 'existingMedia' meta flag to the value of the 'nova-media-library.enable-existing-media' config option.

```php
public function enableExistingMedia(): self
```

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

### setAllowedFileTypes(array $types)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets allowed MIME type prefixes for client-side validation. Uses startsWith check.

```APIDOC
## setAllowedFileTypes(array $types)

### Description
Sets allowed MIME type prefixes for client-side validation. Uses startsWith check.

### Method
builder method

### Parameters
- **$types** (array) - Required - Array of MIME type prefixes (e.g., 'image/', 'application/pdf').

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Document')->setAllowedFileTypes(['application/pdf'])
```
```

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

### withResponsiveImages usage

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

When truthy, FileAdder::withResponsiveImages() is called on every new upload. No declared return type; returns $this.

```php
Media::make('Hero')->withResponsiveImages();
```

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

### setName

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Sets the 'name' field on the Media object. The callback receives the original filename and the current model, and should return the new name.

```APIDOC
## setName

### Description
Sets the 'name' field on the Media object. The callback receives the original filename and the current model, and should return the new name.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **$originalFilename** (string) - Required - The original filename of the uploaded file.
- **$model** (mixed) - Required - The current model instance.

### Request Example
```php
Images::make('Image 1', 'img1')
    ->setName(function($originalFilename, $model){
        return md5($originalFilename);
    });
```

### Response
#### Success Response
Returns the modified field instance to allow chaining.

#### Response Example
N/A
```

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

### loadTranslations() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/service-provider.md

Protected method that loads JSON translations from the package and application override directories.

```php
protected function loadTranslations()
```

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

### Images::make()->temporary() / Files::make()->temporary()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Generates a temporary signed URL for media stored on Amazon S3. This method is called on Images or Files field instances.

```APIDOC
## Images::make()->temporary() / Files::make()->temporary()

### Description
Generates a temporary signed URL for media stored on Amazon S3. This method is called on Images or Files field instances.

### Method
`temporary(Carbon $expiration)`

### Parameters
- **$expiration** (Carbon) - Required - A valid Carbon instance specifying when the URL should expire.

### Return Value
Returns the field instance for chaining.

### Example
```php
Images::make('Image 1', 'img1')
    ->temporary(now()->addMinutes(5));

Files::make('Multiple files', 'multiple_files')
    ->temporary(now()->addMinutes(10));
```

### Note
This feature does not work with the existing media feature.
```

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

### getMediaUrls() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Returns the URL map for one media item. Delegates to getTemporaryConversionUrls() if $secureUntil is a Carbon, otherwise to getConversionUrls().

```php
public function getMediaUrls($media)
```

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

### setFileName($callback)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Sets a custom callback to generate the stored file name. The callback receives the original filename, extension, and model.

```APIDOC
## setFileName($callback)

### Description
Sets a custom callback to generate the stored file name. The callback receives the original filename, extension, and model.

### Method
builder method

### Parameters
- **$callback** (callable) - Required - Callback signature: `($originalFilename, $extension, $model)`.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('Document')->setFileName(fn($name, $ext) => str_slug($name).'.'.$ext)
```
```

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

### customHeaders usage

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Uses FileAdder::addCustomHeaders() (Spatie Media Library ≥ v10). Files are uploaded from a temporary URL so headers are applied on copy.

```php
Media::make('Attachment')->customHeaders(['X-Metadata' => 'project-42']);
```

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

### setMaxFileSize() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Declares the method that sets the meta flag 'maxFileSize' used by the frontend to reject files larger than the given size in kilobytes before upload. Falls back to the file input when the size is exceeded; the user sees a toasted error. This is a client-side check only — server-side limits still need singleMediaRules().

```php
public function setMaxFileSize(int $maxSize)
```

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

### Define custom properties fields for Images and Files

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Adds user-input custom properties fields (Boolean, Markdown) to Images and Files fields. The customPropertiesFields method accepts Nova fields.

```php
Images::make('Gallery')
    ->customPropertiesFields([
        Boolean::make('Active'),
        Markdown::make('Description'),
    ]);
    
Files::make('Multiple files', 'multiple_files')
    ->customPropertiesFields([
        Boolean::make('Active'),
        Markdown::make('Description'),
    ]);
```

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

### serializeMediaUsing

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Overrides how each Spatie Media item is converted to a PHP array before being sent to the frontend. The callback receives the Media model and must return an array, which is merged with a `__media_urls__` key in `resolve()`.

```APIDOC
## serializeMediaUsing(callable $serializeMediaUsing): self

### Description
Overrides how each `Spatie\MediaLibrary\MediaCollections\Models\Media` item is converted to a PHP array before being sent to the frontend. The callback receives the `Media` model and must return an array. The returned array is merged with a `__media_urls__` key in `resolve()`.

### Method
serializeMediaUsing

### Signature
```php
public function serializeMediaUsing(callable $serializeMediaUsing): self
```

### Parameters
- `$serializeMediaUsing` (callable) - Required - `function (\Spatie\MediaLibrary\MediaCollections\Models\Media $media): array`

### Returns
`$this` (fluent).

### Example
```php
Media::make('Video', 'video')
    ->serializeMediaUsing(function ($media) {
        return [
            'id' => $media->id,
            'custom' => ['view_count' => $media->getCustomProperty('views')],
        ];
    });
```

### Notes
The existing-media search endpoint response (see [endpoints.md](../endpoints.md)) is not affected by this callback.
```

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

### getMediaUrls($media)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Returns the URL map for one media item. If `$secureUntil` is a `Carbon` it delegates to `getTemporaryConversionUrls()`, otherwise to `getConversionUrls()`.

```APIDOC
## getMediaUrls($media)

### Description
Returns the URL map for one media item: if `$secureUntil` is a `Carbon` it delegates to `getTemporaryConversionUrls()`, otherwise to `getConversionUrls()` (see [traits.md](./traits.md)). Result shape (identical keys for both variants):

```php
[
    '__original__' => string, // full URL of the original file
    'indexView'    => string, // conversionOnIndexView || ''
    'detailView'   => string, // conversionOnDetailView || ''
    'form'         => string, // conversionOnForm || ''
    'preview'      => string, // conversionOnPreview || ''
]
```

### Parameters
#### Path Parameters
- `$media` (\Spatie\MediaLibrary\MediaCollections\Models\Media) - Required - The media item

### Response
#### Success Response (array)
Returns an array with keys `__original__`, `indexView`, `detailView`, `form`, `preview`.
```

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

### serializeMedia() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Serializes a media item. Uses callback set with serializeMediaUsing() if available, otherwise $media->toArray(). Called by resolve() and merged with __media_urls__.

```php
public function serializeMedia(\Spatie\MediaLibrary\MediaCollections\Models\Media $media): array
```

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

### MediaRequest rules() method

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/http.md

Defines optional validation rules for search_text, page, and per_page. Violations (e.g., non-numeric per_page) result in a 422 ValidationException.

```php
public function rules()
{
    return [
        'search_text' => 'sometimes|nullable|string',
        'page' => 'sometimes|nullable|numeric',
        'per_page' => 'sometimes|nullable|numeric'
    ];
}
```

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

### customHeaders(array $headers)

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/configuration.md

Adds extra headers to files added through the field by calling FileAdder::addCustomHeaders.

```APIDOC
## customHeaders(array $headers)

### Description
Adds extra headers to files added through the field by calling FileAdder::addCustomHeaders.

### Method
builder method

### Parameters
- **$headers** (array) - Required - Associative array of headers to add.

### Returns
- **$this** - The field instance for chaining.

### Example
```php
Media::make('File')->customHeaders(['Cache-Control' => 'no-cache'])
```
```

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

### Use Files field for generic file uploads

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Use the Files field to handle generic file uploads. The second parameter is the media collection name.

```php
use Ebess\AdvancedNovaMediaLibrary\Fields\Files;

Files::make('Single file', 'one_file'),
Files::make('Multiple files', 'multiple_files'),
```

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

### setName() method signature

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

Declares the callback that computes the 'name' attribute of the created Media model (default: original filename without extension). The callback receives the original filename and the model.

```php
public function setName($callback)
```

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

### Images::make()->customHeaders()

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Sets custom headers for the media field. This method is called on an Images field instance.

```APIDOC
## Images::make()->customHeaders()

### Description
Sets custom headers for the media field.

### Method
`customHeaders(array $headers)`

### Parameters
- **$headers** (array) - Required - Associative array of header names and values.

### Return Value
Returns the field instance for chaining.

### Example
```php
Images::make('Gallery')
    ->customHeaders([
        'header-name' => 'header-value', 
    ]);
```
```

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

### Append new Vapor file metadata to form data

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/javascript.md

Used in FormField.fill() for a new Vapor file (file.isVaporUpload). Only metadata is appended, no binary.

```javascript
formData.append(`__media__[${field}][${index}][is_vapor_upload]`, true);
formData.append(`__media__[${field}][${index}][key]`, file.vaporFile.key);
formData.append(`__media__[${field}][${index}][uuid]`, file.vaporFile.uuid);
formData.append(`__media__[${field}][${index}][file_name]`, file.vaporFile.filename);
formData.append(`__media__[${field}][${index}][file_size]`, file.vaporFile.file_size);
formData.append(`__media__[${field}][${index}][mime_type]`, file.vaporFile.mime_type);
```

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

### Deprecated methods

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/_autodocs/api-reference/media.md

All three return `self` and only set a meta value; use the modern conversion methods instead.

```APIDOC
## Deprecated methods

### Description
All three return `self` and only set a meta value; use the modern conversion methods instead.

### Methods

#### multiple(): self
Source: `src/Fields/Media.php:348` — no-op, returns `$this`.

#### thumbnail(string $conversionOnIndexView): self
Source: `src/Fields/Media.php:357` — `withMeta(compact('conversionOnIndexView'))`.

#### conversion(string $conversionOnPreview): self
Source: `src/Fields/Media.php:366` — `withMeta(compact('conversionOnPreview'))`.

#### conversionOnView(string $conversionOnDetailView): self
Source: `src/Fields/Media.php:375` — `withMeta(compact('conversionOnDetailView'))`.
```

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

### Custom headers

Source: https://github.com/ebess/advanced-nova-media-library/blob/master/readme.md

Sets custom headers for the Images field.

```php
Images::make('Gallery')
    ->customHeaders([
        'header-name' => 'header-value', 
    ]);
```
Tokens:
Raw