Add support for autoPad resize

Author: const-cloudinary

src/Transformation/Background/BackgroundTrait.php

@@ -26,7 +26,7 @@ trait BackgroundTrait
      * The image background is visible when padding is added with one of the padding crop modes, when rounding corners,
      * when adding overlays, and with semi-transparent PNGs and GIFs.
      *
-     * @param Background|ColorValue|string $background The the background to set.
+     * @param Background|ColorValue|string $background The background to set.
      *
      * @return $this
      *

src/Transformation/Resize/Crop/CropPad.php

@@ -0,0 +1,64 @@
+<?php
+/**
+ * This file is part of the Cloudinary PHP package.
+ *
+ * (c) Cloudinary
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cloudinary\Transformation;
+
+use Cloudinary\Transformation\Argument\ColorValue;
+use Cloudinary\Transformation\Expression\Expression;
+use InvalidArgumentException;
+
+/**
+ * Class CropPad
+ *
+ * @internal
+ */
+class CropPad extends Crop
+{
+    use CropPadTrait;
+    use BackgroundTrait;
+
+    /**
+     * CropPad constructor.
+     *
+     * @param string|CropMode              $cropMode
+     * @param int|string|Expression        $width
+     * @param int|string|Expression        $height
+     * @param mixed                        $gravity
+     * @param string|Background|ColorValue $background
+     */
+    public function __construct($cropMode, $width = null, $height = null, $gravity = null, $background = null)
+    {
+        if ($gravity === null) {
+            $gravity = Gravity::auto();
+        }
+
+        parent::__construct($cropMode, $width, $height, $gravity);
+
+        $this->background($background);
+    }
+
+    /**
+     * Sets the gravity to use when using the FILL_PAD crop mode.
+     *
+     * @param $autoGravity
+     *
+     * @return $this
+     */
+    public function gravity($autoGravity)
+    {
+        if (! $autoGravity instanceof AutoGravity) {
+            throw new InvalidArgumentException('CropPad only supports Auto Gravity');
+        }
+
+        $this->addQualifier($autoGravity);
+
+        return $this;
+    }
+}

src/Transformation/Resize/Crop/CropPadTrait.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * This file is part of the Cloudinary PHP package.
+ *
+ * (c) Cloudinary
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cloudinary\Transformation;
+
+use Cloudinary\Transformation\Argument\ColorValue;
+
+/**
+ * Trait CropPadTrait
+ *
+ * @api
+ */
+trait CropPadTrait
+{
+    /**
+     * Tries to prevent a "bad crop" by first attempting to use the auto cropping mode, but adding some padding if the
+     * algorithm determines that more of the original image needs to be included in the final image.
+     *
+     * Especially useful if the aspect ratio of the delivered image is considerably different from the original's
+     * aspect ratio.
+     *
+     * Only supported in conjunction with Automatic cropping (Gravity::auto())
+     *
+     * @param int|float|string|null        $width      The required width of a transformed asset.
+     * @param int|float|null               $height     The required height of a transformed asset.
+     * @param FocalGravity|string          $gravity    Specifies which part of the original image to include.
+     * @param Background|ColorValue|string $background The background color of the image.
+     *
+     * @return CropPad
+     *
+     * @see Gravity::auto
+     */
+    public static function autoPad($width = null, $height = null, $gravity = null, $background = null)
+    {
+        return new CropPad(CropMode::AUTO_PAD, $width, $height, $gravity, $background);
+    }
+}

src/Transformation/Resize/Parameter/CropMode.php

@@ -125,6 +125,13 @@ class CropMode extends BaseQualifier
      */
     const AUTO = 'auto';
 
+    /**
+     * The AUTO_PAD crop mode tries to prevent a "bad crop" by first attempting to use the auto cropping mode,
+     * but adding some padding if the algorithm determines that more of the original image needs to be included in the
+     * final image.
+     */
+    const AUTO_PAD = 'auto_pad';
+
     /**
      * The IMAGGA_CROP crop mode crops your image based on automatically calculated areas of interest within each
      * specific photo.

src/Transformation/Resize/ResizeTrait.php

@@ -23,5 +23,6 @@ trait ResizeTrait
     use FillTrait;
     use FillPadTrait;
     use CropTrait;
+    use CropPadTrait;
     use ImaggaTrait;
 }

tests/Unit/Transformation/Image/ResizeTest.php

@@ -14,11 +14,14 @@
 use Cloudinary\Transformation\Argument\Color;
 use Cloudinary\Transformation\AspectRatio;
 use Cloudinary\Transformation\AutoGravity;
+use Cloudinary\Transformation\Background;
 use Cloudinary\Transformation\CompassGravity;
 use Cloudinary\Transformation\CompassPosition;
 use Cloudinary\Transformation\Crop;
+use Cloudinary\Transformation\CropPad;
 use Cloudinary\Transformation\Fill;
 use Cloudinary\Transformation\FillPad;
+use Cloudinary\Transformation\FocusOn;
 use Cloudinary\Transformation\Gravity;
 use Cloudinary\Transformation\Pad;
 use Cloudinary\Transformation\Qualifier;
@@ -255,6 +258,31 @@ public function testCrop()
         );
     }
 
+    public function testCropAutoPad()
+    {
+        self::assertStrEquals(
+            'c_auto_pad,g_auto,h_200,w_100',
+            CropPad::autoPad(100, 200)
+        );
+
+        self::assertStrEquals(
+            'c_auto_pad,g_auto,h_200,w_100,z_0.5',
+            CropPad::autoPad(100, 200, Gravity::auto())->zoom(0.5)
+        );
+
+        self::assertStrEquals(
+            'c_auto_pad,g_auto:dog,h_200,w_100',
+            CropPad::autoPad(100, 200, Gravity::auto()->autoFocus(FocusOn::dog()))
+        );
+
+        self::assertStrEquals(
+            'b_gen_fill,c_auto_pad,g_auto:dog,h_200,w_100',
+            CropPad::autoPad(100, 200, Gravity::auto()->autoFocus(FocusOn::dog()))->background(
+                Background::generativeFill()
+            )
+        );
+    }
+
     public function testResize()
     {
         /** @noinspection PhpUndefinedMethodInspection */
@@ -303,5 +331,10 @@ public function testResize()
             'c_crop,h_70,w_50,z_0.5',
             (string)Resize::crop(50, 70)->zoom(0.5)
         );
+
+        self::assertStrEquals(
+            'b_gen_fill,c_auto_pad,g_auto:dog,h_200,w_100',
+            Resize::autoPad(100, 200, Gravity::auto()->autoFocus(FocusOn::dog()), Background::generativeFill())
+        );
     }
 }