Add downloadGeneratedSprite() and downloadMulti(), support urls for 'multi' and 'sprite'

src/Api/ApiClient.php

@@ -142,6 +142,23 @@ public function postAndSignFormAsync($endPoint, $formParams)
         return $this->postFormAsync($endPoint, $formParams);
     }
 
+    /**
+     * Signs posted parameters using configured account credentials and posts as a JSON to the endpoint.
+     *
+     * @param string|array $endPoint The API endpoint path.
+     * @param array        $params   The parameters
+     *
+     * @return PromiseInterface
+     *
+     * @internal
+     */
+    public function postAndSignJsonAsync($endPoint, $params)
+    {
+        ApiUtils::signRequest($params, $this->cloud);
+
+        return $this->postJsonAsync($endPoint, $params);
+    }
+
     /**
      * Helper method for posting multipart data asynchronously.
      *

src/Api/Upload/ArchiveTrait.php

@@ -181,7 +181,7 @@ public function createZip($options = [])
      */
     public function downloadArchiveUrl($options = [])
     {
-        $options['mode'] = 'download';
+        $options['mode'] = self::MODE_DOWNLOAD;
         $params          = self::buildArchiveParams($options);
 
         ApiUtils::signRequest($params, $this->getCloud());

src/Api/Upload/CreativeTrait.php

@@ -15,7 +15,9 @@
 use Cloudinary\Api\ApiUtils;
 use Cloudinary\ArrayUtils;
 use Cloudinary\Asset\AssetType;
+use Cloudinary\Transformation\Transformation;
 use GuzzleHttp\Promise\PromiseInterface;
+use InvalidArgumentException;
 
 /**
  * Trait CreativeTrait
@@ -27,40 +29,39 @@
 trait CreativeTrait
 {
     /**
-     * Creates a sprite from all images that have been assigned a specified tag.
+     * Creates a sprite from all images that have been assigned a specified tag or from a provided array of image URLs.
      *
      * The process produces two files:
-     * * A single image file containing all the images with the specified tag (PNG by default).
+     * * A single sprite image file containing all the images.
      * * A CSS file that includes the style class names and the location of the individual images in the sprite.
      *
      * This is an asynchronous function.
      *
-     * @param string $tag     The tag that indicates which images to include in the sprite.
-     * @param array  $options The optional parameters. See the upload API documentation.
+     * @param string|array $tag     A string specifying a tag that indicates which images to include or an array
+     *                              which include options and image URLs.
+     * @param array        $options The optional parameters. Should be omitted when $tag is an array.
      *
      * @return PromiseInterface
      *
      * @see https://cloudinary.com/documentation/image_upload_api_reference#sprite_method
      */
     public function generateSpriteAsync($tag, $options = [])
     {
-        $options['transformation'] = ApiUtils::serializeAssetTransformations($options);
-
-        $params        = ArrayUtils::whitelist($options, ['async', 'notification_url', 'transformation']);
-        $params['tag'] = $tag;
+        $params = self::buildSpriteAndMultiParams($tag, $options);
 
-        return $this->callUploadApiAsync(UploadEndPoint::SPRITE, $params, $options);
+        return $this->callUploadApiJsonAsync(UploadEndPoint::SPRITE, $params, $options);
     }
 
     /**
-     * Creates a sprite from all images that have been assigned a specified tag.
+     * Creates a sprite from all images that have been assigned a specified tag or from a provided array of image URLs.
      *
      * The process produces two files:
-     * * A single image file containing all the images with the specified tag (PNG by default).
+     * * A single sprite image file containing all the images.
      * * A CSS file that includes the style class names and the location of the individual images in the sprite.
      *
-     * @param string $tag     The tag that indicates which images to include in the sprite.
-     * @param array  $options The optional parameters. See the upload API documentation.
+     * @param string|array $tag     A string specifying a tag that indicates which images to include or an array
+     *                              which include options and image URLs.
+     * @param array        $options The optional parameters. Should be omitted when $tag is an array.
      *
      * @return ApiResponse
      *
@@ -72,34 +73,58 @@ public function generateSprite($tag, $options = [])
     }
 
     /**
-     * Creates a single animated image, video or PDF from all image assets that have been
-     * assigned a specified tag.
+     * Generates an url to create a sprite from all images that have been assigned a specified tag or from a provided
+     * array of URLs.
+     *
+     * @param string|array $tag     A string specifying a tag that indicates which images to include or an array
+     *                              which include options and image URLs.
+     * @param array        $options The optional parameters. Should be omitted when $tag is an array.
+     *
+     * @return string
+     *
+     * @see https://cloudinary.com/documentation/image_upload_api_reference#sprite_method
+     */
+    public function downloadGeneratedSprite($tag, $options = [])
+    {
+        $params = self::buildSpriteAndMultiParams($tag, $options);
+
+        $params['mode'] = self::MODE_DOWNLOAD;
+
+        $params = ApiUtils::finalizeUploadApiParams($params);
+
+        ApiUtils::signRequest($params, $this->getCloud());
+
+        return $this->getUploadUrl(AssetType::IMAGE, UploadEndPoint::SPRITE, $params);
+    }
+
+    /**
+     * Creates a single animated image, video or PDF from all image assets that have been assigned a specified tag or
+     * from a provided array of URLs.
      *
      * This is an asynchronous function.
      *
-     * @param string $tag     The tag that indicates which images to include in the animated image, video or PDF.
-     * @param array  $options The optional parameters. See the upload API documentation.
+     * @param string|array $tag     A string specifying a tag that indicates which images to include or an array
+     *                              which include options and image URLs.
+     * @param array        $options The optional parameters. Should be omitted when $tag is an array.
      *
      * @return PromiseInterface
      *
      * @see https://cloudinary.com/documentation/image_upload_api_reference#multi_method
      */
     public function multiAsync($tag, $options = [])
     {
-        $options['transformation'] = ApiUtils::serializeAssetTransformations($options);
-
-        $params        = ArrayUtils::whitelist($options, ['format', 'async', 'notification_url', 'transformation']);
-        $params['tag'] = $tag;
+        $params = self::buildSpriteAndMultiParams($tag, $options);
 
-        return $this->callUploadApiAsync(UploadEndPoint::MULTI, $params, $options);
+        return $this->callUploadApiJsonAsync(UploadEndPoint::MULTI, $params, $options);
     }
 
     /**
-     * Creates a single animated image, video or PDF from all image assets that have been
-     * assigned a specified tag.
+     * Creates a single animated image, video or PDF from all image assets that have been assigned a specified tag or
+     * from a provided array of URLs.
      *
-     * @param string $tag     The tag that indicates which images to include in the animated image, video or PDF.
-     * @param array  $options The optional parameters. See the upload API documentation.
+     * @param string|array $tag     A string specifying a tag that indicates which images to include or an array
+     *                              which include options and image URLs.
+     * @param array        $options The optional parameters. Should be omitted when $tag is an array.
      *
      * @return ApiResponse
      *
@@ -110,6 +135,31 @@ public function multi($tag, $options = [])
         return $this->multiAsync($tag, $options)->wait();
     }
 
+    /**
+     * Generates an url to create a single animated image, video or PDF from all image assets that have been assigned
+     * a specified tag or from a provided array of URLs.
+     *
+     * @param string|array $tag     A string specifying a tag that indicates which images to include or an array
+     *                              which include options and image URLs.
+     * @param array        $options The optional parameters. Should be omitted when $tag is an array.
+     *
+     * @return string
+     *
+     * @see https://cloudinary.com/documentation/image_upload_api_reference#sprite_method
+     */
+    public function downloadMulti($tag, $options = [])
+    {
+        $params = self::buildSpriteAndMultiParams($tag, $options);
+
+        $params['mode'] = self::MODE_DOWNLOAD;
+
+        $params = ApiUtils::finalizeUploadApiParams($params);
+
+        ApiUtils::signRequest($params, $this->getCloud());
+
+        return $this->getUploadUrl(AssetType::IMAGE, UploadEndPoint::MULTI, $params);
+    }
+
     /**
      * Creates derived images for all of the individual pages in a multi-page file (PDF or animated GIF).
      *
@@ -205,7 +255,46 @@ public function text($text, $options = [])
         return $this->textAsync($text, $options)->wait();
     }
 
+    /**
+     * Build params for multi, downloadMulti, generateSprite, and downloadGeneratedSprite methods.
+     *
+     * @param string|array $tagOrOptions A string specifying a tag that indicates which images to include or an array
+     *                                   which include image URLs and options.
+     * @param array        $options      The optional parameters. Should be omitted when $tagOrOptions is an array.
+     *
+     * @return array
+     */
+    private static function buildSpriteAndMultiParams($tagOrOptions, $options)
+    {
+        if (is_array($tagOrOptions)) {
+            if (empty($options)) {
+                $options = $tagOrOptions;
+            } else {
+                throw new InvalidArgumentException('First argument must be a tag when additional options are passed');
+            }
+            $tag = null;
+        } else {
+            $tag = $tagOrOptions;
+        }
+        $urls = ArrayUtils::get($options, 'urls');
+
+        if (empty($tag) && empty($urls)) {
+            throw new InvalidArgumentException('Either tag or urls are required');
+        }
+
+        $transformation = new Transformation($options);
+        $transformation->format(ArrayUtils::get($options, 'format'));
+        $options['transformation'] = ApiUtils::serializeAssetTransformations($transformation);
+
+        $params = ArrayUtils::whitelist($options, ['format', 'async', 'notification_url', 'transformation']);
+        if (isset($urls)) {
+            $params['urls'] = $urls;
+        } else {
+            $params['tag'] = $tag;
+        }
+        return $params;
 
+     }
     /**
      * Create auto-generated video slideshows.
      *

src/Api/Upload/UploadApi.php

@@ -34,6 +34,8 @@ class UploadApi
     use TagTrait;
     use UploadTrait;
 
+    const MODE_DOWNLOAD = 'download';
+
     /**
      * @var ApiClient $apiClient The HTTP API client instance.
      */
@@ -113,4 +115,23 @@ protected function callUploadApiAsync($endPoint = UploadEndPoint::UPLOAD, $param
             ApiUtils::finalizeUploadApiParams($params)
         );
     }
+
+    /**
+     * Internal method for performing all Upload API calls as a json.
+     *
+     * @param string $endPoint The relative endpoint.
+     * @param array  $params   Parameters to pass to the endpoint.
+     * @param array  $options  Additional options.
+     *
+     * @return PromiseInterface
+     *
+     * @internal
+     */
+    protected function callUploadApiJsonAsync($endPoint = UploadEndPoint::UPLOAD, $params = [], $options = [])
+    {
+        return $this->apiClient->postAndSignJsonAsync(
+            self::getUploadApiEndPoint($endPoint, $options),
+            ApiUtils::finalizeUploadApiParams($params)
+        );
+    }
 }