Add support for AI generative effects

src/Transformation/Effect/EffectAction.php

@@ -29,6 +29,6 @@ class EffectAction extends Action
      */
     public function __construct($effect, ...$args)
     {
-        parent::__construct(ClassUtils::verifyInstance($effect, EffectQualifier::class, null, ...$args));
+        parent::__construct(ClassUtils::verifyInstance($effect, static::MAIN_QUALIFIER, null, ...$args));
     }
 }

src/Transformation/Effect/Generative/DetectMultipleTrait.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Cloudinary\Transformation;
+
+use Cloudinary\TransformationUtils;
+
+/**
+ * Trait DetectMultipleTrait
+ */
+trait DetectMultipleTrait
+{
+    /**
+     * Whether to detect all instances of the prompt in the image.
+     *
+     * When used with multiple prompts, it’s always true even if not explicitly set.
+     *
+     * @param bool $detectMultiple Whether to detect multiple objects.
+     *
+     * @return $this
+     */
+    public function detectMultiple($detectMultiple = true)
+    {
+        $this->getMainQualifier()->getPropertiesValue()->setSimpleNamedValue(
+            GenerativeEffectAction::MULTIPLE,
+            TransformationUtils::boolToString($detectMultiple)
+        );
+
+        return $this;
+    }
+}

src/Transformation/Effect/Generative/GenerativeEffect.php

@@ -0,0 +1,24 @@
+<?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;
+
+/**
+ * Class GenerativeEffect
+ */
+abstract class GenerativeEffect
+{
+    const GENERATIVE_RECOLOR = 'gen_recolor';
+    const GENERATIVE_REMOVE  = 'gen_remove';
+    const GENERATIVE_REPLACE  = 'gen_replace';
+    const GENERATIVE_RESTORE  = 'gen_restore';
+
+    use GenerativeEffectTrait;
+}

src/Transformation/Effect/Generative/GenerativeEffectAction.php

@@ -0,0 +1,22 @@
+<?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;
+
+/**
+ * Class GenerativeEffectAction
+ */
+class GenerativeEffectAction extends EffectAction
+{
+    const MAIN_QUALIFIER = ListEffectQualifier::class;
+
+    const MULTIPLE = 'multiple';
+    const PROMPT   = 'prompt';
+}

src/Transformation/Effect/Generative/GenerativeEffectTrait.php

@@ -0,0 +1,77 @@
+<?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;
+
+/**
+ * Trait GenerativeEffectTrait
+ *
+ * @api
+ */
+trait GenerativeEffectTrait
+{
+    /**
+     * Applies a generative restore effect to the asset.
+     *
+     * @return GenerativeEffectAction
+     */
+    public static function generativeRestore()
+    {
+        return new GenerativeEffectAction(GenerativeEffect::GENERATIVE_RESTORE);
+    }
+
+    /**
+     * Applies a generative recolor effect to the asset.
+     *
+     * @param string|array $prompt         Use natural language to describe what you want to affect in the image.
+     * @param string       $toColor        The target color.
+     * @param bool         $detectMultiple Whether to recolor all instances of the prompt in the image.
+     *
+     * @return GenerativeRecolor
+     */
+    public static function generativeRecolor($prompt, $toColor, $detectMultiple = null)
+    {
+        return new GenerativeRecolor($prompt, $toColor, $detectMultiple);
+    }
+
+    /**
+     * Applies a generative remove effect to the asset.
+     *
+     * @param string|array $prompt         Use natural language to describe what you want to affect in the image.
+     * @param string|array $region         Remove items from the specified region(s).
+     * @param bool         $detectMultiple Whether to detect all instances of the prompt in the image.
+     * @param bool         $removeShadow   Whether to remove shadows and reflections.
+     *
+     * @return GenerativeRemove
+     */
+    public static function generativeRemove(
+        $prompt = null,
+        $region = null,
+        $detectMultiple = null,
+        $removeShadow = null
+    ) {
+        return new GenerativeRemove($prompt, $region, $detectMultiple, $removeShadow);
+    }
+
+    /**
+     * Applies a generative replacement effect to the asset.
+     *
+     * @param string $fromPrompt       Use natural language to describe what you want to replace.
+     * @param string $toPrompt         Use natural language to describe the replacement.
+     * @param bool   $preserveGeometry Whether to maintain the shape of the object you're replacing.
+     * @param bool   $detectMultiple   Whether to detect all instances of the prompt in the image.
+     *
+     * @return GenerativeReplace
+     */
+    public static function generativeReplace($fromPrompt, $toPrompt, $preserveGeometry = null, $detectMultiple = null)
+    {
+        return new GenerativeReplace($fromPrompt, $toPrompt, $preserveGeometry, $detectMultiple);
+    }
+}

src/Transformation/Effect/Generative/GenerativeRecolor.php

@@ -0,0 +1,59 @@
+<?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\StringUtils;
+use Cloudinary\Transformation\Argument\ColorValue;
+
+/**
+ * Class GenerativeRecolor
+ */
+class GenerativeRecolor extends GenerativeEffectAction
+{
+    use PromptTrait;
+    use DetectMultipleTrait;
+
+    const TO_COLOR = 'to-color';
+
+    /**
+     * GenerativeRecolor constructor.
+     *
+     * @param string|array $prompt         Use natural language to describe what you want to affect in the image.
+     * @param string       $toColor        The target color.
+     * @param bool         $detectMultiple Whether to detect all instances of the prompt in the image.
+     * @param mixed        ...$args
+     */
+    public function __construct($prompt, $toColor, $detectMultiple = null, ...$args)
+    {
+        parent::__construct(GenerativeEffect::GENERATIVE_RECOLOR, ...$args);
+
+        $this->prompt($prompt);
+        $this->toColor($toColor);
+        $this->detectMultiple($detectMultiple);
+    }
+
+    /**
+     * Sets the target color.
+     *
+     * @param string|ColorValue $toColor The HTML name or RGB/A hex code of the target color.
+     *
+     * @return $this
+     */
+    public function toColor($toColor)
+    {
+        $this->getMainQualifier()->getPropertiesValue()->setSimpleNamedValue(
+            self::TO_COLOR,
+            StringUtils::truncatePrefix((string)$toColor, '#')
+        );
+
+        return $this;
+    }
+}

src/Transformation/Effect/Generative/GenerativeRemove.php

@@ -0,0 +1,83 @@
+<?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\ArrayUtils;
+use Cloudinary\StringUtils;
+use Cloudinary\Transformation\Argument\ColorValue;
+use Cloudinary\TransformationUtils;
+
+/**
+ * Class GenerativeRemove
+ */
+class GenerativeRemove extends GenerativeEffectAction
+{
+    use PromptTrait;
+    use DetectMultipleTrait;
+
+    const REGION        = 'region';
+    const REMOVE_SHADOW = 'remove-shadow';
+
+    /**
+     * GenerativeRemove constructor.
+     *
+     * @param string|array $prompt         Use natural language to describe what you want to affect in the image.
+     * @param string|array $region         Remove items from the specified region(s).
+     * @param bool         $detectMultiple Whether to detect all instances of the prompt in the image.
+     * @param bool         $removeShadow   Whether to remove shadows and reflections.
+     * @param mixed        ...$args
+     */
+    public function __construct($prompt = null, $region = null, $detectMultiple = null, $removeShadow = null, ...$args)
+    {
+        parent::__construct(GenerativeEffect::GENERATIVE_REMOVE, ...$args);
+
+        $this->prompt($prompt);
+        $this->region($region);
+        $this->detectMultiple($detectMultiple);
+        $this->removeShadow($removeShadow);
+    }
+
+    /**
+     * Sets the target region.
+     *
+     * @param $region
+     *
+     * @return $this
+     */
+    public function region(...$region)
+    {
+        $this->getMainQualifier()->getPropertiesValue()->setSimpleNamedValue(
+            self::REGION,
+            new FullListQualifierMultiValue(
+                ...ArrayUtils::build($region)
+            )
+        );
+
+        return $this;
+    }
+
+    /**
+     * Whether to remove the shadow in addition to the object(s).
+     *
+     * @param bool $removeShadow Whether to remove shadow.
+     *
+     * @return $this
+     */
+    public function removeShadow($removeShadow = true)
+    {
+        $this->getMainQualifier()->getPropertiesValue()->setSimpleNamedValue(
+            self::REMOVE_SHADOW,
+            TransformationUtils::boolToString($removeShadow)
+        );
+
+        return $this;
+    }
+}