README

🎭 Restore the beloved mask() and opacity() methods removed in Intervention Image v3

🚀 Why This Package?

With the release of Intervention Image v3, the popular mask() and opacity() methods were removed. This package brings them back as clean, framework-agnostic modifiers that work seamlessly with both GD and Imagick drivers.

✨ Features

• 🎭 Apply masks to images using alpha channels
• 🔮 Control opacity with precise float values (0.0 to 1.0)
• 🖼️ Dual driver support - Works with both GD and Imagick
• ⚡ Zero configuration - Just install and use
• 🧪 Fully tested - 17 tests with 25 assertions
• 📦 Lightweight - No extra dependencies beyond Intervention Image

📦 Installation

composer require dialloibrahima/intervention-image-mask

Requirements

• PHP 8.3 or higher
• Intervention Image 3.0 or higher
• GD or Imagick PHP extension

🎯 Quick Start

Apply a Mask

Use a mask image to define transparency. The mask's alpha channel determines which parts of the original image become transparent.

use DialloIbrahima\InterventionMask\ApplyMask;
use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver;

$manager = new ImageManager(new Driver());

// Load your image and mask
$image = $manager->read('photo.jpg');
$mask = $manager->read('mask.png');

// Apply the mask
$result = $image->modify(new ApplyMask($mask));

// Save the result
$result->toPng()->save('masked-photo.png');

Set Opacity

Control the transparency level of an entire image with a simple float value.

use DialloIbrahima\InterventionMask\SetOpacity;

$image = $manager->read('photo.png');

// 50% opacity
$result = $image->modify(new SetOpacity(0.5));

$result->toPng()->save('semi-transparent.png');

📖 API Reference

ApplyMask

Applies a mask image to define transparency regions.

new ApplyMask(ImageInterface $mask)

How it works:

• White areas (or opaque) in the mask → Image is visible
• Black areas (or transparent) in the mask → Image becomes transparent
• Gray areas → Partial transparency

SetOpacity

Sets the overall opacity level of an image.

new SetOpacity(float $opacity)

Examples:

• 0.0 → Completely invisible
• 0.5 → 50% transparent
• 1.0 → Fully opaque (no change)

💡 Use Cases

🧩 Puzzle Piece Effect

$piece = $manager->read('puzzle-background.jpg');
$shape = $manager->read('puzzle-piece-shape.png');

$puzzlePiece = $piece->modify(new ApplyMask($shape));

🖼️ Image Watermark with Transparency

$watermark = $manager->read('logo.png');
$fadedWatermark = $watermark->modify(new SetOpacity(0.3));

📸 Vignette Effect

$photo = $manager->read('portrait.jpg');
$vignette = $manager->read('vignette-mask.png');

$vintagePhoto = $photo->modify(new ApplyMask($vignette));

🎨 Gradient Fade

$image = $manager->read('landscape.jpg');
$gradientMask = $manager->read('horizontal-gradient.png');

$fadedImage = $image->modify(new ApplyMask($gradientMask));

🔧 Using with Imagick

The package automatically detects and uses the appropriate driver:

use Intervention\Image\Drivers\Imagick\Driver as ImagickDriver;

$manager = new ImageManager(new ImagickDriver());

// Same API - driver is detected automatically
$result = $image->modify(new ApplyMask($mask));

🧪 Testing

composer test

Run static analysis:

composer analyse

Format code with Pint:

composer format

📄 License

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

🙏 Credits

• Ibrahima Diallo
• Inspired by the original Intervention Image v2 implementation

Made with ❤️ for the PHP community