Last updated: Oct-31-2023
Cloudinary provides an API for uploading images, videos, and any other kind of file to the cloud. Files uploaded to Cloudinary are stored safely in the cloud with secure backups and revision history. Cloudinary's APIs allow secure uploading from your servers, directly from your visitors' browsers or mobile applications, or fetched via remote public URLs.
Cloudinary's PHP Library wraps Cloudinary's upload API and simplifies the integration. PHP methods are available for easily performing PHP image and video uploads to the cloud and PHP view helper methods are available for uploading directly from a browser to Cloudinary.
This page covers common usage patterns for PHP image and video upload with Cloudinary.
You can upload images, videos, or any other raw file to Cloudinary from your PHP code. Uploading is done over HTTPS using a secure protocol based on your product environment's
The following PHP method uploads an image to the cloud:
For example, uploading a local image file named 'my_image.jpg':
The file to upload can be specified as a local path, a remote HTTP or HTTPS URL, a whitelisted storage bucket (S3 or Google Storage) URL, a data stream, a base64 data URI, or an FTP URL. For details and code examples of uploading using each of these data source types, see Required upload parameters.
You upload videos in exactly the same way as images. However, the
upload method supports uploading files only up to 100 MB. To upload larger videos, use the upload_large method, which uploads large files to the cloud in chunks.
upload_large method has the identical signature and options as the
upload method, with the addition of an optional
chunk_size parameter (default 20 MB).
The following example uploads
dog.mp4 to Cloudinary and stores it in a bi-level folder structure with the public ID
dog_closeup. It also performs two eager transformations that resize the video to a square and a small rectangle.
By default, uploading is performed synchronously. Once finished, the uploaded image or video is immediately available for transformation and delivery. An upload call returns a Hash with content similar to the following:
The response includes HTTP and HTTPS URLs for accessing the uploaded media asset as well as additional information regarding the uploaded asset: The Public ID, resource type, width and height, file format, file size in bytes, a signature for verifying the response and more.
The upload sample mentioned above allows your server-side PHP code to upload media assets to Cloudinary. In this flow, if you have a web form that allows your users to upload images or videos, the media file's data is first sent to your server and only then uploaded to Cloudinary.
A more efficient and powerful option is to allow your users to upload images and videos in your client-side code directly from the browser to Cloudinary instead of going through your servers. This method allows for faster uploading and a better user experience. It also reduces load from your servers and reduces the complexity of your PHP applications.
You can upload files directly from the browser using signed or unsigned calls to the upload endpoint, as shown in the Upload multiple files using a form examples.
Alternatively, you can use Cloudinary's jQuery plugin as described in the following sections.
Cloudinary's jQuery plugin requires your
cloud_name and additional configuration parameters.
api_secretin public client-side code.
To automatically set-up Cloudinary's configuration, include the following line in your view or layout:
The Cloudinary jQuery library utilizes the Blueimp File Upload library to support uploading media directly from the browser. You must explicitly initialize this library:
Direct uploading from the browser is performed using XHR (Ajax XMLHttpRequest) CORS (Cross Origin Resource Sharing) requests. To support older browsers that do not support CORS, the jQuery plugin gracefully degrades to an iframe based solution. This solution requires placing
Embed a file input tag in your HTML pages using one of the following methods:
cl_upload_tag: images or videos
The following example adds a file input field for images to your form. Selecting or dragging a file to this input field automatically initiates uploading from the browser to Cloudinary.
When uploading is completed, the identifier of the uploaded image is set as the value of a hidden input field of your selected name (e.g., 'image_id' in the example above).
You can now display a directly uploaded image in the same way you would display any other Cloudinary hosted image:
The following example renders a direct file upload input field using the
cl_upload_tag helper method. Although the default
resource_type for this method is
video type is explicitly defined, and asynchronous eager transformations are used to generate adaptive bitrate streaming content. The
html parameter is used to include standard HTML parameters (in this case, an
id attribute) in the generated tag.
Cloudinary's jQuery library also enables an enhanced uploading experience with options like showing a progress bar, displaying a thumbnail of the uploaded image, drag & drop support, uploading multiple files and more.
For example, bind to Cloudinary's
cloudinarydone event if you want to be notified when an upload to Cloudinary has completed. You will have access to the full details of the uploaded image and you can display a cloud-generated thumbnail of the uploaded images using Cloudinary's jQuery plugin. The following code creates a 150x100 thumbnail of an uploaded image and updates an input field with the public ID of this image.
You can find more details and options in the jQuery documentation.