README

A powerful and flexible image processing package for Laravel that provides resizing, compression, format conversion, and watermarking capabilities.

Author

Daiyan Mozumder

Prerequisites

Before installing ImageWiz, make sure your Laravel project has the following:

• PHP 8.0 or higher

• Laravel 8.0 or higher

• GD Library(usually comes with PHP)

Check GD Library Installation

php -m | grep gd

If GD is not installed, Laragon usually has it pre-installed. To check:

1. Open Laragon

2. Click on Menu → PHP → Extras → phpinfo()

3. Search for "GD" in the phpinfo page

Installation

Step 1: Install Intervention Image (Required)

composer require intervention/image

Step 2: Install ImageWiz Package

composer require daiyanmozumder/imagewiz

Step 3: Publish Configuration (Optional)

php artisan vendor:publish --provider="DaiyanMozumder\\ImageWiz\\ImageWizServiceProvider" --tag=imagewiz-config

Configuration

After publishing, you can modify config/imagewiz.php:

return [
    'default_target_kb' => 400,
    'watermark' => [
        'default_size' => 100,
        'default_opacity' => 70,
    ],
    'default_quality' => 90,
];

Quick Start

Basic Usage

use DaiyanMozumder\ImageWiz\Facades\ImageWiz;

// Process image with default settings
$image = ImageWiz::process(public_path('input.jpg'));
$image->save(public_path('output.webp'));

// With resizing and compression
$image = ImageWiz::process(public_path('input.jpg'), [
    'width' => 800,
    'target_kb' => 300
]);
$image->save(public_path('resized.webp'));

// With watermark
$image = ImageWiz::process(public_path('input.jpg'), [
    'watermark_path' => public_path('logo.png'),
    'watermark_size' => 150,    // Size in pixels
    'watermark_opacity' => 60   // Opacity percentage (0-100)
]);
$image->save(public_path('watermarked.webp'));

Complete Tutorial

Basic Usage Examples

Example 1: Simple Image Processing

use DaiyanMozumder\ImageWiz\Facades\ImageWiz;

// Process image with default settings (400kb target, webp format)
$image = ImageWiz::process(public_path('images/input.jpg'));
$image->save(public_path('images/output.webp'));

Example 2: With Custom Resizing

$image = ImageWiz::process(public_path('images/input.jpg'), [
    'width' => 800,
    // Resize to 800px width (maintains aspect ratio)
    'height' => 600,     // Optional: You can specify both or just one
    'target_kb' => 300   // Compress to 300KB
]);
$image->save(public_path('images/resized.webp'));

Example 3: With Watermark

$image = ImageWiz::process(public_path('images/input.jpg'), [
    'watermark_path' => public_path('watermarks/logo.png'),
    'watermark_size' => 150,    // Size in pixels
    'watermark_opacity' => 50   // Opacity percentage (0-100)
]);
$image->save(public_path('images/watermarked.webp'));

Real-World Usage Scenarios

Scenario 1: Handling Form Uploads

Controller Method

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use DaiyanMozumder\ImageWiz\Facades\ImageWiz;
use Illuminate\Support\Str;

class ImageController extends Controller
{
    public function uploadImage(Request $request)
    {
        $request->validate([
            'image' => 'required|image|mimes:jpeg,png,jpg,gif|max:5120',
        ]);

        if ($request->hasFile('image')) {
            $uploadedImage = $request->file('image');
            // Generate unique filename
            $filename = Str::random(20) . '.webp';
            $outputPath = public_path('uploads/' . $filename);

            // Process the uploaded image
            $image = ImageWiz::process($uploadedImage->getPathname(), [
                'width' => 1200,
                'target_kb' => 400,
            ]);
            $image->save($outputPath);

            return response()->json([
                'success' => true,
                'message' => 'Image processed and saved successfully',
                'image_path' => 'uploads/' . $filename
            ]);
        }

        return response()->json([
            'success' => false,
            'message' => 'No image uploaded'
        ], 400);
    }
}

Route Definition

Route::post('/upload-image', [ImageController::class, 'uploadImage']);

Scenario 2: Using Watermark with Logo Image

Simple Watermark Usage

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use DaiyanMozumder\ImageWiz\Facades\ImageWiz;

class WatermarkController extends Controller
{
    public function addWatermarkToImage(Request $request)
    {
        $request->validate([
            'image' => 'required|image|mimes:jpeg,png,jpg,gif',
        ]);

        $uploadedImage = $request->file('image');
        // Generate output filename
        $filename = 'watermarked_' . time() . '.webp';
        $outputPath = public_path('processed/' . $filename);

        // Process image with watermark
        $image = ImageWiz::process($uploadedImage->getPathname(), [
            'width' => $request->width ?? 800,
            'target_kb' => $request->target_kb ?? 400,
            'watermark_path' => public_path('assets/logo.png'), // Your logo path
            'watermark_size' => $request->watermark_size ?? 200, // Size as number
            'watermark_opacity' => $request->watermark_opacity ?? 60 // Opacity as number
        ]);
        $image->save($outputPath);

        return response()->json([
            'success' => true,
            'message' => 'Image processed with watermark',
            'image_path' => 'processed/' . $filename
        ]);
    }

    public function processWithCustomWatermark(Request $request)
    {
        $request->validate([
            'image' => 'required|image',
            'logo' => 'required|image', // Upload logo dynamically
        ]);

        $uploadedImage = $request->file('image');
        $logoImage = $request->file('logo');

        // Save logo temporarily
        $logoPath = $logoImage->store('temp', 'public');
        $fullLogoPath = storage_path('app/public/' . $logoPath);

        $filename = 'custom_watermark_' . time() . '.webp';
        $outputPath = public_path('uploads/' . $filename);

        // Process with dynamic watermark
        $image = ImageWiz::process($uploadedImage->getPathname(), [
            'watermark_path' => $fullLogoPath,
            'watermark_size' => $request->size ?? 150,    // Number: 150
            'watermark_opacity' => $request->opacity ?? 70 // Number: 70
        ]);
        $image->save($outputPath);

        // Clean up temporary logo
        unlink($fullLogoPath);

        return response()->json([
            'success' => true,
            'image_path' => 'uploads/' . $filename
        ]);
    }
}

Scenario 3: Batch Processing Multiple Images

public function processMultipleImages(Request $request)
{
    $request->validate([
        'images.*' => 'image|mimes:jpeg,png,jjpg,gif',
    ]);

    $processedImages = [];

    foreach ($request->file('images') as $uploadedImage) {
        $filename = 'batch_' . time() . '_' . Str::random(10) . '.webp';
        $outputPath = public_path('batch_processed/' . $filename);

        $options = [
            'width' => 1200,
            'target_kb' => 500,
        ];

        // Add watermark if provided
        if ($request->has('watermark_path')) {
            $options['watermark_path'] = $request->watermark_path;
            $options['watermark_size'] = $request->watermark_size ?? 100;
            $options['watermark_opacity'] = $request->watermark_opacity ?? 70;
        }

        $image = ImageWiz::process($uploadedImage->getPathname(), $options);
        $image->save($outputPath);

        $processedImages[] = [
            'filename' => $filename,
            'path' => 'batch_processed/' . $filename,
            'size' => filesize($outputPath)
        ];
    }

    return response()->json([
        'success' => true,
        'message' => count($processedImages) . ' images processed successfully',
        'images' => $processedImages
    ]);
}

Advanced Usage

Getting Encoded Data for API Responses

public function getImageData(Request $request)
{
    $image = ImageWiz::process(public_path('images/sample.jpg'), [
        'width' => 800,
        'target_kb' => 200
    ]);

    $webpData = $image->encodeToWebp(85);

    return response($webpData)
        ->header('Content-Type', 'image/webp')
        ->header('Content-Disposition', 'inline; filename="processed.webp"');
}

Custom Compression Settings

// Aggressive compression for small file size
$image = ImageWiz::process($imagePath, [
    'target_kb' => 100, // Very small file size
]);

// High quality with larger file size
$image = ImageWiz::process($imagePath, [
    'target_kb' => 1000, // 1MB file size
]);

Watermark with Different Positions

// Simple watermark with custom size and opacity
$image = ImageWiz::process('input.jpg', [
    'watermark_path' => 'logo.png',
    'watermark_size' => 200,    // Size as number
    'watermark_opacity' => 60   // Opacity as number (0-100)
]);

// Without watermark
$image = ImageWiz::process('input.jpg', [
    'width' => 800,
    'target_kb' => 400
    // No watermark_path provided = no watermark
]);

Available Methods

Main Processing Method

ImageWiz::process(string $imagePath, array $options = [])

Options Parameters

• width(int|null): Target width for resizing (maintains aspect ratio)

• height(int|null): Target height for resizing (maintains aspect ratio)

• target_kb(int): Target file size in KB (default: 400)

• watermark_path(string|null): Path to watermark image file

• watermark_size(int): Watermark size in pixels (default: 100)

• watermark_opacity(int): Watermark opacity 0-100 (default: 70)

Additional Methods

// Save processed image
$image->save(string $outputPath, int $quality = 90);

// Get encoded webp data
$webpData = $image->encodeToWebp(int $quality = 90);

// Get Intervention Image instance
$interventionImage = $image->getImage();

Error Handling

try {
    $image = ImageWiz::process($imagePath, [
        'width' => 800,
        'target_kb' => 400,
        'watermark_path' => $watermarkPath
    ]);
    $image->save($outputPath);
} catch (\Exception $e) {
    // Handle errors (file not found, invalid image, etc.)
    logger()->error('Image processing failed: ' . $e->getMessage());
    return response()->json([
        'success' => false,
        'message' => 'Image processing failed: ' . $e->getMessage()
    ], 500);
}

Best Practices

1. Always validate uploaded imagesbefore processing

2. Use try-catch blocksfor error handling

3. Store images in public directoryor configure proper storage

4. Consider filesystem permissionsfor output directories

5. Use unique filenamesto avoid conflicts

6. Clean up temporary filesif created

Watermark Parameters Explained

// watermark_size: Number representing width in pixels
// The height will be adjusted automatically to maintain aspect ratio
'watermark_size' => 200, // Logo will be 200px wide

// watermark_opacity: Number between 0-100 representing opacity percentage
'watermark_opacity' => 60, // 60% opacity

// Example usage:
$image = ImageWiz::process('photo.jpg', [
    'watermark_path' => 'company-logo.png',
    'watermark_size' => 150,    // Simple number
    'watermark_opacity' => 75   // Simple number
]);

Troubleshooting

Common Issues:

1. "File not found" error: Check file paths and permissions

2. GD library not installed: Install php-gd package

3. Memory exhaustion: Process smaller images or increase memory limit

4. Permission denied: Check directory write permissions

Increasing Memory Limit (if needed):

// In your controller or middleware
ini_set('memory_limit', '256M');

Support

For issues and questions, please contact:Daiyan Mozumder

License

MIT License

Quick Start Summary:

composer require intervention/image
composer require daiyanmozumder/imagewiz

Then use in your controller:

$image = ImageWiz::process($uploadedImage->getPathname(), [
    'width' => 800,
    'target_kb' => 400,
    'watermark_path' => public_path('logo.png'),
    'watermark_size' => 200,
    'watermark_opacity' => 60
]);
$image->save('output.webp');