Fix watermark transparency with the ImageMagick adapter

[sebfie]

Description (*)

Magento\Framework\Image\Adapter\ImageMagick::watermark() builds an integer channel mask:

$compositeChannels = \Imagick::CHANNEL_ALL;          // 134217727
$compositeChannels &= ~(\Imagick::CHANNEL_OPACITY);  // 134217711

and hands it to addSingleWatermark(), whose signature typed it as bool. The file has no declare(strict_types=1), so PHP silently coerces 134217711 to true, and Imagick::compositeImage() receives channel 1 — i.e. Imagick::CHANNEL_RED. Only the red channel takes part in the composite and the remaining channels are written with out-of-band values, so the transparent areas of the watermark are replaced by a solid colour block (pure red with ImageMagick 7.1.2).

Telling detail: addTiledWatermark() immediately above receives the same argument without any type hint, which is exactly why tile positioning still works. That asymmetry strongly suggests the bool is a typo.

Introduced in c509a4e (#26036, a PHPCS-only refactor that split the too-long watermark() method into the two helpers), shipped in 2.4.0 and present in every 2.4.x since, including 2.4-develop. The GD2 adapter is not affected.

This PR types the parameter as int and corrects the two @param bool $compositeChannels docblocks.

Related Pull Requests

None.

Fixed Issues (if relevant)

1. Fixes ImageMagick adapter: bool type hint on addSingleWatermark() breaks watermark transparency (solid colour block) #41137

Manual testing scenarios (*)

1. Set dev/image/default_adapter to IMAGEMAGICK.
2. Content > Design > Configuration > edit a theme > Product Image Watermarks: upload a PNG watermark with a transparent background, size 165x100, opacity 100, position Bottom Right.
3. Run rm -rf pub/media/catalog/product/cache && bin/magento catalog:images:resize && bin/magento cache:flush
4. Open any product page.
5. Before this change the whole watermark rectangle is a solid colour block. After it, the transparent areas of the watermark leave the product image untouched, matching the GD2 rendering.

Standalone check, no Magento install required:

$mask = Imagick::CHANNEL_ALL & ~Imagick::CHANNEL_OPACITY; // 134217711

$dst = new Imagick();
$dst->newImage(400, 300, new ImagickPixel('white'));
$dst->setImageAlphaChannel(Imagick::ALPHACHANNEL_ACTIVATE); // state left by ImageMagick::resize()

$wm = new Imagick('watermark.png'); // PNG with a transparent background

$dst->compositeImage($wm, Imagick::COMPOSITE_OVER, 235, 200, (bool) $mask); // before: solid colour block
$dst->compositeImage($wm, Imagick::COMPOSITE_OVER, 235, 200, $mask);        // after: transparency preserved

Questions or comments

The value written to the channels left out of the mask is not stable across ImageMagick builds, which would explain the different colours reported over the years. These two look like the same root cause and were both closed without a fix:

• Imagemagick Black pixels instead of watermark in magento 2.4.0 #29497 — "Imagemagick Black pixels instead of watermark in magento 2.4.0", closed as Cannot Reproduce; the reporter noted "Using PHP GD2 solves the problem".
• Watermark turning images cyan #38855 — "Watermark turning images cyan", reported S0, closed as needs update.

Happy to add an integration test covering watermark transparency for both adapters if you would like one.

Contribution checklist (*)

• Pull request has a meaningful description of its purpose
• All commits are accompanied by meaningful commit messages
• All new or changed code is covered with unit/integration tests (if applicable)
• README.md files for modified modules are updated and included in the pull request if any README.md predefined sections require an update
• All automated tests passed successfully (all builds are green)

[m2-assistant]

Hi @sebfie. Thank you for your contribution!
Here are some useful tips on how you can test your changes using Magento test environment.
❗ Automated tests can be triggered manually with an appropriate comment:

• @magento run all tests - run or re-run all required tests against the PR changes
• @magento run <test-build(s)> - run or re-run specific test build(s)
  For example: @magento run Unit Tests

<test-build(s)> is a comma-separated list of build names.

Allowed build names are:

1. Database Compare
2. Functional Tests CE
3. Functional Tests EE
4. Functional Tests B2B
5. Integration Tests
6. Magento Health Index
7. Sample Data Tests CE
8. Sample Data Tests EE
9. Sample Data Tests B2B
10. Static Tests
11. Unit Tests
12. WebAPI Tests
13. Semantic Version Checker

You can find more information about the builds here
ℹ️ Run only required test builds during development. Run all test builds before sending your pull request for review.

---

For more details, review the Code Contributions documentation.
Join Magento Community Engineering Slack and ask your questions in #github channel.