PHPackages daiyanmozumder/image-wizard - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Queues & Workers](/categories/queues) 4. / 5. daiyanmozumder/image-wizard ActiveLibrary[Queues & Workers](/categories/queues) daiyanmozumder/image-wizard =========================== Enterprise Laravel Image Processing Package powered by Python v1.0.2(2w ago)06MITPHPPHP ^8.1|^8.2|^8.3 Since Jun 27Pushed 2w agoCompare [ Source](https://github.com/DaiyanMozumder/image-wizard)[ Packagist](https://packagist.org/packages/daiyanmozumder/image-wizard)[ RSS](/packages/daiyanmozumder-image-wizard/feed)WikiDiscussions main Synced 2w ago READMEChangelogDependencies (10)Versions (4)Used By (0) [![Image Wizard](https://raw.githubusercontent.com/daiyanmozumder/image-wizard/main/art/logo.png)](https://raw.githubusercontent.com/daiyanmozumder/image-wizard/main/art/logo.png) **Enterprise Laravel Image Processing powered by Python** [![Latest Version on Packagist](https://camo.githubusercontent.com/0d492140efcb75fc6a28bff9f46360caf99c9912960bb8c522a83732b6e928d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64616979616e6d6f7a756d6465722f696d6167652d77697a6172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/daiyanmozumder/image-wizard) [![Total Downloads](https://camo.githubusercontent.com/84814d076e639464cd979ec2ce2947f6b46339ce6a4c40724efe5ddc456ed969/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f64616979616e6d6f7a756d6465722f696d6167652d77697a6172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/daiyanmozumder/image-wizard) [![PHP Version Require](https://camo.githubusercontent.com/d68c43b7765c1931a45e4e26e132a2eecdb9cb8c74a57971da466df83b0c6581/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f64616979616e6d6f7a756d6465722f696d6167652d77697a6172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/daiyanmozumder/image-wizard) [![License](https://camo.githubusercontent.com/40280856210c46450b6b1fd2f7121d287601ffad98171eb458371ed26a850221/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d737563636573732e7376673f7374796c653d666c61742d737175617265)](https://opensource.org/licenses/MIT) --- **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 ---------- [](#-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 -------------- [](#-requirements) - PHP 8.1+ - Laravel 10.0, 11.0, or 12.0+ - Python 3+ - Pillow (`pip install Pillow>=10.0.0`) --- 🚀 Installation -------------- [](#-installation) 1. Require the package via Composer: ``` composer require daiyanmozumder/image-wizard ``` 2. Publish the configuration file: ``` php artisan vendor:publish --tag=image-wizard-config ``` 3. Ensure you have Python and the Pillow library installed on your server/environment: ``` pip install Pillow ``` --- ⚙️ Configuration ---------------- [](#️-configuration) Open `config/image-wizard.php`. Here you can define default formats, compression quality, queue settings, and responsive variant presets. ``` return [ 'default_format' => 'webp', // Convert everything to webp by default 'python' => [ 'executable' => env('IMAGE_WIZARD_PYTHON_EXECUTABLE', 'python3'), 'timeout' => 60, // Maximum execution time in seconds ], 'quality' => [ 'jpeg' => 80, 'webp' => 80, 'avif' => 50, ], 'variants' => [ 'thumbnail' => ['width' => 150, 'height' => 150, 'fit' => 'crop'], 'medium' => ['width' => 800, 'height' => 800, 'fit' => 'contain'], 'large' => ['width' => 1200, 'height' => 1200, 'fit' => 'contain'], ], ]; ``` --- 🌐 Setting up Python on cPanel ----------------------------- [](#-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): ``` python3 -m venv --without-pip ~/image_wizard_env ``` 3. **Activate the environment**: ``` source ~/image_wizard_env/bin/activate ``` 4. **Install `pip` and `Pillow`**: - *For Python 3.10+*: ``` curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py python get-pip.py rm get-pip.py pip install Pillow ``` - *For Python 3.9*: ``` curl https://bootstrap.pypa.io/pip/3.9/get-pip.py -o get-pip.py python get-pip.py rm get-pip.py pip install Pillow ``` 5. **Set the executable path in your Laravel `.env`**: ``` IMAGE_WIZARD_PYTHON_EXECUTABLE=/home/YOUR_CPANEL_USERNAME/image_wizard_env/bin/python ``` 6. **Clear your Laravel config cache**: ``` php artisan config:clear ``` --- 📖 Usage Guide ------------- [](#-usage-guide) ### Basic Processing [](#basic-processing) Chain commands together effortlessly. Execution is delayed until you call `save()`, allowing for clean architecture. ``` use ImageWizard; ImageWizard::load('public/uploads/raw.jpg') ->resize(800, 600, 'cover') ->format('webp') ->quality(85) ->save('public/images/optimized.webp'); ``` ### Advanced Resizing (Fit Strategies) [](#advanced-resizing-fit-strategies) Pass a fit strategy as the third argument to `resize()` to control how the image scales. ``` ImageWizard::load('image.jpg') ->resize(500, 500, 'contain') // (Default) Scale to fit within bounds // ->resize(500, 500, 'cover') // Scale to fill bounds exactly, cropping overflow // ->resize(500, 500, 'stretch') // Ignore aspect ratio, force to exact dimensions // ->resize(500, 500, 'pad') // Fit within bounds, adding transparent/white padding ->save('output.jpg'); ``` ### Watermarks [](#watermarks) Overlay logos onto your images with intelligent scaling, automatic cropping for wide logos, CSS-like positioning, opacity, and dynamic margins. ``` ImageWizard::load('photo.jpg') ->watermark('logo.png', [ 'position' => 'bottom-right', // CSS-like positioning: top-left, center, bottom-right, etc. 'opacity' => 0.6, // 60% opacity (0.0 to 1.0) 'size_ratio' => 0.12, // Auto-scales watermark to 12% of main image's smaller dimension (default: 0.12) 'margin' => 20, // Explicit margin offset in px (auto-calculated as 3% min 10px if omitted) ]) ->save('photo-watermarked.jpg'); ``` #### Smart Watermark Features: [](#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) [](#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. ``` ImageWizard::fromDisk('s3', 'raw-uploads/user.jpg') ->resize(1200) ->watermark('watermark.png') ->toDisk('s3', 'optimized/user.jpg'); ``` ### Background Processing (Queues) [](#background-processing-queues) Processing large 4K images blocks the PHP thread. Use `queue()` to dispatch a background job instantly instead of `save()`. ``` // Instantly returns a response to the user ImageWizard::load('massive-raw-file.tiff') ->format('avif') ->resize(2000) ->queue('public/optimized.avif'); ``` ### Automatic Responsive Variants [](#automatic-responsive-variants) Instead of manually creating multiple sizes, use your config presets to generate them all at once. ``` ImageWizard::load('hero.png') ->generateVariants('public/hero.jpg', ['thumbnail', 'medium', 'large']); ``` This generates: - `public/hero-thumbnail.jpg` - `public/hero-medium.jpg` - `public/hero-large.jpg` ### Batch Processing [](#batch-processing) Apply a strict pipeline to an entire array of files. ``` $files = ['img1.jpg', 'img2.png', 'img3.webp']; ImageWizard::resize(500, 500, 'crop') ->format('webp') ->batch($files, 'public/batch-output/'); ``` ### Preserving Metadata (EXIF) [](#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: ``` ImageWizard::load('photo.jpg') ->preserveMetadata() ->save('photo-preserved.jpg'); ``` --- 🛠️ Troubleshooting ------------------ [](#️-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 ----------- [](#️-security) If you discover any security related issues, please email `hello@example.com` instead of using the issue tracker. 📄 License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 42 — FairBetter than 88% of packages Maintenance97 Actively maintained with recent releases Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~15 days Total 3 Last Release 15d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/0306cc63f1bc4923a2db180a4874181070fa930957dc8b8b032ec89fb4c4f3b9?d=identicon)[MiltonDaiyan](/maintainers/MiltonDaiyan) --- Top Contributors [![DaiyanMozumder](https://avatars.githubusercontent.com/u/108240573?v=4)](https://github.com/DaiyanMozumder "DaiyanMozumder (4 commits)") --- Tags laravelimageprocessingwatermarkqueuebatchoptimizationpythonpillowWebpavif ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/daiyanmozumder-image-wizard/health.svg) ``` [![Health](https://phpackages.com/badges/daiyanmozumder-image-wizard/health.svg)](https://phpackages.com/packages/daiyanmozumder-image-wizard) ``` ### Alternatives [laravel/horizon Dashboard and code-driven configuration for Laravel queues. 4.2k99.8M350](/packages/laravel-horizon)[illuminate/queue The Illuminate Queue package. 20433.0M1.8k](/packages/illuminate-queue)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 79227.1M213](/packages/laravel-mcp)[spatie/laravel-health Monitor the health of a Laravel application 88212.7M185](/packages/spatie-laravel-health)[illuminate/console The Illuminate Console package. 13046.6M7.2k](/packages/illuminate-console)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)