class UploadApi

Class UploadApi for accessing Cloudinary Upload API functionality

Properties

ApiClient $apiClient Defined in UploadApi class from UploadTrait

Methods

createArchiveAsync(array $options = [], string $targetFormat = null)

Creates a new archive in the server and returns information in JSON format.

createArchive(array $options = [], null $targetFormat = null)

Creates a new archive in the server and returns information in JSON format.

createZipAsync(array $options = [])

Creates a new zip archive in the server and returns information in JSON format.

createZip(array $options = [])

Creates a new zip archive in the server and returns information in JSON format.

downloadArchiveUrl(array $options = [])

Returns a URL that when invoked creates an archive and returns it.

downloadZipUrl(array $options = [])

Returns a URL that when invokes creates a zip archive and returns it.

privateDownloadUrl(string $publicId, string $format, array $options = [])

Returns a URL that when invoked downloads the asset.

downloadFolder(string $folderPath, array $options = [])

Creates and returns a URL that when invoked creates an archive of a folder.

downloadBackedupAsset(string $assetId, string $versionId)

The returned url allows downloading the backedup asset based on the the asset ID and the version ID.

addContextAsync(array|string $context, array|string $publicIds = [], array $options = [])

Adds context metadata as key-value pairs to the the specified assets.

addContext(array|string $context, array|string $publicIds = [], array $options = [])

Adds context metadata as key-value pairs to the the specified assets.

removeAllContextAsync(array|string $publicIds = [], array $options = [])

Removes all context metadata from the specified assets.

removeAllContext(array $publicIds = [], array $options = [])

Removes all context metadata from the specified assets.

generateSpriteAsync(string|array $tag, array $options = [])

Creates a sprite from all images that have been assigned a specified tag or from a provided array of image URLs.

generateSprite(string|array $tag, array $options = [])

Creates a sprite from all images that have been assigned a specified tag or from a provided array of image URLs.

downloadGeneratedSprite(string|array $tag, array $options = [])

Generates an url to create a sprite from all images that have been assigned a specified tag or from a provided array of URLs.

multiAsync(string|array $tag, array $options = [])

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.

multi(string|array $tag, array $options = [])

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.

downloadMulti(string|array $tag, array $options = [])

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.

explodeAsync(string $publicId, array $options = [])

Creates derived images for all of the individual pages in a multi-page file (PDF or animated GIF).

explode(string $publicId, array $options = [])

Creates derived images for all of the individual pages in a multi-page file (PDF or animated GIF).

textAsync(string $text, array $options = [])

Dynamically generates an image from a given textual string.

text(string $text, array $options = [])

Dynamically generates an image from a given textual string.

createSlideshowAsync(array $options = [])

Create auto-generated video slideshows.

createSlideshow(array $options = [])

Create auto-generated video slideshows.

destroyAsync(string $publicId, array $options = [])

Immediately and permanently deletes a single asset from your Cloudinary cloud.

destroy(string $publicId, array $options = [])

Immediately and permanently deletes a single asset from your Cloudinary cloud.

renameAsync(string $fromPublicId, string $toPublicId, array $options = [])

Renames the specified asset in your Cloudinary cloud.

rename(string $fromPublicId, string $toPublicId, array $options = [])

Renames the specified asset in your Cloudinary cloud.

explicitAsync(string $publicId, array $options = [])

Applies actions to an already uploaded asset.

explicit(string $publicId, array $options = [])

Applies actions to already uploaded assets.

updateMetadataAsync(array $metadata, array $publicIds, array $options)

Populates metadata fields with the given values. Existing values will be overwritten.

updateMetadata(array $metadata, array $publicIds, array $options = [])

Populates metadata fields with the given values.

addTagAsync(string $tag, array $publicIds = [], array $options = [])

Adds a tag to the assets specified.

addTag(string $tag, array $publicIds = [], array $options = [])

Adds a tag to the assets specified.

removeTagAsync(string $tag, array|string $publicIds = [], array $options = [])

Removes a tag from the assets specified.

removeTag(string $tag, array|string $publicIds = [], array $options = [])

Removes a tag from the assets specified.

removeAllTagsAsync(array $publicIds = [], array $options = [])

Removes all tags from the assets specified.

removeAllTags(array $publicIds = [], array $options = [])

Removes all tags from the assets specified.

replaceTagAsync(string $tag, array|string $publicIds = [], array $options = [])

Replaces all existing tags on the assets specified with the tag specified.

replaceTag(string $tag, array|string $publicIds = [], array $options = [])

Replaces all existing tags on the assets specified with the tag specified.

buildUploadParams(array $options)

Consolidates the upload parameters.

uploadAsync(string $file, array $options = [])

Uploads an asset to a Cloudinary cloud.

upload(string $file, array $options = [])

Uploads an asset to a Cloudinary cloud.

unsignedUploadAsync(string $file, string $uploadPreset, array $options = [])

Uploads an asset to a Cloudinary cloud.

unsignedUpload(string $file, string $uploadPreset, array $options = [])

Uploads an asset to a Cloudinary cloud.

__construct(mixed $configuration = null)

Admin Api constructor.

getUploadUrl(string $assetType = AssetType::AUTO, string $endPoint = UploadEndPoint::UPLOAD, array $params = [])

Gets upload URL for the specified asset type and endpoint.

Details

PromiseInterface createArchiveAsync(array $options = [], string $targetFormat = null)

Creates a new archive in the server and returns information in JSON format.

Parameters

Name Type Description
$options array
$targetFormat string

Return Value

PromiseInterface

ApiResponse createArchive(array $options = [], null $targetFormat = null)

Creates a new archive in the server and returns information in JSON format.

Parameters

Name Type Description
$options array
$targetFormat null

Return Value

ApiResponse

PromiseInterface createZipAsync(array $options = [])

Creates a new zip archive in the server and returns information in JSON format.

Parameters

Name Type Description
$options array

Return Value

PromiseInterface

ApiResponse createZip(array $options = [])

Creates a new zip archive in the server and returns information in JSON format.

Parameters

Name Type Description
$options array

Return Value

ApiResponse

string downloadArchiveUrl(array $options = [])

Returns a URL that when invoked creates an archive and returns it.

Parameters

Name Type Description
$options array Additional options. Can be one of the following:

Return Value

string The resulting archive URL.

string downloadZipUrl(array $options = [])

Returns a URL that when invokes creates a zip archive and returns it.

Parameters

Name Type Description
$options array Additional options. See ArchiveTrait::downloadArchiveUrl.

Return Value

string The resulting archive URL.

See also

ArchiveTrait::downloadArchiveUrl

string privateDownloadUrl(string $publicId, string $format, array $options = [])

Returns a URL that when invoked downloads the asset.

Parameters

Name Type Description
$publicId string The public ID of the asset to download.
$format string The format of the asset to download.
$options array Additional options.

Return Value

string

string downloadFolder(string $folderPath, array $options = [])

Creates and returns a URL that when invoked creates an archive of a folder.

Parameters

Name Type Description
$folderPath string Full path (from the root) of the folder to download.
$options array Additional options.

Return Value

string Url for downloading an archive of a folder.

string downloadBackedupAsset(string $assetId, string $versionId)

The returned url allows downloading the backedup asset based on the the asset ID and the version ID.

Parameters

Name Type Description
$assetId string The asset ID of the asset.
$versionId string The version ID of the asset.

Return Value

string The signed URL for downloading backup version of the asset.

PromiseInterface addContextAsync(array|string $context, array|string $publicIds = [], array $options = [])

Adds context metadata as key-value pairs to the the specified assets.

This is an asynchronous function.

Parameters

Name Type Description
$context array|string The key-value pairs of context metadata.
$publicIds array|string The public IDs of the assets to add context metadata to.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#context_method

ApiResponse addContext(array|string $context, array|string $publicIds = [], array $options = [])

Adds context metadata as key-value pairs to the the specified assets.

Parameters

Name Type Description
$context array|string The key-value pairs of context metadata.
$publicIds array|string The public IDs of the assets to add context metadata to.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#context_method

PromiseInterface removeAllContextAsync(array|string $publicIds = [], array $options = [])

Removes all context metadata from the specified assets.

This is an asynchronous function.

Parameters

Name Type Description
$publicIds array|string The public IDs of the assets to remove context metadata from.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#context_method

ApiResponse removeAllContext(array $publicIds = [], array $options = [])

Removes all context metadata from the specified assets.

Parameters

Name Type Description
$publicIds array The public IDs of the assets to remove context metadata from.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#context_method

PromiseInterface generateSpriteAsync(string|array $tag, array $options = [])

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 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.

Parameters

Name Type Description
$tag string|array A string specifying a tag that indicates which images to include or an array which include options and image URLs.
$options array The optional parameters. Should be omitted when $tag is an array.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#sprite_method

ApiResponse generateSprite(string|array $tag, array $options = [])

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 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.

Parameters

Name Type Description
$tag string|array A string specifying a tag that indicates which images to include or an array which include options and image URLs.
$options array The optional parameters. Should be omitted when $tag is an array.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#sprite_method

string downloadGeneratedSprite(string|array $tag, array $options = [])

Generates an url to create a sprite from all images that have been assigned a specified tag or from a provided array of URLs.

Parameters

Name Type Description
$tag string|array A string specifying a tag that indicates which images to include or an array which include options and image URLs.
$options array The optional parameters. Should be omitted when $tag is an array.

Return Value

string

See also

https://cloudinary.com/documentation/image_upload_api_reference#sprite_method

PromiseInterface multiAsync(string|array $tag, array $options = [])

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.

Parameters

Name Type Description
$tag string|array A string specifying a tag that indicates which images to include or an array which include options and image URLs.
$options array The optional parameters. Should be omitted when $tag is an array.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#multi_method

ApiResponse multi(string|array $tag, array $options = [])

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.

Parameters

Name Type Description
$tag string|array A string specifying a tag that indicates which images to include or an array which include options and image URLs.
$options array The optional parameters. Should be omitted when $tag is an array.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#multi_method

string downloadMulti(string|array $tag, array $options = [])

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.

Parameters

Name Type Description
$tag string|array A string specifying a tag that indicates which images to include or an array which include options and image URLs.
$options array The optional parameters. Should be omitted when $tag is an array.

Return Value

string

See also

https://cloudinary.com/documentation/image_upload_api_reference#sprite_method

PromiseInterface explodeAsync(string $publicId, array $options = [])

Creates derived images for all of the individual pages in a multi-page file (PDF or animated GIF).

Each derived image is stored with the same public ID as the original file, and can be accessed using the page parameter, in order to deliver a specific image.

This is an asynchronous function.

Parameters

Name Type Description
$publicId string The public ID of the multi-page file.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#explode_method

ApiResponse explode(string $publicId, array $options = [])

Creates derived images for all of the individual pages in a multi-page file (PDF or animated GIF).

Each derived image is stored with the same public ID as the original file, and can be accessed using the page parameter, in order to deliver a specific image.

Parameters

Name Type Description
$publicId string The public ID of the multi-page file.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#explode_method

PromiseInterface textAsync(string $text, array $options = [])

Dynamically generates an image from a given textual string.

This is an asynchronous function.

Parameters

Name Type Description
$text string The text string to generate an image for.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#text_method

ApiResponse text(string $text, array $options = [])

Dynamically generates an image from a given textual string.

Parameters

Name Type Description
$text string The text string to generate an image for.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#text_method

PromiseInterface createSlideshowAsync(array $options = [])

Create auto-generated video slideshows.

Parameters

Name Type Description
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/video_slideshow_generation

ApiResponse createSlideshow(array $options = [])

Create auto-generated video slideshows.

Parameters

Name Type Description
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/video_slideshow_generation

PromiseInterface destroyAsync(string $publicId, array $options = [])

Immediately and permanently deletes a single asset from your Cloudinary cloud.

Backed up assets are not deleted, and any assets and transformed assets already downloaded by visitors to your website might still be accessible through cached copies on the CDN. You can invalidate any cached copies on the CDN with the invalidate parameter.

This is an asynchronous function.

Parameters

Name Type Description
$publicId string The public ID of the asset to delete.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#destroy_method

ApiResponse destroy(string $publicId, array $options = [])

Immediately and permanently deletes a single asset from your Cloudinary cloud.

Backed up assets are not deleted, and any assets and transformed assets already downloaded by visitors to your website might still be accessible through cached copies on the CDN. You can invalidate any cached copies on the CDN with the invalidate parameter.

Parameters

Name Type Description
$publicId string The public ID of the asset to delete.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#destroy_method

PromiseInterface renameAsync(string $fromPublicId, string $toPublicId, array $options = [])

Renames the specified asset in your Cloudinary cloud.

The existing URLs of renamed assets and their associated derived assets are no longer valid, although any assets and transformed assets already downloaded by visitors to your website might still be accessible through cached copies on the CDN. You can invalidate any cached copies on the CDN with the invalidate parameter.

This is an asynchronous function.

Parameters

Name Type Description
$fromPublicId string The public ID of the asset to rename.
$toPublicId string The new public ID of the asset.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#rename_method

mixed rename(string $fromPublicId, string $toPublicId, array $options = [])

Renames the specified asset in your Cloudinary cloud.

The existing URLs of renamed assets and their associated derived assets are no longer valid, although any assets and transformed assets already downloaded by visitors to your website might still be accessible through cached copies on the CDN. You can invalidate any cached copies on the CDN with the invalidate parameter.

Parameters

Name Type Description
$fromPublicId string The public ID of the asset to rename.
$toPublicId string The new public ID of the asset.
$options array The optional parameters. See the upload API documentation.

Return Value

mixed

See also

https://cloudinary.com/documentation/image_upload_api_reference#rename_method

PromiseInterface explicitAsync(string $publicId, array $options = [])

Applies actions to an already uploaded asset.

This is an asynchronous function.

Parameters

Name Type Description
$publicId string The public ID of the asset to apply the actions to.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#explicit_method

mixed explicit(string $publicId, array $options = [])

Applies actions to already uploaded assets.

Parameters

Name Type Description
$publicId string The public ID of the asset to apply the actions to.
$options array The optional parameters. See the upload API documentation.

Return Value

mixed

See also

https://cloudinary.com/documentation/image_upload_api_reference#explicit_method

mixed updateMetadataAsync(array $metadata, array $publicIds, array $options)

Populates metadata fields with the given values. Existing values will be overwritten.

Any metadata-value pairs given are merged with any existing metadata-value pairs (an empty value for an existing metadata field clears the value).

This is an asynchronous function.

Parameters

Name Type Description
$metadata array A list of custom metadata fields (by external_id) and the values to assign to each of them.
$publicIds array An array of Public IDs of assets uploaded to Cloudinary.
$options array The optional parameters. See the upload API documentation.

Return Value

mixed A list of public IDs that were updated.

See also

https://cloudinary.com/documentation/image_upload_api_reference#metadata_method

mixed updateMetadata(array $metadata, array $publicIds, array $options = [])

Populates metadata fields with the given values.

Existing values will be overwritten.

Any metadata-value pairs given are merged with any existing metadata-value pairs (an empty value for an existing metadata field clears the value).

Parameters

Name Type Description
$metadata array A list of custom metadata fields (by external_id) and the values to assign to each of them.
$publicIds array An array of Public IDs of assets uploaded to Cloudinary.
$options array The optional parameters. See the upload API documentation.

Return Value

mixed A list of public IDs that were updated.

See also

https://cloudinary.com/documentation/image_upload_api_reference#metadata_method

PromiseInterface addTagAsync(string $tag, array $publicIds = [], array $options = [])

Adds a tag to the assets specified.

This is an asynchronous function.

Parameters

Name Type Description
$tag string The name of the tag to add.
$publicIds array The public IDs of the assets to add the tag to.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

ApiResponse addTag(string $tag, array $publicIds = [], array $options = [])

Adds a tag to the assets specified.

Parameters

Name Type Description
$tag string The name of the tag to add.
$publicIds array The public IDs of the assets to add the tag to.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

PromiseInterface removeTagAsync(string $tag, array|string $publicIds = [], array $options = [])

Removes a tag from the assets specified.

This is an asynchronous function.

Parameters

Name Type Description
$tag string The name of the tag to remove.
$publicIds array|string The public IDs of the assets to remove the tags from.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

ApiResponse removeTag(string $tag, array|string $publicIds = [], array $options = [])

Removes a tag from the assets specified.

Parameters

Name Type Description
$tag string The name of the tag to remove.
$publicIds array|string The public IDs of the assets to remove the tags from.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

PromiseInterface removeAllTagsAsync(array $publicIds = [], array $options = [])

Removes all tags from the assets specified.

This is an asynchronous function.

Parameters

Name Type Description
$publicIds array The public IDs of the assets to remove all tags from.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

ApiResponse removeAllTags(array $publicIds = [], array $options = [])

Removes all tags from the assets specified.

Parameters

Name Type Description
$publicIds array The public IDs of the assets to remove all tags from.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

PromiseInterface replaceTagAsync(string $tag, array|string $publicIds = [], array $options = [])

Replaces all existing tags on the assets specified with the tag specified.

This is an asynchronous function.

Parameters

Name Type Description
$tag string The new tag with which to replace the existing tags.
$publicIds array|string The public IDs of the assets to replace the tags of.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

ApiResponse replaceTag(string $tag, array|string $publicIds = [], array $options = [])

Replaces all existing tags on the assets specified with the tag specified.

Parameters

Name Type Description
$tag string The new tag with which to replace the existing tags.
$publicIds array|string The public IDs of the assets to replace the tags of.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

See also

https://cloudinary.com/documentation/image_upload_api_reference#tags_method

static array buildUploadParams(array $options)

Consolidates the upload parameters.

Parameters

Name Type Description
$options array The optional parameters. See the upload API documentation.

Return Value

array

See also

https://cloudinary.com/documentation/image_upload_api_reference#upload_method

PromiseInterface uploadAsync(string $file, array $options = [])

Uploads an asset to a Cloudinary cloud.

The asset can be: * a local file path * the actual data (byte array buffer) * the Data URI (Base64 encoded), max ~60 MB (62,910,000 chars) * the remote FTP, HTTP or HTTPS URL address of an existing file * a private storage bucket (S3 or Google Storage) URL of a whitelisted bucket

This is an asynchronous function.

Parameters

Name Type Description
$file string The asset to upload.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

Exceptions

ApiError

See also

https://cloudinary.com/documentation/image_upload_api_reference#upload_method

ApiResponse upload(string $file, array $options = [])

Uploads an asset to a Cloudinary cloud.

The asset can be: * a local file path * the actual data (byte array buffer) * the Data URI (Base64 encoded), max ~60 MB (62,910,000 chars) * the remote FTP, HTTP or HTTPS URL address of an existing file * a private storage bucket (S3 or Google Storage) URL of a whitelisted bucket

Parameters

Name Type Description
$file string The asset to upload.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

Exceptions

ApiError

See also

https://cloudinary.com/documentation/image_upload_api_reference#upload_method

PromiseInterface unsignedUploadAsync(string $file, string $uploadPreset, array $options = [])

Uploads an asset to a Cloudinary cloud.

The upload is not signed so an upload preset is required.

This is an asynchronous function.

Parameters

Name Type Description
$file string The asset to upload.
$uploadPreset string The name of an upload preset.
$options array The optional parameters. See the upload API documentation.

Return Value

PromiseInterface

Exceptions

ApiError

See also

https://cloudinary.com/documentation/image_upload_api_reference#unsigned_upload_syntax

ApiResponse unsignedUpload(string $file, string $uploadPreset, array $options = [])

Uploads an asset to a Cloudinary cloud.

The upload is not signed so an upload preset is required.

Parameters

Name Type Description
$file string The asset to upload.
$uploadPreset string The name of an upload preset.
$options array The optional parameters. See the upload API documentation.

Return Value

ApiResponse

Exceptions

ApiError

See also

https://cloudinary.com/documentation/image_upload_api_reference#unsigned_upload_syntax

__construct(mixed $configuration = null)

Admin Api constructor.

Parameters

Name Type Description
$configuration mixed

string getUploadUrl(string $assetType = AssetType::AUTO, string $endPoint = UploadEndPoint::UPLOAD, array $params = [])

Gets upload URL for the specified asset type and endpoint.

Parameters

Name Type Description
$assetType string The asset type.
$endPoint string The endpoint name.
$params array Additional query parameters.

Return Value

string

Constants

MODE_DOWNLOAD