Download the PHP package povly/moonshine-image-editor without Composer

MoonShine Image Editor

Image editor for MoonShine admin panel powered by Filerobot Image Editor. Integrates with MoonShine Media Manager to provide in-browser image editing with automatic optimization and WebP/AVIF conversion.

Features

• Full-featured image editor: adjust, annotate, crop, resize, rotate, filters, finetune, watermark
• Format selector (PNG/JPG) in modal toolbar — defaults to original format, separate from editor
• Automatic optimization on upload via Media Manager events — images are optimized and converted when uploaded through the file manager
• Automatic cleanup on delete — WebP/AVIF conversions are removed when the source image is deleted
• Admin settings page — manage optimization quality, conversion toggles, and queue settings directly from MoonShine panel (stored in DB)
• Batch optimization — scan and re-process existing images with real-time progress bar, detailed logs (webp vs original, avif vs webp), and file filter
• Optimization with size comparison (keeps smaller version)
• Optional WebP/AVIF conversion with size-aware cleanup
• Queue support for async processing
• Localization support (EN, RU) via Laravel lang files
• No CDN dependencies — all assets are local
• Imagick driver support with automatic fallback to GD
• Integrates as a file action button in Media Manager

Requirements

• PHP 8.2+
• Laravel 11+ / 12+
• MoonShine 4.x
• yurizoom/moonshine-media-manager ^4.0
• intervention/image-laravel ^1.0 (installs intervention/image ^3.0 automatically)
• PHP Imagick extension (recommended) or GD

Installation

Image Optimization Dependency

For image optimization and format conversion (WebP/AVIF) to work, install Intervention Image:

Note: Only intervention/image-laravel is needed — it automatically installs intervention/image as a dependency.

Publish the Intervention Image config (optional):

This creates config/image.php where you can set the default driver (GD or Imagick).

Publish assets:

Optionally publish config and translations:

Or everything at once:

Run migrations (creates image_editor_settings table):

Setup

1. Register assets

Add the package JS and CSS to your MoonShine layout's assets() method:

Note: The built-in Image Editor Settings page automatically registers these assets when loaded, so you only need this step if you want the editor modal available on other pages (e.g., Media Manager).

2. Render the editor modal

Add the modal to your layout's getContentComponents() method:

Alternatively, the legacy static helper still works:

The "Edit Image" button automatically appears in the Media Manager for image files. The listeners for upload optimization and delete cleanup are registered automatically — no additional setup required.

3. Image driver (recommended)

For best PNG optimization, install the Imagick PHP extension:

The package auto-detects the driver — if Imagick is available it will be used, otherwise GD. You can also configure it explicitly in config/image.php:

Note: GD cannot optimize PNG effectively — it often makes files larger. Imagick is strongly recommended for PNG support.

Configuration

Settings can be managed from the MoonShine admin panel (recommended) or via the config file. Database settings override config values at runtime.

Publish the config file (optional):

Config Options

Localization

Translations are loaded from the package automatically. Supported languages:

• en — English (default)
• ru — Russian

To override translations, publish them:

Files will be published to lang/vendor/image-editor/en/ and lang/vendor/image-editor/ru/.

How It Works

Image Editor

1. User clicks the "Edit Image" button in Media Manager
2. A modal opens with the format selector toolbar and Filerobot Image Editor
3. The format selector defaults to the original image format
4. User edits the image (crop, filters, text, etc.)
5. On save, the selected format is used — image is uploaded to the same directory as the original
6. If overwrite_original is false (default), the file is saved with a -edited suffix
7. Post-save: optimization runs, WebP/AVIF generated if enabled
8. Size comparison: if optimized/conversion is larger → smaller version is kept

Automatic Upload Optimization

When a user uploads an image through the Media Manager:

1. MediaManagerFileUploaded event fires
2. OptimizeUploadedImage listener detects image files (jpg, png, gif, webp, avif)
3. Image is optimized (strip metadata, resize if configured)
4. WebP/AVIF versions generated if enabled
5. Supports queue for async processing

Automatic Delete Cleanup

When a user deletes an image through the Media Manager:

1. MediaManagerFileDeleted event fires
2. DeleteImageConversions listener finds associated .webp and .avif files
3. Conversion files are removed automatically

Size Comparison Logic

Admin Settings Page

The package adds a "Image Editor Settings" page to the MoonShine sidebar with two tabs:

Settings Tab

Configure optimization and conversion parameters stored in the database:

• Quality — JPG, WebP, AVIF quality (1–100)
• Conversion — enable/disable WebP and AVIF generation
• Optimization — strip metadata, max width/height
• Queue — enable async processing, delay

Settings are applied to the config at runtime on each request, so changes take effect immediately without editing config files.

Batch Optimization Tab

Re-process existing images with current settings:

1. Choose filter: All images (recreate conversions) or Only without conversions (skip files that already have webp/avif)
2. Scan files — shows count of matching originals (jpg/png/gif)
3. Start processing — runs via Laravel Bus::batch on the images queue
4. Real-time progress bar with processed/total counter
5. Detailed log showing per-file results:
   • Original: photo.jpg (100 KB → 95 KB, -5%)
   • WebP conversion: → photo.webp (95 KB → 50 KB, -47.4%, vs original)
   • AVIF conversion: → photo.avif (50 KB → 30 KB, -40%, vs webp)
   • Automatic deletion: → photo.webp deleted (larger than original)

Queue Worker Setup

For batch processing (and async optimization), run a queue worker:

For production, use Supervisor to keep the worker running:

Format Conversion Flow

Filerobot always exports PNG regardless of the user's format choice. The server handles format conversion:

• PNG → PNG: re-encode to optimize file size (requires Imagick for effective compression)
• PNG → JPG: convert with configurable quality, progressive encoding, metadata stripping
• JPG → PNG: convert to lossless format
• Same format: optimize only (strip metadata, resize if configured)

Artisan Commands

Security

All controller endpoints are protected by MoonShine auth middleware. Additionally:

• Settings whitelist — only predefined keys are accepted (quality, convert, optimize, queue), unknown keys are silently ignored
• Path traversal protection — ../ and url-encoded variants are rejected in source paths
• File type validation — only image extensions (jpg, jpeg, png, gif, webp, avif) are processed
• Batch limit — max 500 files per batch operation
• Settings validation — quality values clamped to 1–100, dimensions capped at 10000px, types enforced

Publishing

Note: Migrations run automatically from the package via loadMigrationsFrom() when you run php artisan migrate. If you need to customize them or prefer having them in your project's database/migrations/ directory, publish them explicitly:

License

MIT

Related

This package uses Intervention Image for server-side image processing (optimization, format conversion, WebP/AVIF generation).