PHP migration guide
Last updated: Sep-02-2024
Introduction
The latest major version of the Cloudinary PHP SDK is designed to provide a simpler and more enhanced developer experience. This guide will explain how to migrate from your existing legacy PHP SDK version, including the changes you'll need to make to your code and any other considerations.
Key improvements in the latest PHP SDK version:
- A new action-based syntax, designed to make building delivery URLs and transformations more logical and discoverable.
- When compiled to the final delivery URL, each action (including any action qualifiers) represents a different component (separated by a '/'), for example:
/c_scale,w_400/f_auto/q_auto/
, rather than/c_scale,f_auto,q_auto,w_400/
.
- When compiled to the final delivery URL, each action (including any action qualifiers) represents a different component (separated by a '/'), for example:
- Newly added autocomplete to list options and parameters and ensure only those that are supported can be used together.
The action-based syntax used in the latest version of the SDK may cause URLs to be formed differently from those generated by the legacy version of SDK.
For example:
-
URL generated with legacy SDK:
https://res.cloudinary.com/demo/image/upload/c_scale,f_auto,q_auto,w_400/sample.jpg
-
URL generated with latest SDK:
https://res.cloudinary.com/demo/image/upload/c_scale,w_400/f_auto/q_auto/sample.jpg
Even if the delivered media file looks and behaves identically, changes to URLs can have the following implications:
- You may see a one-time increase in transformation counts
- You may see a one-time increase in storage usage for the new derived assets
- You may see a one-time increase in add-on usage when add-on transformation parameters are used in the URL
- CDN caches may need to be warmed with the new derived assets
- If strict transformations are enabled for your your product environment (in the Security page of your Console Settings), you need to allow the new transformations
- If you require transformations to be generated eagerly, for example long videos, you need to regenerate these via the latest SDK, using the
eager
parameter of the explicit method.
To reduce the impact of all of the above, we recommend using the fromParams method for your existing transformation URLs, especially if your existing app delivers a large number of transformed assets. This maintains the formations of the transformations, so the URLs remain the same.
For all new transformation URLs that you add to your application, we recommend using the new action-based SDK syntax offered by the latest version of the SDK.
For full documentation on the latest version of the PHP SDK, see the PHP SDK guide.
Prerequisites
Before installing the SDK ensure you have removed the existing legacy SDK dependency from your application.
Installation
Install the SDK using composer in the same way as your existing version, specifying the new version you want to install.
For example:
You can also install manually by downloading the package from the GitHub repository and it including it in your project.
Migration
As part of migrating from the legacy version to the latest version of the Cloudinary PHP SDK, you will need to update your code in order to retain your existing functionality and allow you to take advantage of the new functionality. The main difference between the latest version and the older versions is the way your media is delivered. The latest version provides a new syntax for building your delivery URLs, designed to make it simpler and more logical. You may also need to update the way you set your global configuration. There is also a small change to the way you access upload and administration methods, this will require minor refactoring.
Configuration
If you currently set your configuration using the CLOUDINARY_URL
environment variable, you will not need to make a change to this. If you set your configuration globally, you will need to update this to be compatible with the latest version of the Cloudinary PHP SDK.
You can set your configuration using an instance of the Configuration
class:
Alternatively, if you require multiple instances, you can use the Cloudinary
object, for example:
Upload
The upload method in the latest version of the Cloudinary PHP SDK is no longer a static method. To upload assets to Cloudinary you will now need to use the UploadApi
class.
Update all instances of the upload
method to use the method from the UploadApi
class, rather than the Cloudinary Uploader.
For example, to upload the image "my_image":
Becomes:
You can find more detailed documentation in the PHP SDK guide.
Admin
Similar to upload, the admin methods are now accessed from the AdminApi
class.
For example, to get details of an asset using the assets
method (resources
in the legacy version):
Becomes:
You can find more detailed documentation in the PHP SDK guide.
Delivery
The latest version of the Cloudinary PHP SDK uses a new syntax for creating Cloudinary delivery URLs and media tags, so to fully update your code, you would need to replace the old syntax with the correct new syntax. However, to make the initial migration as easy as possible, the latest SDK provides a fromParams
helper method that takes the original transformations in the old syntax as a parameter. This allows you to wrap your existing transformation syntax and maintain the structure of the generated transformation URLs.
fromParams
method. If you replace your existing transformations using the new SDK transformation syntax, you may find your URLs are generated in a slightly different way. See Things to know before migrating to the latest SDK, for the implications of these changes to transformation URLs.You will need to update any instance of:
-
cloudinary_url
-
cl_image_tag
-
cl_video_tag
Cloudinary URLs
To migrate your Cloudinary URLs from the legacy version of the SDK to the latest version of the Cloudinary PHP SDK, you will need to replace the cloudinary_url
helper method with a new media
instance and use the fromParams
helper method.
For example:
Becomes:
Cloudinary image and video tags
For image and video tags, replace cl_image_tag
and cl_video_tag
with ImageTag
and VideoTag
respectively and include the fromParams
helper method.
For example:
Becomes:
Additional types
When an image is delivered from a video or vice versa, you need to identify the delivery type and use the correct delivery method.
For example, to deliver a thumbnail image from a video, with the legacy SDK you could use cl_image_tag
and set the resource_type
to "video":
For the latest version of the Cloudinary PHP SDK you need to deliver the correct media type. In this example you would use VideoThumbnailTag
:
- Take a look at the full latest PHP SDK guide.
- Learn more about uploading images and videos using the PHP SDK.
- See examples of powerful image and video transformations using PHP code
and see our image transformations and video transformations docs.
- Check out Cloudinary's asset management capabilities, for example, renaming and deleting assets, adding tags and metadata to assets, and searching for assets.
- Stay tuned for updates with the Programmable Media Release Notes and the Cloudinary Blog.