Filament Curator

https://github.com/awcodes/filament-curator
Admin
Filament Curator is a media picker and manager plugin for Filament Admin that enables users to...
Tokens:166,166
Snippets:1,097
Trust Score:9.6
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the Curator Installer

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/installation.md

Run this command to start the interactive installer that configures Curator.

```bash
php artisan curator:install
```

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

### URL Generation Examples

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Examples of generating permanent URLs, temporary URLs, and using the temporary URL scope.

```php
use Awcodes\Curator\Facades\Glide;

// Permanent signed URL
$url = Glide::getUrl('uploads/photo.jpg', ['w' => 400, 'h' => 300, 'fit' => 'crop']);

// Temporary URL valid ~5 minutes, pinned to a private disk
$url = Glide::getTemporaryUrl('uploads/photo.jpg', [], null, 'private-s3');

// Make everything built inside temporary
$html = Glide::withTemporaryUrls('s3', fn () => view('post', $post)->render());
```

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

### Usage example for MimeType methods

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/mime-type.md

Shows how to detect a MIME type from file contents, resolve an extension, and check acceptance against allowed types. The example uses 'photo.JPG' as the client extension, which resolves to 'jpg'.

```php
use Awcodes\Curator\Enums\MimeType;

$type = MimeType::detectFromContents($bytes);                       // e.g. "image/jpeg"
$ext  = MimeType::resolveExtension($type, 'photo.JPG');             // "jpg"
$ok   = MimeType::isAccepted($type, ['image/*', 'application/pdf']); // true
```

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

### Uploader Configuration Example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/uploader-and-editor.md

Example of configuring the Uploader field within a Filament form, including disk, directory, accepted file types, and image resizing settings.

```php
use Awcodes\Curator\Components\Forms\Uploader;

Uploader::make('file')
    ->disk('public')
    ->directory('images')
    ->acceptedFileTypes(['image/*', 'application/pdf'])
    ->maxSize(2048)
    ->maxFiles(1)
    ->preserveFilenames()
    ->imageResizeMode('contain')
    ->imageResizeTargetWidth('1200')
    ->imageResizeTargetHeight('1200');
```

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

### Media Model Usage Examples

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-model.md

Examples of retrieving a media record, accessing its URL and thumbnail properties, and generating a custom Glide transformation URL.

```php
use Awcodes\Curator\Models\Media;

$media = Media::find(1);

echo $media->url;            // signed/plain URL
echo $media->thumbnail_url;  // 200x200 webp crop URL
echo $media->getPrettyName(); // "title" or "name.ext"

// Custom transform on a specific record
$url = $media->getGlideUrl(['w' => 800, 'h' => 600, 'fit' => 'contain']);
```

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

### Usage Example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Blade usage example for the Glider component.

```APIDOC
## Usage Example

### Blade Template

```blade
<x-curator-glider
    :media="$post->hero_image_id"
    width="800"
    format="webp"
    fit="crop"
    quality="80"
    :srcset="['320w', '640w', '1024w', '2x']"
    sizes="(max-width: 600px) 320px, 800px"
    fallback="placeholder"
/>
```

### Output
- For previewable media: renders an <img> tag with src, srcset, and sizes attributes.
- For non-previewable media: renders <x-curator::display.document>.
```

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

### Media Factory Usage Example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-model.md

Demonstrates how to use the Media factory to create a private image record.

```php
use Awcodes\Curator\Models\Media;

Media::factory()->type('image')->private()->create();
```

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

### MediaScope usage example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-scope.md

Demonstrates initializing a MediaScope instance and using its methods to resolve media, check containment, and extract IDs.

```php
use Awcodes\
Curator\\Support\\MediaScope;

$scope = new MediaScope(
    disk: 'public',
    acceptedFileTypes: ['image/*'],
    directory: 'products',
    isLimitedToDirectory: true,
);

$media = $scope->resolve([1, 2, 3]);          // Collection<Media>, ids outside scope dropped
$ok    = $scope->contains([1, 2]);            // bool
$dirs  = $scope->directories();               // navigable directories
$ids   = MediaScope::extractIds($state);      // normalize picker state to ids
```

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

### GlideBuilder Fluent Usage Example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/glide.md

Demonstrates using the fluent builder to generate a signed URL and a raw query string.

```php
use Awcodes\Curator\Glide\GlideBuilder;

$url = GlideBuilder::make()
    ->width(400)
    ->height(300)
    ->fit('crop')
    ->format('webp')
    ->quality(80)
    ->blur(2)
    ->toUrl('uploads/photo.jpg');

// Equivalent without signing:
$query = GlideBuilder::make()->width(200)->height(200)->toQueryString(); // "w=200&h=200"
```

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

### Configuring Curation Presets

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Example of using the Curation facade to configure multiple curation presets for the application.

```php
use Awcodes\Curator\Curations\CurationPreset;
use Awcodes\Curator\Facades\Curation;

Curation::configure()->presets([
    CurationPreset::make('Thumbnail')->width(200)->height(200)->format('webp')->quality(60),
    CurationPreset::make('Hero')->width(1600)->height(900)->format('jpg')->quality(80),
]);
```

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

### Use Curator Facades

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Example usage of the new Curator, Curation, and Glide facades for accessing core functionality.

```php
use Awcodes\Curator\Facades\Curator;
use Awcodes\Curator\Facades\Curation;
use Awcodes\Curator\Facades\Glide;

// Example usage
$media = Curator::getMedia($id);
$curation = Curation::getCuration($mediaId, 'thumbnail');
```

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

### Install Tailwind Vite plugin

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Install the required Tailwind Vite plugin if it is missing from your project dependencies.

```bash
npm install -D @tailwindcss/vite
```

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

### CuratorColumn usage example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Example of creating a CuratorColumn with a label, image size, and resolution for high-DPI displays.

```php
use Awcodes\Curator\Components\Tables\CuratorColumn;

CuratorColumn::make('featured_image')
    ->label('Image')
    ->imageSize(80)
    ->resolution(2);   // retina / high-DPI
```

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

### Media Model Usage

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-model.md

Example of using the Media model to access URLs and methods.

```APIDOC
## Media Model Usage

### Description
Example of using the Media model to access URLs and methods.

### Code
```php
use Awcodes\Curator\Models\Media;

$media = Media::find(1);

echo $media->url;            // signed/plain URL
echo $media->thumbnail_url;  // 200x200 webp crop URL
echo $media->getPrettyName(); // "title" or "name.ext"

// Custom transform on a specific record
$url = $media->getGlideUrl(['w' => 800, 'h' => 600, 'fit' => 'contain']);
```
```

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

### Importing media with CuratorUtils

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/curator-utils.md

Example usage of CuratorUtils::importMedia to import a file from a URL and create a Media record.

```php
use Awcodes
ullCurator
ullCuratorUtils;
use Awcodes
ullCurator
ullModels
ullMedia;

try {
    $data = CuratorUtils::importMedia(
        path: 'https://example.com/photo.jpg',
        alt: 'A photo',
    );

    Media::create($data);
} catch (
ullException $e) {
    report($e);
}
```

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

### Signed URL Request Example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/endpoints.md

Example of a signed request using curl. The signature is generated by the library and must be included in the query parameters.

```bash
# A signed URL is normally built by the library:
#   Glide::getUrl('uploads/photo.jpg', ['w' => 400, 'h' => 300, 'fit' => 'crop'])
# Example resulting request:
curl -G 'https://example.com/curator/uploads/photo.jpg' \
  -d w=400 -d h=300 -d fit=crop \
  -d sig=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
```

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

### Registering a Glider Fallback

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/glide.md

Example of registering a custom fallback placeholder using the Glide facade.

```php
use Awcodes\Curator\Facades\Glide;
use Awcodes\Curator\Glide\GliderFallback;

Glide::registerGliderFallback(
    GliderFallback::make('placeholder')
        ->source('placeholders/missing.svg')
        ->alt('Missing image')
        ->width(400)
        ->height(300),
);
```

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

### Supply custom Glide server configuration

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/storage/glide.md

Pass a Glide server configuration to the facade to take over how media is served. This example uses Imagick driver and a local cache.

```php
use Awcodes\Curator\Facades\Glide;
use Illuminate\Support\Facades\Storage;

public function register(): void
{
    Glide::serverConfig([
        'driver' => 'imagick',
        'source' => Storage::disk('public')->getDriver(),
        'cache' => storage_path('app'),
        'cache_path_prefix' => '.cache',
        'max_image_size' => 2000 * 2000,
    ]);
}
```

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

### Install Filament Curator via Composer

Source: https://github.com/awcodes/filament-curator/blob/5.x/README.md

Run this command to add the package to your project dependencies.

```bash
composer require awcodes/filament-curator
```

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

### Configure Feature Flags

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Example configuration array for enabling or disabling specific Curator features.

```php
'features' => [
    'curations' => true,
    'file_swap' => true,
    'directory_restriction' => false,
    'tenancy' => [
        'enabled' => false,
        'relationship_name' => null,
    ],
],
```

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

### curator:install command signature

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/plugin-and-provider.md

Defines the signature for the curator:install command, which supports options for UUID primary key, tenancy model name, and running migrations. Interactive prompts back these options when not passed.

```php
public $signature = 'curator:install
    {--use-uuid= : Use UUID for the primary key (default: false)}
    {--tenancy-name= : The name of the tenant model (e.g., Team)}
    {--run-migrations= : Run migrations after installation (default: false)}
';
```

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

### GET /{path}

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/endpoints.md

Serves media files. The route uses a catch-all path parameter and a configurable base path (default 'curator').

```APIDOC
## GET /{path}

### Description
Serves media files. The route uses a catch-all path parameter and a configurable base path (default 'curator').

### Method
GET

### Endpoint
/{path}

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the media file. Supports multi-segment paths.

### Response
#### Success Response (200)
Returns the media file content.

#### Response Example
(No explicit response example provided in the source.)
```

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

### Global path_generator configuration

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/path-generators.md

Configuration example for setting the global path generator. Set it to any class-string implementing PathGenerator to apply it to every picker/uploader that does not override it.

```php
// config/curator.php
'path_generator' => null,
```

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

### Configuring Curator upload settings

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Example of using the Curator facade to configure global upload settings like disk, directory, max size, and accepted file types.

```php
use Awcodes	Curator	Facades	Curator;

Curator::configure()
    ->disk('s3')
    ->directory('products')
    ->maxSize(2048)
    ->acceptedFileTypes(['image/*', 'application/pdf']);
```

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

### Publish Curator configuration file

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/configuration.md

Use this Artisan command to publish the configuration file if it was not automatically published during installation.

```bash
php artisan vendor:publish --tag="curator-config"
```

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

### Glide Server Factory Registration

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Example of setting a custom Glide server factory in a Service Provider using the Glide facade.

```php
use Awcodes\Curator\Facades\Glide;

public function register(): void 
{
    Glide::serverConfig([
        'driver' => 'imagick',
        'response' => new LaravelResponseFactory(app('request')),
        'source' => storage_path('app'),
        'source_path_prefix' => 'public',
        'cache' => storage_path('app'),
        'cache_path_prefix' => '.cache',
        'max_image_size' => 2000 * 2000,
    ]);
}
```

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

### CuratorPicker usage example

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/curator-picker.md

Configure a CuratorPicker field with multiple selection, disk, directory, accepted file types, directory restriction, and max items. Use this to set up a picker for product images.

```php
use Awcodes\Curator\Components\Forms\CuratorPicker;

CuratorPicker::make('images')
    ->multiple()
    ->disk('public')
    ->directory('products')
    ->acceptedFileTypes(['image/*'])
    ->limitToDirectory()
    ->maxItems(5);
```

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

### GET /{basePath}/{path}

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/endpoints.md

Serves media files with optional Glide transformations. Requires a valid Glide signature for authentication. Supports temporary URLs with expiration for private media.

```APIDOC
## GET /{basePath}/{path}

### Description
Serves media files with optional Glide transformations. Requires a valid Glide signature for authentication. Supports temporary URLs with expiration for private media.

### Method
GET

### Endpoint
/{basePath}/{path} where basePath defaults to 'curator' and path is the media's stored path.

### Parameters
#### Path Parameters
- **basePath** (string) - Optional - Base path for media, defaults to 'curator'.
- **path** (string) - Required - The stored path of the media file.

#### Query Parameters
- **{transform}** (string) - Optional - Glide transform parameters, e.g., w, h, fit, fm, q, crop, dpr, blur, bg, border, bri, con, filt, flip, gam, mark* (watermark family), or, pixel, sharp.
- **sig** (string) - Required - The Glide signature produced by UrlBuilderFactory::create($basePath, $token)->getUrl(...).
- **expires** (int) - Optional - Unix timestamp; present on temporary URLs (private media). Must be an all-digit string and greater than now(). Malformed or expired values are rejected with 403.
- **disk** (string) - Optional - The disk the temporary URL was issued for (only meaningful together with expires). Used to resolve the media record when the same path exists on multiple disks.

### Request Example
```bash
curl -G 'https://example.com/curator/uploads/photo.jpg' \
  -d w=400 -d h=300 -d fit=crop \
  -d sig=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
```

### Response
#### Success Response (200)
- For resizable media: StreamedResponse with Content-Type/Content-Length, public cache for 1 year, and Last-Modified/304 revalidation support.
- For non-resizable media: Raw file streamed from disk with Content-Type pinned from MimeType::tryFromExtension (when known), else sniffed (never a sniffed document/scriptable type - those fall back to application/octet-stream with attachment disposition). X-Content-Type-Options: nosniff. Content-Disposition: attachment for restricted types, inline otherwise.
- For temporary URLs: keepPrivate() removes Expires, sets Cache-Control: private, max-age=<seconds-until-expiry>.

#### Response Example
(No explicit response body example provided in source)

#### Status Codes
- **200** - Media served (transformed or raw)
- **304** - Not modified (revalidation against Last-Modified, resizable path)
- **403** - Invalid signature (SignatureException from SignatureFactory::validateRequest), or expires malformed/expired
- **404** - No Media record resolves for the path (+ optional disk), or the request is permanent and the record is not public

### Error Handling
| Condition | Result | Source |
|-----------|--------|--------|
| Invalid signature | abort(403) | src/Http/Controllers/MediaController.php:36 |
| expires absent | treated as permanent URL | getExpiration() returns null |
| expires not an all-digit string | abort(403) | getExpiration() returns false |
| expires in the past | abort(403) | getExpiration() returns false |
| No resolvable Media | abort(404) | src/Http/Controllers/MediaController.php:44 |
| Glide read failures | FilesystemException / FileNotFoundException (declared on show()) | League Glide |
```

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

### CuratorPlugin::boot()

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/plugin-and-provider.md

Boots the plugin. This is a no-op method that does nothing, as the plugin does not require additional boot logic.

```APIDOC
## CuratorPlugin::boot()

### Description
Boots the plugin. This is a no-op method that does nothing, as the plugin does not require additional boot logic.

### Method
boot

### Signature
`boot(Panel $panel): void`

### Parameters
- **$panel** (Filament\Panel) - Required - The Filament panel instance.

### Return Value
void

### Example
```php
$plugin->boot($panel);
```
```

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

### GlideManager::getServer()

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Builds a League\Glide\Server instance. Uses the provided disk or the default disk from configuration. If serverConfig() was called, it uses that config with forced overrides for base_url and response factory.

```APIDOC
## GlideManager::getServer()

### Description
Builds a `League\Glide\Server` instance.

### Method
`public function getServer(?string $disk = null): Server`

### Parameters
#### Query Parameters
- **disk** (string|null) - Optional - The disk to use as the source. Defaults to `config('curator.default_disk')`.

### Returns
- **Server** - The configured League Glide Server instance.
```

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

### GlideManager::getMediaUrl()

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Generates a URL for a Media model or an array. Public media gets a permanent URL; non-public media gets a temporary URL naming its disk.

```APIDOC
## GlideManager::getMediaUrl()

### Description
Accepts a `Media` model or an array `{path, disk?, visibility?}`. Public media gets a permanent URL; non-public media gets a temporary URL naming its disk.

### Method
`public function getMediaUrl(Media | array $media, array $params = []): string`

### Parameters
#### Request Body
- **media** (Media|array) - Required - The media model or an array with `path`, `disk?`, `visibility?` keys.
- **params** (array) - Optional - Glide query parameters.

### Returns
- **string** - The generated URL.
```

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

### Publishing the new configuration file

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Backup your existing configuration and publish the new v4 configuration file using Artisan.

```bash
# Backup your current config
cp config/curator.php config/curator.php.backup

# Publish new config
php artisan vendor:publish --tag="curator-config" --force
```

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

### getCuration

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-model.md

Instance method to get a curation by key.

```APIDOC
## getCuration

### Description
Returns the first curation whose curation.key equals the given key, or an empty array if not found.

### Method
Instance method

### Signature
```php
public function getCuration(string $key): array
```

### Parameters
- **key** (string) - Required - The curation key.

### Returns
- **array** - The curation array, or empty array if not found.
```

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

### getPrettyName

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-model.md

Instance method to get a pretty name for the media.

```APIDOC
## getPrettyName

### Description
Returns the title if filled, otherwise returns name.ext.

### Method
Instance method

### Signature
```php
public function getPrettyName(): string
```

### Returns
- **string** - The pretty name.
```

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

### handleString

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Builds a MediaDTO from a bare path string.

```APIDOC
## handleString

### Description
Builds a MediaDTO from a bare path; resizable/previewable/ext derived from the extension.

### Method
handleString

### Signature
handleString(string $media): void

### Parameters
- **media** (string) - Required - The path string.

### Returns
- void
```

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

### CuratorColumn::getResolution(): ?int

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Gets the current display resolution multiplier for the column.

```APIDOC
## CuratorColumn::getResolution(): ?int

### Description
Gets the current display resolution multiplier for the column.

### Method
getResolution

### Returns
- **?int** - The resolution multiplier, or null if not set.
```

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

### getGlideUrl

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-model.md

Instance method to get a Glide URL for the media with optional parameters.

```APIDOC
## getGlideUrl

### Description
Returns a Glide URL for the media. The URL is temporary when the media is not public.

### Method
Instance method

### Signature
```php
public function getGlideUrl(array $params = []): string
```

### Parameters
- **params** (array) - Optional - An array of Glide transformation parameters.

### Returns
- **string** - The Glide URL.
```

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

### Development and Testing Commands

Source: https://github.com/awcodes/filament-curator/blob/5.x/CLAUDE.md

A collection of Composer and NPM commands for linting, refactoring, static analysis, testing, and asset building.

```bash
# Code style
composer lint           # Run Laravel Pint (fix in place)
composer test:lint      # Dry-run style check

# Refactoring
composer refactor       # Run Rector
composer test:refactor  # Dry-run Rector check

# Static analysis
composer test:types     # Run PHPStan (level 5, larastan)

# Testing
composer test:unit      # Run Pest unit tests
composer test           # Run all checks (refactor, lint, types, unit)

# Run a single test file or method
vendor/bin/pest tests/src/Unit/Models/MediaTest.php
vendor/bin/pest --filter="test name or pattern"

# Frontend assets
npm run dev             # Dev build
npm run build           # Production build
```

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

### MediaScope Constructor

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-scope.md

Creates a MediaScope instance that defines the disk, accepted file types, directory, and tenant awareness for a media picker.

```APIDOC
## MediaScope Constructor

### Description
Creates a new MediaScope value object that limits media to a specific disk, optional file types, optional directory, and optional tenant scoping.

### Method
Constructor

### Signature
```php
public function __construct(
    private string $disk,
    private array $acceptedFileTypes = [],
    ?string $directory = null,
    private bool $isLimitedToDirectory = false,
    private bool $isTenantAware = false,
    private ?string $tenantOwnershipRelationshipName = null,
) {}
```

### Parameters
- **disk** (string) - Required - The storage disk the scope is limited to.
- **acceptedFileTypes** (array<int, mixed>) - Optional - Types as a field accepts them (`image/*` wildcards included); empty means any type.
- **directory** (?string) - Optional - The directory the field is limited to (includes its subdirectories); stored normalized.
- **isLimitedToDirectory** (bool) - Optional - Whether the field is limited to its directory; when true and no directory is named, nothing is in scope.
- **isTenantAware** (bool) - Optional - Whether tenant scoping applies.
- **tenantOwnershipRelationshipName** (?string) - Optional - Relationship name used for tenant scoping (falls back to Filament's).
```

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

### Custom Component Width Parameter

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Example of using the new Width enum support in v4.

```php
// v4 adds Width enum support
use Filament\Support\Enums\Width;
->width(Width::Full)
```

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

### Set CURATOR_GLIDE_TOKEN in .env.example

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/storage/token.md

Add this key to .env.example and set it in every environment. The value does not need to match across environments, but it must be present or media URL generation and serving will fail.

```dotenv
CURATOR_GLIDE_TOKEN=
```

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

### handleMedia

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Builds a MediaDTO from a Media record and marks it as a media record.

```APIDOC
## handleMedia

### Description
Builds a MediaDTO from a record and marks it as a media record.

### Method
handleMedia

### Signature
handleMedia(Media $media): void

### Parameters
- **media** (Media) - Required - The Media model instance.

### Returns
- void
```

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

### Troubleshoot Media Grid

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Commands to resolve issues where the media picker grid appears blank or broken.

```bash
npm run build
```

```bash
php artisan optimize:clear
```

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

### Blade Component Usage

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Example of using the <x-curator-glider> component in a Blade template with various transformation and responsive attributes.

```blade
<x-curator-glider
    :media="$post->hero_image_id"
    width="800"
    format="webp"
    fit="crop"
    quality="80"
    :srcset="['320w', '640w', '1024w', '2x']"
    sizes="(max-width: 600px) 320px, 800px"
    fallback="placeholder"
/>
```

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

### Rebuild frontend assets

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Execute this command to rebuild the frontend assets for the application.

```bash
npm run build
```

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

### Curation Component Usage

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Example of using the x-curator-curation Blade component to display a specific curation of a media item.

```blade
<x-curator-curation :media="$post->hero_image_id" curation="hero" />
```

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

### Configure delete actions with modal descriptions using Curator::configureDeleteActionsUsing

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/configuration.md

Call this in a service provider's boot() method to customize all media delete actions at once. The callback receives the action; use $action instanceof BulkAction to differentiate bulk from single-record actions. Single-record actions receive $record (nullable) and bulk actions receive $records. Any Filament action method is available, including before() with halt().

```php
use Awcodes\Curator\Facades\Curator;
use Awcodes\Curator\Models\Media;
use Filament\Actions\Action;
use Filament\Actions\BulkAction;
use Illuminate\Support\Collection;

Curator::configureDeleteActionsUsing(function (Action $action): void {
    if ($action instanceof BulkAction) {
        $action->modalDescription(fn (Collection $records): string => "Delete {$records->count()} files? Any content using them will lose its image.");

        return;
    }

    $action->modalDescription(fn (?Media $record): string => "Delete {$record?->name}? Any content using it will lose its image.");
});
```

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

### Run Migration Commands

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Commands to generate and execute the migration for renaming the database table.

```bash
php artisan make:migration rename_media_table_to_curator
# Add the code above, then:
php artisan migrate
```

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

### Server Configuration Methods

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Methods for configuring the Glide server and base path.

```php
public function serverConfig(array $config): static
public function basePath(string $basePath): static
public function getServer(?string $disk = null): Server
public function getBasePath(): string
```

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

### v3 Plugin Registration

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Example of the Curator plugin registration in Filament Panels for v3, noting removed methods.

```php
use Awcodes\Curator\CuratorPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            CuratorPlugin::make()
                ->label('Media')
                ->pluralLabel('Media')
                ->navigationIcon('heroicon-o-photo')
                ->navigationGroup('Content')
                ->navigationSort(3)
                ->navigationCountBadge()           // ❌ Removed
                ->registerNavigation(false)
                ->defaultListView('grid')          // ❌ Removed
                ->resource(\App\Filament\Resources\CustomMediaResource::class), // ❌ Removed
        ]);
}
```

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

### Configure Glide for cloud disks

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/storage/glide.md

Supply a server config with an S3 source and local cache for cloud disks. Note that source must point to the disk where media lives and cache should be fast local storage.

```php
use Awcodes\Curator\Facades\Glide;
use Illuminate\Support\Facades\Storage;

Glide::serverConfig([
    'source' => Storage::disk('s3')->getDriver(),
    'cache' => Storage::disk('local')->getDriver(),
    'cache_path_prefix' => '.cache',
    'max_image_size' => 2000 * 2000,
]);
```

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

### CuratorPicker::make() with rules() and imageResizeMode()

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/fields/picker.md

Example of using the CuratorPicker component to reject images wider than 2000px or scale them down before upload.

```APIDOC
## CuratorPicker::make()

### Description
Creates a CuratorPicker form field. The example shows how to use rules() to reject images wider than 2000px, or use imageResizeMode() and imageResizeTargetWidth() to scale images down before upload.

### Method
make()

### Parameters
- **name** (string) - Required - The field name.
- **rules** (array) - Optional - Validation rules. Example: ['dimensions:max_width=2000']
- **imageResizeMode** (string) - Optional - Resize mode, e.g., 'contain'.
- **imageResizeTargetWidth** (string) - Optional - Target width in pixels, e.g., '2000'.

### Request Example
```php
use Awcodes\Curator\Components\Forms\CuratorPicker;

// Reject images wider than 2000px.
CuratorPicker::make('featured_image_id')
    ->rules(['dimensions:max_width=2000']);

// Or scale them down to 2000px wide before they are uploaded.
CuratorPicker::make('featured_image_id')
    ->imageResizeMode('contain')
    ->imageResizeTargetWidth('2000');
```

### Response
No response body. The method returns a CuratorPicker instance for chaining.
```

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

### Extend Curator media model and update config

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/configuration.md

Shows how to create a custom Media model extending CuratorMedia and point the config 'model' key to it. The parent already sets the table to 'curator', so only declare $table if you renamed it.

```php
namespace App\Models;

use Awcodes\Curator\Models\Media as CuratorMedia;

class Media extends CuratorMedia
{
    //
}
```

```php
'model' => \App\Models\Media::class,
```

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

### handleId

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/table-and-view-components.md

Loads a media record by key and calls handleMedia().

```APIDOC
## handleId

### Description
Loads the record by key and calls handleMedia(); leaves mediaItem unset when not found.

### Method
handleId

### Signature
handleId(int|string $media): void

### Parameters
- **media** (int|string) - Required - The media key (ID, UUID, or ULID).

### Returns
- void
```

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

### v4 Plugin Registration

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Example of the updated Curator plugin registration for v4, including new methods and renamed parameters.

```php
use Awcodes\Curator\CuratorPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            CuratorPlugin::make()
                ->label('Media')
                ->pluralLabel('Media')
                ->navigationIcon('heroicon-o-photo')
                ->navigationGroup('Content')
                ->navigationSort(3)
                ->showBadge(true)               // ✅ Renamed from navigationCountBadge()
                ->registerNavigation(true)
                ->curations(true)               // ✅ New: Control curation feature
                ->fileSwap(true),               // ✅ New: Control file swap feature
        ]);
}
```

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

### CurationPreset::format

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/types.md

Sets the format of the preset. Returns the instance for chaining.

```APIDOC
## CurationPreset::format

### Description
Sets the format of the preset. Returns the instance for chaining.

### Method
`format(string $format): static`

### Parameters
- **format** (string) - Required - The image format (e.g., 'jpg', 'webp').

### Returns
- **static** - The current instance for chaining.

### Example
```php
$preset->format('webp');
```
```

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

### getLabel(): string

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/mime-type.md

Returns a human-readable label for the MIME type case. For example, 'Adobe Portable Document Format (PDF)' or 'JPEG images'.

```APIDOC
## getLabel(): string

### Description
Returns a human-readable label for the MIME type case. Examples: 'Adobe Portable Document Format (PDF)', 'JPEG images', 'HyperText Markup Language (HTML)'.

### Method
Instance method

### Returns
- **string** - The human-readable label.
```

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

### MediaScope Static Helpers

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-scope.md

Static utility methods for extracting IDs, directory normalization, and query constraints.

```php
public static function extractIds(mixed $state): array            // array<int, string>
public static function whereWithinDirectory(Builder $query, string $directory): Builder
public static function normalizeDirectory(?string $directory): ?string
public static function escapeLike(string $value): string
```

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

### getExt(): string

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/mime-type.md

Returns the canonical file extension for the MIME type case. For example, ApplicationPdf returns 'pdf', ImageJpeg returns 'jpg'.

```APIDOC
## getExt(): string

### Description
Returns the canonical file extension for the case. Examples: ApplicationPdf -> 'pdf', ImageJpeg -> 'jpg', ImageSvgXml -> 'svg', ApplicationOctetStream -> 'bin', AudioMpeg -> 'mp3', ApplicationX7zCompressed -> '7z'.

### Method
Instance method

### Returns
- **string** - The canonical file extension.
```

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

### CuratorPicker validation and resizing

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/fields/picker.md

Examples of using rules to reject images based on dimensions and using image resizing methods to scale images before upload.

```php
use Awcodes	apCurator	apComponents	apForms	apCuratorPicker;

// Reject images wider than 2000px.
CuratorPicker::make('featured_image_id')
    ->rules(['dimensions:max_width=2000']);

// Or scale them down to 2000px wide before they are uploaded.
CuratorPicker::make('featured_image_id')
    ->imageResizeMode('contain')
    ->imageResizeTargetWidth('2000');
```

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

### Dispatching insert-media event

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/panel-and-curation.md

Dispatches the 'insert-media' Livewire event with the current state path, media data, and context.

```php
$this->dispatch('insert-media', [
    'statePath' => $this->statePath,
    'media' => $media,
    'context' => $this->context,
]);
```

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

### Using pathGenerator() on CuratorPicker

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/path-generators.md

Example of setting a custom path generator per field using the pathGenerator() method on CuratorPicker. Here it uses DatePathGenerator::class.

```php
use Awcodes\Curator\PathGenerators\DatePathGenerator;
use Awcodes\Curator\Components\Forms\CuratorPicker;

CuratorPicker::make('image')
    ->pathGenerator(DatePathGenerator::class);
```

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

### Troubleshoot Plugin Registration

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Command to clear cache if the Curator menu item is not appearing.

```bash
php artisan optimize:clear
```

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

### Configure Curator, Glide, and Curation presets in AppServiceProvider::boot()

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/configuration.md

Use this snippet to programmatically configure the Curator plugin, including disk, directory, max size, accepted file types, and URL provider. It also configures Glide with a base path and fallback, and defines a curation preset. Finally, it registers the plugin in a Filament panel with a custom label and navigation group.

```php
// AppServiceProvider::boot()
use Awcodes\Curator\Curations\CurationPreset;
use Awcodes\Curator\CuratorPlugin;
use Awcodes\Curator\Facades\Curation;
use Awcodes\Curator\Facades\Curator;
use Awcodes\Curator\Facades\Glide;
use Awcodes\Curator\PathGenerators\DatePathGenerator;

Curator::configure()
    ->disk('s3')
    ->directory('uploads')
    ->maxSize(8192)
    ->acceptedFileTypes(['image/*', 'application/pdf'])
    ->urlProvider(MyUrlProvider::class);

Glide::configure()
    ->basePath('media')
    ->registerGliderFallback(GliderFallback::make('placeholder')->source('placeholders/blank.svg'));

Curation::configure()->presets([
    CurationPreset::make('Thumbnail')->width(200)->height(200)->format('webp')->quality(60),
]);

// panel registration
$panel->plugins([
    CuratorPlugin::make()->label('Media')->navigationGroup('Content'),
]);
```

```php
// AppServiceProvider::boot()
use Awcodes\Curator\Curations\CurationPreset;
use Awcodes\Curator\CuratorPlugin;
use Awcodes\Curator\Facades\Curation;
use Awcodes\Curator\Facades\Curator;
use Awcodes\Curator\Facades\Glide;
use Awcodes\Curator\PathGenerators\DatePathGenerator;

Curator::configure()
    ->disk('s3')
    ->directory('uploads')
    ->maxSize(8192)
    ->acceptedFileTypes(['image/*', 'application/pdf'])
    ->urlProvider(MyUrlProvider::class);

Glide::configure()
    ->basePath('media')
    ->registerGliderFallback(GliderFallback::make('placeholder')->source('placeholders/blank.svg'));

Curation::configure()->presets([
    CurationPreset::make('Thumbnail')->width(200)->height(200)->format('webp')->quality(60),
]);

// panel registration
$panel->plugins([
    CuratorPlugin::make()->label('Media')->navigationGroup('Content'),
]);
```

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

### readSample(mixed $stream): string

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/mime-type.md

Reads and closes a stream, returning the first 64 KiB.

```APIDOC
## readSample(mixed $stream): string

### Description
Reads and closes a stream, returning the first 64 KiB.

### Method
Static method

### Parameters
- **$stream** (mixed) - Required - The stream to read.

### Returns
- **string** - The first 64 KiB of the stream.
```

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

### Using CanNormalizePaths in a custom class

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/path-generators.md

Example of using the CanNormalizePaths trait in a custom storage class. The normalizePath method is called to clean up a directory path, e.g. '/uploads//images/' becomes 'uploads/images'.

```php
use Awcodes\Curator\Concerns\CanNormalizePaths;

class MyStorage
{
    use CanNormalizePaths;

    public function store(string $dir): void
    {
        $dir = $this->normalizePath($dir); // e.g. "/uploads//images/" => "uploads/images"
    }
}
```

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

### CurationPreset::getFormat

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/types.md

Returns the format of the preset, defaulting to 'jpg' if not set.

```APIDOC
## CurationPreset::getFormat

### Description
Returns the format of the preset, defaulting to 'jpg' if not set.

### Method
`getFormat(): string`

### Returns
- **string** - The format, or 'jpg' if not set.

### Example
```php
$format = $preset->getFormat();
```
```

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

### GlideManager::serverConfig()

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/managers.md

Stores raw League Glide server options. This configuration is used when building the server, with some forced overrides.

```APIDOC
## GlideManager::serverConfig()

### Description
Stores raw League Glide server options.

### Method
`public function serverConfig(array $config): static`

### Parameters
#### Request Body
- **config** (array) - Required - Raw League Glide server options.

### Returns
- **static** - The current GlideManager instance.
```

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

### is_media_resizable(string $ext): bool

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/curator-utils.md

Checks if a file extension is resizable by the media library.

```APIDOC
## is_media_resizable(string $ext): bool

### Description
Checks if a file extension is resizable by the media library.

### Method
Function

### Signature
is_media_resizable(string $ext): bool

### Parameters
- **$ext** (string) - Required - The file extension to check.

### Returns
- **bool** - True if the extension is resizable, false otherwise.
```

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

### Register CuratorPlugin on a Filament panel

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/plugin-and-provider.md

Example of registering the CuratorPlugin on a Filament panel with custom label, plural label, navigation icon, navigation group, and enabling curations while disabling file swap.

```php
use Awcodes\Curator\CuratorPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel->plugins([
        CuratorPlugin::make()
            ->label('Media')
            ->pluralLabel('Media')
            ->navigationIcon('heroicon-o-photo')
            ->navigationGroup('Content')
            ->curations()
            ->fileSwap(false),
    ]);
}
```

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

### Rebuild project assets

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Run these commands to rebuild your assets and clear caches after updating your theme configuration.

```bash
npm run build
php artisan filament:assets
php artisan optimize:clear
```

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

### tenantAware

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/curator-picker.md

Applies tenant scoping to the picker.

```APIDOC
## tenantAware

### Description
Applies tenant scoping to the picker. Defaults to `curator.features.tenancy.enabled`.

### Signature
`tenantAware(bool|Closure $condition = true): static`

### Parameters
- **$condition** (bool|Closure) - Optional - Defaults to `true`. When `false`, tenant scoping is not applied.

### Returns
`static` - The picker instance for chaining.
```

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

### Republish Configuration

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Command to force republish the Curator configuration file after backing up old settings.

```bash
php artisan vendor:publish --tag="curator-config" --force
```

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

### Configure RichEditor with AttachCuratorMediaPlugin

Source: https://github.com/awcodes/filament-curator/blob/5.x/docs/fields/rich-editor.md

Register the plugin and add the 'attachCuratorMedia' tool to the toolbar. Both steps are required to make the media picker accessible.

```php
use Awcodes	Curator\Components\Forms\RichEditor\AttachCuratorMediaPlugin;
use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->tools([
        'attachCuratorMedia',
    ])
    ->plugins([
        AttachCuratorMediaPlugin::make(),
    ]);
```

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

### MediaDTO::getDescription()

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-scope.md

Returns the description of the media.

```APIDOC
## MediaDTO::getDescription()

### Description
Returns the description of the media.

### Method
PHP method

### Signature
`public function getDescription(): ?string`

### Returns
- **?string** - The description.
```

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

### MediaScope Query Construction Methods

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-scope.md

Methods for building and applying scope-based queries to the media model.

```php
public function query(): Builder
public function apply(Builder $query): Builder
public function tenantQuery(): Builder
```

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

### MediaScope::tenantQuery

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/media-scope.md

Builds a query for media of the current tenant regardless of disk/type/directory, used to keep already-saved records loadable.

```APIDOC
## MediaScope::tenantQuery

### Description
Returns media of the current tenant regardless of disk/type/directory (used to keep already-saved records loadable).

### Method
Instance method

### Signature
```php
public function tenantQuery(): Builder
```

### Return Value
- **Builder** - A query builder for the current tenant's media.
```

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

### getMediaScope

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/panel-and-curation.md

Builds the media scope from picker settings.

```APIDOC
## getMediaScope

### Description
Builds the scope from `diskName`, `acceptedFileTypes` (or `[]` when `showAll`), `settings['directory']`, `isLimitedToDirectory`, `isTenantAware`, `tenantOwnershipRelationshipName`.

### Method
Public method

### Signature
`public function getMediaScope(): MediaScope`
```

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

### Defining getMediaScope method

Source: https://github.com/awcodes/filament-curator/blob/5.x/_autodocs/api-reference/panel-and-curation.md

Defines the method signature for building the media scope based on disk, file types, directory settings, and tenant awareness.

```php
public function getMediaScope(): MediaScope
```

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

### Clear application caches

Source: https://github.com/awcodes/filament-curator/blob/5.x/UPGRADE.md

Run these commands to clear various application caches after completing the upgrade steps.

```bash
php artisan optimize:clear
php artisan config:clear
php artisan view:clear
php artisan filament:assets
```
Tokens:
Raw