Merges a source rectangle onto a destination using a percentage opacity.
What It Does
imagecopy() does not resize; imagecopyresampled() performs smooth resampling. Percentage is 0–100; transparency handling is not equivalent to full alpha compositing.
Requirements and Compatibility
GD extension. Sample images and fonts referred to by filename must be supplied locally. Use PHP 8 GdImage objects where applicable; optional decoders depend on the installed build.
Syntax, Inputs and Results
The arguments shown below are concrete values for this function; their types and ranges matter. The example checks return data rather than assuming that every operation succeeds.
Example 1: Basic Use
Call the function with a concrete input and inspect its result.
<?php
if (!extension_loaded('gd')) throw new RuntimeException('GD extension required');
$im = imagecreatetruecolor(160, 110);
$white = imagecolorallocate($im, 255, 255, 255);
imagefilledrectangle($im, 0, 0, 159, 109, $white);
$src = imagecreatetruecolor(40, 40);
imagefilledrectangle($src, 0, 0, 39, 39, imagecolorallocate($src, 200, 65, 60));
imageline($src, 0, 0, 39, 39, imagecolorallocate($src, 255, 255, 255));
$ok = imagecopymerge($im, $src, 10, 10, 0, 0, 40, 40, 50);
var_dump($ok);Example 2: Another Case
Change the inputs to observe the behavior on another case.
<?php
if (!extension_loaded('gd')) throw new RuntimeException('GD extension required');
$im = imagecreatetruecolor(160, 110);
$white = imagecolorallocate($im, 255, 255, 255);
imagefilledrectangle($im, 0, 0, 159, 109, $white);
$src = imagecreatetruecolor(40, 40);
imagefilledrectangle($src, 0, 0, 39, 39, imagecolorallocate($src, 200, 65, 60));
imageline($src, 0, 0, 39, 39, imagecolorallocate($src, 255, 255, 255));
$ok = imagecopymerge($im, $src, 60, 10, 0, 0, 35, 35, 80);
var_dump($ok);Practical Example
Use the result to create an output, validate a condition, or complete an image workflow.
<?php
if (!extension_loaded('gd')) throw new RuntimeException('GD extension required');
$im = imagecreatetruecolor(160, 110);
$white = imagecolorallocate($im, 255, 255, 255);
imagefilledrectangle($im, 0, 0, 159, 109, $white);
$src = imagecreatetruecolor(40, 40);
imagefilledrectangle($src, 0, 0, 39, 39, imagecolorallocate($src, 200, 65, 60));
imageline($src, 0, 0, 39, 39, imagecolorallocate($src, 255, 255, 255));
imagecopymerge($im, $src, 60, 10, 0, 0, 35, 35, 80);
if (!imagepng($im, __DIR__ . "/imagecopymerge-demo.png")) throw new RuntimeException("Unable to save");For production, apply the compatibility and edge-case limits described below.
Important Behavior and Edge Cases
Percentage is 0–100; transparency handling is not equivalent to full alpha compositing.
Comparison with Related Functions and Tools
| Subject | Key difference |
|---|---|
| imagecopymerge() | imagecopy() does not resize; imagecopyresampled() performs smooth resampling. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Calling imagecopymerge() without its required input or supported extension | Check the extension, supply valid arguments, and handle false or exceptions according to the function. |
| Assuming imagecopymerge() guarantees a valid or safe image | Percentage is 0–100; transparency handling is not equivalent to full alpha compositing. |
| Confusing the operation with a related API | imagecopy() does not resize; imagecopyresampled() performs smooth resampling. |
Key Takeaways
- Merges a source rectangle onto a destination using a percentage opacity.
- Percentage is 0–100; transparency handling is not equivalent to full alpha compositing.
- Choose the companion API described in the comparison table when the job differs.
Use these examples as a starting point, then validate the result with the actual PHP build, dependencies and inputs used by your application.