Download the PHP package daiyanmozumder/image-wizard without Composer

Enterprise Laravel Image Processing powered by Python

Image Wizard is an enterprise-grade Laravel image processing package. Instead of relying on PHP's memory-hungry GD/Imagick libraries, it bridges Laravel to a high-performance Python engine powered by the Pillow library.

Laravel handles the orchestration, fluent API, and background queueing, while Python executes the heavy CPU-bound image manipulation.

✨ Features

• Blazing Fast: Image processing runs in an isolated Python process. No more Allowed memory size exhausted errors in PHP!
• Fluent API: Clean, intuitive, and chainable syntax (->resize()->watermark()->save()).
• Laravel Queues: Send massive batch jobs to the background instantly with ->queue().
• Cloud Storage (S3): Seamlessly pull/push to AWS S3 or Local disks with ->fromDisk() and ->toDisk().
• Variant Generator: Automatically spawn thumbnail, medium, and large responsive variants based on config presets.
• Watermark Engine: Apply image watermarks with CSS-like positioning, alpha opacity, automatic wide-logo cropping, smart dynamic rescaling, and auto-margins.
• Next-Gen Formats: Built-in support for converting to WebP and AVIF.

📦 Requirements

• PHP 8.1+
• Laravel 10.0, 11.0, or 12.0+
• Python 3+
• Pillow (pip install Pillow>=10.0.0)

🚀 Installation

1. Require the package via Composer:

2. Publish the configuration file:

3. Ensure you have Python and the Pillow library installed on your server/environment:

⚙️ Configuration

Open config/image-wizard.php. Here you can define default formats, compression quality, queue settings, and responsive variant presets.

🌐 Setting up Python on cPanel

On cPanel hosting environments, do not use cPanel's "Setup Python App" GUI web application tool (as it overrides your domain's web traffic with Python WSGI instead of serving your Laravel PHP application).

Instead, create a standalone command-line Python virtual environment via cPanel Terminal / SSH:

1. Open cPanel Terminal (under Advanced) or connect via SSH.

2. Create a Python virtual environment (--without-pip prevents ensurepip errors common on cPanel):

3. Activate the environment:

4. Install pip and Pillow:

   • For Python 3.10+:

   • For Python 3.9:

5. Set the executable path in your Laravel .env:

6. Clear your Laravel config cache:

📖 Usage Guide

Basic Processing

Chain commands together effortlessly. Execution is delayed until you call save(), allowing for clean architecture.

Advanced Resizing (Fit Strategies)

Pass a fit strategy as the third argument to resize() to control how the image scales.

Watermarks

Overlay logos onto your images with intelligent scaling, automatic cropping for wide logos, CSS-like positioning, opacity, and dynamic margins.

Smart Watermark Features:

• Aspect Ratio Crop (Wide Logos): If a logo has an aspect ratio width / height > 1.5 (e.g. logo with company text), Image Wizard automatically crops (0, 0, height, height) to isolate the left square icon mark.
• Smart Dynamic Rescaling: Automatically resizes the watermark relative to the target image (size_ratio, default 12%), so watermarks stay proportionally sized on high-res and low-res photos alike.
• Smart Dynamic Margin: If no margin is provided, margin is auto-calculated as 3% of the target image's smaller dimension (minimum 10px).

Cloud Storage (AWS S3)

Image Wizard integrates natively with Laravel's Storage facade. It automatically streams files from S3 to a local temp folder, processes them via Python, streams them back to S3, and cleans up the temp files.

Background Processing (Queues)

Processing large 4K images blocks the PHP thread. Use queue() to dispatch a background job instantly instead of save().

Automatic Responsive Variants

Instead of manually creating multiple sizes, use your config presets to generate them all at once.

This generates:

• public/hero-thumbnail.jpg
• public/hero-medium.jpg
• public/hero-large.jpg

Batch Processing

Apply a strict pipeline to an entire array of files.

Preserving Metadata (EXIF)

By default, EXIF data (GPS, camera info) is stripped to optimize file size. If you are building a photography portfolio, preserve it easily:

🛠️ Troubleshooting

• Python execution failed / File not found: Ensure python or python3 is available in your server's $PATH. If using Docker or a specific environment, update the executable path in config/image-wizard.php.

• JSON Decode Error: The PHP bridge expects strict JSON from Python. If you have modified the Python environment to print debug warnings to stdout, it will break the bridge. Ensure your Python script runs silently.

• Missing Pillow: If you get an internal engine error mentioning PIL, run pip install Pillow on your host machine.

🛡️ Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

📄 License

The MIT License (MIT). Please see License File for more information.