Fill image transform setting

src/base/Image.php

@@ -74,7 +74,7 @@ abstract public function crop(int $x1, int $x2, int $y1, int $y2): self;
      * @param bool $scaleIfSmaller
      * @return static Self reference
      */
-    abstract public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self;
+    abstract public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, string $position = 'center-center'): self;
 
     /**
      * Scale and crop image to exactly fit the specified size.

src/controllers/ImageTransformsController.php

@@ -10,6 +10,7 @@
 use Craft;
 use craft\helpers\Image;
 use craft\models\ImageTransform;
+use craft\validators\ColorValidator;
 use craft\web\assets\edittransform\EditTransformAsset;
 use craft\web\Controller;
 use yii\web\NotFoundHttpException;
@@ -133,6 +134,7 @@ public function actionSave(): ?Response
         $transform->quality = $this->request->getBodyParam('quality') ?: null;
         $transform->interlace = $this->request->getBodyParam('interlace');
         $transform->format = $this->request->getBodyParam('format');
+        $transform->fill = $this->request->getBodyParam('fill');
 
         if (empty($transform->format)) {
             $transform->format = null;
@@ -156,6 +158,13 @@ public function actionSave(): ?Response
             $errors = true;
         }
 
+        $useFill = $this->request->getBodyParam('useFill');
+        if ($useFill && $transform->mode === 'fit') {
+            $transform->fill = $transform->fill ? ColorValidator::normalizeColor($transform->fill) : 'transparent';
+        } else {
+            $transform->fill = null;
+        }
+
         if (!$errors) {
             $success = Craft::$app->getImageTransforms()->saveTransform($transform);
         } else {

src/elements/Asset.php

@@ -2586,7 +2586,8 @@ private function _dimensions(mixed $transform = null): array
             $this->_height,
             $transform->width,
             $transform->height,
-            $transform->mode
+            $transform->mode,
+            $transform->fill
         );
     }
 

src/helpers/Image.php

@@ -81,11 +81,15 @@ public static function targetDimensions(
         ?int $transformWidth,
         ?int $transformHeight,
         string $mode = 'crop',
+        ?string $fill = null,
         ?bool $upscale = null,
     ): array {
         [$width, $height] = static::calculateMissingDimension($transformWidth, $transformHeight, $sourceWidth, $sourceHeight);
         $factor = max($sourceWidth / $width, $sourceHeight / $height);
 
+        $imageRatio = $sourceWidth / $sourceHeight;
+        $transformRatio = $width / $height;
+
         if ($upscale ?? Craft::$app->getConfig()->getGeneral()->upscaleImages) {
             // Special case for 'fit' since that's the only one whose dimensions vary from the transform dimensions
             if ($mode === 'fit') {
@@ -96,14 +100,12 @@ public static function targetDimensions(
             return [$width, $height];
         }
 
-        if ($transformWidth === null || $transformHeight === null) {
-            $transformRatio = $sourceWidth / $sourceHeight;
-        } else {
-            $transformRatio = $transformWidth / $transformHeight;
+        // When mode is `fit` with a fill provided, always use the transform size
+        if ($mode === 'fit' && $fill) {
+            return [$width, $height];
         }
 
-        $imageRatio = $sourceWidth / $sourceHeight;
-
+        // When mode is `fit` (no fill provided) or the source is the same ratio as the transform
         if ($mode === 'fit' || $imageRatio === $transformRatio) {
             $targetWidth = min($sourceWidth, $width, (int)round($sourceWidth / $factor));
             $targetHeight = min($sourceHeight, $height, (int)round($sourceHeight / $factor));

src/helpers/ImageTransforms.php

@@ -18,6 +18,7 @@
 use craft\errors\ImageTransformException;
 use craft\image\Raster;
 use craft\models\ImageTransform;
+use craft\validators\ColorValidator;
 
 /**
  * Image Transforms helper.
@@ -30,7 +31,7 @@ class ImageTransforms
     /**
      * @var string The pattern to use for matching against a transform string.
      */
-    public const TRANSFORM_STRING_PATTERN = '/_(?P<width>\d+|AUTO)x(?P<height>\d+|AUTO)_(?P<mode>[a-z]+)(?:_(?P<position>[a-z\-]+))?(?:_(?P<quality>\d+))?(?:_(?P<interlace>[a-z]+))?/i';
+    public const TRANSFORM_STRING_PATTERN = '/_(?P<width>\d+|AUTO)x(?P<height>\d+|AUTO)_(?P<mode>[a-z]+)(?:_(?P<position>[a-z\-]+))?(?:_(?P<quality>\d+))?(?:_(?P<interlace>[a-z]+))?(?:_(?P<fill>[0-9a-f]{6}|transparent))?/i';
 
     /**
      * Create an AssetImageTransform model from a string.
@@ -55,6 +56,10 @@ public static function createTransformFromString(string $transformString): Image
             unset($matches['quality']);
         }
 
+        if (isset($matches['fill'])) {
+            $fill = ColorValidator::normalizeColor($matches['fill']);
+        }
+
         return Craft::createObject([
             'class' => ImageTransform::class,
             /** @phpstan-ignore-next-line */
@@ -65,6 +70,7 @@ public static function createTransformFromString(string $transformString): Image
             'position' => $matches['position'],
             'quality' => $matches['quality'] ?? null,
             'interlace' => $matches['interlace'] ?? 'none',
+            'fill' => $fill ?? null,
             'transformer' => ImageTransform::DEFAULT_TRANSFORMER,
         ]);
     }
@@ -234,7 +240,8 @@ public static function getTransformString(ImageTransform $transform, bool $ignor
             '_' . $transform->mode .
             '_' . $transform->position .
             ($transform->quality ? '_' . $transform->quality : '') .
-            '_' . $transform->interlace;
+            '_' . $transform->interlace .
+            ($transform->fill ? '_' . ltrim($transform->fill, '#') : '');
     }
 
     /**
@@ -266,6 +273,7 @@ public static function normalizeTransform(mixed $transform): ?ImageTransform
                 'parameterChangeTime',
                 'mode',
                 'position',
+                'fill',
                 'quality',
                 'interlace',
             ]);
@@ -282,6 +290,16 @@ public static function normalizeTransform(mixed $transform): ?ImageTransform
                 $transform['height'] = null;
             }
 
+            if (!empty($transform['fill'])) {
+                $normalizedValue = ColorValidator::normalizeColor($transform['fill']);
+                if ((new ColorValidator())->validate($normalizedValue)) {
+                    $transform['fill'] = $normalizedValue;
+                } else {
+                    Craft::warning("Invalid transform fill: {$transform['fill']}", __METHOD__);
+                    $transform['fill'] = null;
+                }
+            }
+
             if (array_key_exists('transform', $transform)) {
                 $baseTransform = self::normalizeTransform(ArrayHelper::remove($transform, 'transform'));
                 return self::extendTransform($baseTransform, $transform);

src/image/Raster.php

@@ -24,6 +24,7 @@
 use Imagine\Image\BoxInterface;
 use Imagine\Image\ImageInterface;
 use Imagine\Image\Metadata\ExifMetadataReader;
+use Imagine\Image\Palette\Color\ColorInterface;
 use Imagine\Image\Palette\RGB;
 use Imagine\Image\Point;
 use Imagine\Imagick\Imagine as ImagickImagine;
@@ -59,9 +60,9 @@ class Raster extends Image
     private int $_quality = 0;
 
     /**
-     * @var AbstractImage|null
+     * @var ImageInterface|null
      */
-    private ?AbstractImage $_image = null;
+    private ?ImageInterface $_image = null;
 
     /**
      * @var AbstractImagine|null
@@ -78,6 +79,11 @@ class Raster extends Image
      */
     private ?Font $_font = null;
 
+    /**
+     * @var ColorInterface|null
+     */
+    private ?ColorInterface $_fill = null;
+
     /**
      * @inheritdoc
      */
@@ -234,7 +240,7 @@ public function crop(int $x1, int $x2, int $y1, int $y2): self
     /**
      * @inheritdoc
      */
-    public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self
+    public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, array|string $position = 'center-center'): self
     {
         $this->normalizeDimensions($targetWidth, $targetHeight);
 
@@ -243,11 +249,67 @@ public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfS
         if ($scaleIfSmaller || $this->getWidth() > $targetWidth || $this->getHeight() > $targetHeight) {
             $factor = max($this->getWidth() / $targetWidth, $this->getHeight() / $targetHeight);
             $this->resize(round($this->getWidth() / $factor), round($this->getHeight() / $factor));
+
+            if ($this->_fill) {
+                $this->applyFill($targetWidth, $targetHeight, $position);
+            }
         }
 
         return $this;
     }
 
+    protected function applyFill(?int $targetWidth, ?int $targetHeight, string $position = 'center-center')
+    {
+        $box = new Box($targetWidth, $targetHeight);
+        $canvas = $this->_instance->create($box, $this->_fill);
+
+        [$verticalPosition, $horizontalPosition] = explode('-', $position);
+
+        switch ($verticalPosition) {
+            case 'top':
+                $y = 0;
+                break;
+            case 'bottom':
+                $y = ($box->getHeight() - $this->getHeight());
+                break;
+            default:
+                $y = ($box->getHeight() - $this->getHeight()) / 2;
+                break;
+        }
+
+        switch ($horizontalPosition) {
+            case 'left':
+                $x = 0;
+                break;
+            case 'right':
+                $x = ($box->getWidth() - $this->getWidth());
+                break;
+            default:
+                $x = ($box->getWidth() - $this->getWidth()) / 2;
+                break;
+        }
+
+        $point = new Point($x, $y);
+
+        if ($this->_isAnimated) {
+            $canvas->layers()->remove(0);
+            $this->_image->layers()->coalesce();
+
+            foreach ($this->_image->layers() as $layer) {
+                $newLayer = $this->_instance->create($box, $this->_fill);
+                $newLayer->paste($layer, $point);
+                $canvas->layers()->add($newLayer);
+
+                // Hopefully this doesn't take _too_ long, but it might
+                $this->heartbeat();
+            }
+        } else {
+            $canvas->paste($this->_image, $point);
+        }
+
+        $this->_image = $canvas;
+    }
+
     /**
      * @inheritdoc
      */
@@ -458,6 +520,23 @@ public function setInterlace(string $interlace): self
         return $this;
     }
 
+    /**
+     * Sets the fill color based on the image's palette.
+     *
+     * @param string $fill Hex color of the fill.
+     * @return $this Self reference
+     */
+    public function setFill(string $fill): self
+    {
+        if ($fill === 'transparent') {
+            $this->_fill = $this->_image->palette()->color('#ffffff', 0);
+        } else {
+            $this->_fill = $this->_image->palette()->color($fill);
+        }
+
+        return $this;
+    }
+
     /**
      * @inheritdoc
      */

src/image/Svg.php

@@ -144,7 +144,7 @@ public function crop(int $x1, int $x2, int $y1, int $y2): self
     /**
      * @inheritdoc
      */
-    public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self
+    public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, string $position = 'center-center'): self
     {
         $this->normalizeDimensions($targetWidth, $targetHeight);
 

src/imagetransforms/ImageTransformer.php

@@ -357,21 +357,26 @@ protected function generateTransformedImage(Asset $asset, ImageTransformIndex $i
         // In case this takes a while, update the timestamp so we know it's all working
         $image->setHeartbeatCallback(fn() => $this->storeTransformIndexData($index));
 
+        if ($asset->getHasFocalPoint()) {
+            $position = $asset->getFocalPoint();
+        } elseif (!preg_match('/(top|center|bottom)-(left|center|right)/', $transform->position)) {
+            $position = 'center-center';
+        } else {
+            $position = $transform->position;
+        }
+
         switch ($transform->mode) {
             case 'fit':
-                $image->scaleToFit($transform->width, $transform->height);
+                if ($transform->fill && $image instanceof Raster) {
+                    $image->setFill($transform->fill);
+                }
+
+                $image->scaleToFit($transform->width, $transform->height, Craft::$app->getConfig()->getGeneral()->upscaleImages, $position);
                 break;
             case 'stretch':
                 $image->resize($transform->width, $transform->height);
                 break;
             default:
-                if ($asset->getHasFocalPoint()) {
-                    $position = $asset->getFocalPoint();
-                } elseif (!preg_match('/(top|center|bottom)-(left|center|right)/', $transform->position)) {
-                    $position = 'center-center';
-                } else {
-                    $position = $transform->position;
-                }
                 $image->scaleAndCrop($transform->width, $transform->height, Craft::$app->getConfig()->getGeneral()->upscaleImages, $position);
         }
 

src/migrations/Install.php

@@ -197,6 +197,7 @@ public function createTables(): void
             'format' => $this->string(),
             'quality' => $this->integer(),
             'interlace' => $this->enum('interlace', ['none', 'line', 'plane', 'partition'])->notNull()->defaultValue('none'),
+            'fill' => $this->string(11)->null(),
             'parameterChangeTime' => $this->dateTime(),
             'dateCreated' => $this->dateTime()->notNull(),
             'dateUpdated' => $this->dateTime()->notNull(),

src/migrations/m221027_160703_add_image_transform_fill.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace craft\migrations;
+
+use craft\db\Migration;
+use craft\db\Table;
+
+/**
+ * m221027_160703_add_image_transform_fill migration.
+ */
+class m221027_160703_add_image_transform_fill extends Migration
+{
+    /**
+     * @inheritdoc
+     */
+    public function safeUp(): bool
+    {
+        // Place migration code here...
+        $this->addColumn(Table::IMAGETRANSFORMS, 'fill', $this->string(11)->null()->after('interlace'));
+
+        return true;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function safeDown(): bool
+    {
+        echo "m221027_160703_add_image_transform_fill cannot be reverted.\n";
+        return false;
+    }
+}