Download the PHP package ibrahim-kaya/imageman without Composer
On this page you can find all versions of the php package ibrahim-kaya/imageman. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package imageman
ImageMan
Professional Laravel image upload, processing and multi-disk management package.
πΉπ· TΓΌrkΓ§e dokΓΌmantasyon iΓ§in README.tr.md dosyasΔ±na bakΔ±n
Features
- WebP & AVIF conversion β Auto-convert any uploaded image to WebP or AVIF on the fly
- Multi-size variants β Generate thumbnail, medium, large and custom size presets in one pass
- Multi-disk support β Switch between
local,s3,ftp,sftp, GCS and any Flysystem driver - Duplicate detection β SHA-256 hash-based deduplication with
reuse,throworallowmodes - Watermarking β Apply logo or text watermarks with configurable position and opacity
- LQIP placeholders β Generate base64 blur placeholders for smooth lazy-loading transitions
- EXIF stripping β Remove GPS coordinates and device info to protect user privacy
- CDN integration β Built-in URL generators for Imgix, Cloudinary, ImageKit and Cloudflare Images
- Event system β
ImageUploaded,ImageProcessed,ImageDeletedevents for reactive workflows - Queue support β Dispatch image processing to a background queue for fast HTTP responses
- HasImages trait β Drop into any Eloquent model for instant upload/retrieve/delete support
- Artisan commands β
imageman:regenerate,imageman:clean,imageman:convert - Blade directives β
@image,@responsiveImage,@lazyImage - API Resource β Ready-made
ImageResourcefor JSON API responses - Filament v3 β Form component and table column for the Filament admin panel
- Laravel Nova β Custom field for the Nova admin panel
- Fluent API β Chainable builder that reads like plain English
Requirements
| Dependency | Version |
|---|---|
| PHP | ^8.1 |
| Laravel | ^10.0 | ^11.0 |
| Intervention Image | ^3.0 |
Optional (for admin panel integrations):
filament/filament^3.0laravel/nova^4.0
Installation
1. Install via Composer:
2. Publish the config file:
3. Publish and run migrations:
The imageman_images table will be created in your database.
Configuration
After publishing, edit config/imageman.php. Every option is documented with an inline comment in the file. Key settings:
| Key | Default | Description |
|---|---|---|
disk |
local |
Default filesystem disk (env: IMAGEMAN_DISK) |
path |
images |
Storage directory prefix (env: IMAGEMAN_PATH) |
format |
webp |
Output format: webp, avif, jpeg, original |
webp_quality |
80 |
WebP encoding quality (1β100) |
avif_quality |
70 |
AVIF encoding quality (1β100) |
default_sizes |
['thumbnail','medium'] |
Size presets generated for every upload |
detect_duplicates |
true |
Enable SHA-256 duplicate detection |
on_duplicate |
reuse |
reuse / throw / allow |
queue |
false |
Process images in a background queue |
url_generator |
default |
default, imgix, cloudinary, imagekit, cloudflare |
generate_lqip |
true |
Generate blur placeholder data URIs |
strip_exif |
true |
Strip EXIF metadata for privacy |
Basic Usage
Upload an image
Retrieve and delete
Upload from URL
The uploadFromUrl() method downloads the remote image and passes it through the same processing pipeline as a regular upload (WebP conversion, resizing, watermarking, etc.):
Error handling:
Fluent API Reference
All methods return $this (except save() which returns an Image model).
| Method | Description |
|---|---|
->disk('s3') |
Override the storage disk |
->collection('gallery') |
Set the collection name |
->sizes(['thumbnail','large']) |
Choose which size presets to generate |
->withOriginal() |
Also keep the unmodified original file |
->for($model) |
Associate with an Eloquent model |
->meta(['alt' => 'β¦']) |
Attach metadata (alt text, title, etc.) |
->format('avif') |
Override output format for this upload |
->filename('my-photo') |
Custom filename stem (slugified, no extension needed) |
->inDirectory('products') |
Store inside a custom subdirectory |
->noUuid() |
Omit UUID folder for a deterministic, stable path |
->watermark() |
Enable watermark (overrides config) |
->noWatermark() |
Disable watermark for this upload |
->watermarkImage($path) |
Use a specific image file as watermark |
->watermarkText('Β© 2024') |
Use a text string as watermark |
->withLqip() |
Enable LQIP generation |
->withoutLqip() |
Disable LQIP generation |
->replaceExisting() |
Delete old images in the collection after saving |
->keepExisting() |
Keep old images even if collection is singleton |
->maxSize(2048) |
Max file size in KB |
->minWidth(400) |
Minimum width in pixels |
->maxWidth(2000) |
Maximum width in pixels |
->aspectRatio('16/9') |
Enforce aspect ratio |
->save() |
Execute and return Image model |
Size Variants
Define named presets in config/imageman.php:
Retrieve by name:
Disk Management
Switch disk per upload β no config change needed:
Make sure the target disk is configured in config/filesystems.php.
Custom Filename & Directory
Custom filename
Set a custom filename stem for the stored file. The extension is always determined automatically from the output format β do not include it:
Turkish characters and spaces are automatically slugified:
Custom directory
Group images into a subdirectory without changing the base path config:
Each directory segment is slugified automatically:
Deterministic paths with ->noUuid()
By default every upload gets its own UUID folder to prevent collisions. Call ->noUuid() to omit it and get a fully stable, predictable URL β ideal for profile photos and cover images:
Note: When
noUuid()is active, uploading to the same path again silently overwrites the existing file. Combine with->replaceExisting()(or singleton collections) to also clean up the old database record.
Path composition table
inDirectory() |
noUuid() |
filename() |
Result |
|---|---|---|---|
| β | β | β | images/{uuid}/{uuid}.webp |
'products' |
β | β | images/products/{uuid}/{uuid}.webp |
'products' |
β | 'iphone' |
images/products/{uuid}/iphone.webp |
'users/42' |
β | 'avatar' |
images/users/42/avatar.webp |
'products' |
β | β | images/products/{uuid}.webp |
WebP & AVIF Conversion
Change format globally (in .env or config):
Or per upload:
Watermarking
Global config
Set a default watermark for all uploads in config/imageman.php:
Per-upload: image watermark
Override the watermark image on a single upload without touching the config file:
Per-upload: text watermark
Enable / disable for a single upload
Priority rules
| Method called | Result |
|---|---|
->watermarkImage($path) |
Enables watermark, uses given image |
->watermarkText($text) |
Enables watermark, uses given text |
->watermark() |
Enables watermark, keeps config type/path/text |
->noWatermark() |
Disables watermark for this upload |
| (none) | Falls back entirely to config/imageman.php |
Duplicate Detection
When the same file is uploaded twice, ImageMan checks the SHA-256 hash:
| Mode | Behaviour |
|---|---|
reuse |
Returns the existing Image model. No new file stored. |
throw |
Throws DuplicateImageException with a reference to the existing image. |
allow |
Creates a new record regardless. |
Handle the exception:
Singleton Collections
A singleton collection holds exactly one image per model instance. When a new image is uploaded to a singleton collection, all previously stored images in that collection for the same model are automatically deleted after the new image has been successfully saved β so the model is never left without an image during the transition.
Option 1 β Config-based (always singleton)
List the collection names in config/imageman.php:
Any upload to those collections will automatically replace the previous one β no extra method call needed:
Option 2 β Per-upload with ->replaceExisting()
Use the fluent method to opt in on a single upload:
Option 3 β HasImages trait with replace option
Override: keeping multiple images in a singleton collection
Call ->keepExisting() to opt out of automatic replacement even when the collection is listed in config:
How it works
| Scenario | Result |
|---|---|
replaceExisting() + model set |
Old images in collection deleted after new save |
keepExisting() |
Old images kept regardless of config |
replaceExisting() + no model |
Silently ignored (no scope to delete within) |
| Different collection on same model | Untouched |
| Same collection on different model instance | Untouched |
Safety guarantee: Old images are only deleted after the new image has been fully written to disk and the database record has been committed. If processing fails before that point, the old image remains intact.
LQIP & Lazy Loading
Access the blur placeholder:
Use in Blade with the @lazyImage directive:
Renders:
Add lazysizes to your front-end for the blur-to-sharp transition.
EXIF Stripping
Enabled by default. Strips GPS coordinates, device model, and all other EXIF metadata before saving:
Upload Validation
Set global rules in config:
Or apply rules fluently per upload:
Model Integration (HasImages Trait)
Add the trait to any Eloquent model:
Methods available
Event System
Listen to ImageMan events in your EventServiceProvider:
Event payloads:
Queue Processing
Enable background processing to keep upload responses fast:
Start the worker:
When queue is enabled, save() inserts the DB record immediately (so you get an ID back) and dispatches ProcessImageJob. Variants are available once the job completes β listen to ImageProcessed to know when they are ready.
Chunked Uploads
Upload files larger than PHP's upload_max_filesize limit by splitting them into small chunks in the browser and reassembling them on the server. All chunks are fed through the standard ImageUploader pipeline (WebP/AVIF conversion, size variants, watermark, LQIP, queue, etc.) once assembly is complete.
Enable chunk routes
Chunk routes are enabled by default (config('imageman.chunks.enabled') = true). They are always loaded when chunk support is on β regardless of the register_routes setting.
If you want to add authentication middleware to chunk endpoints:
JavaScript helper
Publish the bundled ImageManUploader class to your public/ directory:
The file is a UMD bundle β it works as a plain <script> tag, an ES module import, or a CommonJS require().
Script tag
ES module (Vite / webpack)
CommonJS (Node / older bundlers)
Resumable uploads
Store the upload_id returned at initiation (e.g. in localStorage) so that if the page is refreshed or the browser closes mid-upload, the session can be resumed β only the missing chunks are re-sent:
Abort an upload
HTTP API reference
| Method | URL | Description |
|---|---|---|
POST |
/imageman/chunks/initiate |
Start a new session, get upload_id |
POST |
/imageman/chunks/{id} |
Upload one chunk (multipart) |
GET |
/imageman/chunks/{id}/status |
Poll assembly status |
DELETE |
/imageman/chunks/{id} |
Abort and delete all chunk files |
Initiate request body (JSON or form-data):
| Field | Type | Required | Description |
|---|---|---|---|
filename |
string | yes | Original file name |
mime_type |
string | yes | MIME type (must be in allowed_mimes) |
total_size |
integer | yes | Full file size in bytes |
total_chunks |
integer | yes | Number of chunks the file is split into |
collection |
string | no | Target collection (default: "default") |
disk |
string | no | Target storage disk |
meta |
object | no | Arbitrary metadata |
imageable_type |
string | no | Eloquent model FQCN for polymorphic link |
imageable_id |
integer | no | Eloquent model primary key |
Status response fields: status, received_chunks, missing_chunks, total_chunks, image_id, error_message.
Status values: uploading β assembling β processing (queued) β complete / failed.
Queue assembly
Set assemble_on_queue in config (or inherit from imageman.queue) to run chunk assembly in the background:
Poll GET /imageman/chunks/{id}/status until status === 'complete' β the JS helper does this automatically.
Clean stale sessions
Chunk files are stored under storage/app/imageman_chunks/{upload_id}/. Use the included Artisan command to remove sessions that were abandoned:
Schedule it in App\Console\Kernel:
Artisan Commands
Regenerate variants
Re-run size generation for existing images. Useful after adding a new size preset:
Clean orphaned images
Remove images with no associated model:
Bulk format conversion
Convert stored images to a new format (e.g. after changing config.format):
CDN Integration
Imgix
Cloudinary
ImageKit
Cloudflare Images
Custom URL Generator
Implement UrlGeneratorContract and reference your class:
Blade Directives
@image β Single variant
Renders:
@responsiveImage β srcset
Renders:
@lazyImage β LQIP lazy load
Renders an <img> with src set to the LQIP placeholder and data-src pointing to the full image, ready for lazysizes.
API Resource
Use in controllers to return a consistent JSON structure:
Example JSON output:
Filament v3 Integration
Register the plugin in your panel provider:
Form component
Table column
Laravel Nova Integration
Private Disk Routes
To serve images stored on a private disk through your Laravel app, enable the optional routes:
Two endpoints become available:
| Route | Description |
|---|---|
GET /imageman/{id}/{variant?} |
Proxy-stream the image through PHP |
GET /imageman/{id}/{variant?}/sign |
Redirect to a signed temporary URL (S3/GCS) |
Temporary Signed URLs
For private disks (S3, GCS, Azure Blob):
Testing
The package ships with an Orchestra Testbench-based test suite:
Testing in your own application
Use Storage::fake() and the fakeImageFile() helper pattern:
Contributing
Pull requests are welcome. Please:
- Fork the repository and create a branch from
main. - Write tests covering your change.
- Ensure
./vendor/bin/phpunitpasses with no failures. - Follow PSR-12 code style.
- Submit a pull request with a clear description of the change.
License
The MIT License (MIT). See LICENSE for details.
All versions of imageman with dependencies
illuminate/support Version ^9.0|^10.0|^11.0|^12.0
illuminate/database Version ^9.0|^10.0|^11.0|^12.0
illuminate/filesystem Version ^9.0|^10.0|^11.0|^12.0
illuminate/queue Version ^9.0|^10.0|^11.0|^12.0
illuminate/http Version ^9.0|^10.0|^11.0|^12.0
intervention/image Version ^3.0