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)

Parameter	Type	Description
`$mask`	`ImageInterface`	The mask image. Its alpha channel defines transparency.

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)

Parameter	Type	Description
`$opacity`	`float`	Opacity level from 0.0 (fully transparent) to 1.0 (fully opaque)

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

dialloibrahima / intervention-image-mask

Maintainers

Details