PHP v2 migration guide (Beta)
Introduction
Cloudinary PHP SDK 2 is designed to provide a simpler and more enhanced developer experience. This guide will explain how to migrate from your existing PHP SDK version, including the changes you’ll need to make to your code and any other considerations.
Key improvements for SDK 2:
- 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 represents a different component (separated by a '/').
- Newly added autocomplete to list options and parameters and ensure only those that are supported can be used together.
For full documentation on the PHP SDK 2, see the SDK guide.
Prerequisites
Before installing the SDK ensure you have removed the existing SDK 1 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:
composer config repositories.cloudinary_php_v2 vcs https://github.com/cloudinary/cloudinary_php_v2.git composer require cloudinary/cloudinary_php:2.0.0-beta
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 to SDK 2, 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 SDK 2 and older versions is the way your media is delivered. SDK 2 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 SDK 2.
You can set your configuration using an instance of the Configuration
class:
Configuration::instance(['account' => ['cloud_name' => 'n07t21i7', 'key' => '123456789012345', 'secret' => 'abcdeghijklmnopqrstuvwxyz12']]);
Alternatively, if you require multiple instances, you can use the Cloudinary
object, for example:
$cloudinary = new Cloudinary( [ 'account' => [ 'cloud_name' => 'n07t21i7', 'key' => '123456789012345', 'secret' => 'abcdeghijklmnopqrstuvwxyz12', ], ] );
Upload
The upload method in SDK 2 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 2 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 resource
method:
#SDK 1.x require "cloudinary.php"; require "api.php"; $api = new \Cloudinary\Api(); $result = $api->resource("sample");
Becomes:
#SDK 2.x use Cloudinary\Api\Admin\AdminApi; $result = (new AdminApi())->resource("sample");
You can find more detailed documentation in the PHP SDK 2 guide.
Delivery
The SDK provides a fromParams
helper method to make the initial migration as easy as possible. This method takes the original transformations in the old syntax as a parameter. SDK 2 also uses a new syntax for creating Cloudinary URLs and media tags. You will need to replace the old syntax with the correct new syntax.
fromParams
method. If you replace your existing transformations using the new SDK 2 transformation syntax, you may find your URLs are generated in a slightly different way. This will result in new derived assets being created and an increase in usage.You will need to update any instance of:
-
cloudinary_url
-
cl_image_tag
-
cl_video_tag
Cloudinary URLs
To migrate your Cloudinary URLs from SDK 1 to SDK 2, you will need to replace the cloudinary_url
helper method with a new media
instance and use the fromParams
helper method.
For example:
#SDK 1.x cloudinary_url("actor", array("transformation"=>array( array("effect"=>"cartoonify"), array("radius"=>"max"), array("effect"=>"outline:100", "color"=>"lightblue"), array("background"=>"lightblue"), array("height"=>300, "crop"=>"scale") )))
Becomes:
#SDK 2.x Media::fromParams("actor", array("transformation"=>array( array("effect"=>"cartoonify"), array("radius"=>"max"), array("effect"=>"outline:100", "color"=>"lightblue"), array("background"=>"lightblue"), array("height"=>300, "crop"=>"scale") )));
Cloudinary image and video tags
For image and video tags, replace the current cl_image_tag
and cl_video_tag
with ImageTag
and VideoTag
respectively and include the fromParams
helper method.
For example:
#SDK 1.x cl_image_tag("actor", array("transformation"=>array( array("effect"=>"cartoonify"), array("radius"=>"max"), array("effect"=>"outline:100", "color"=>"lightblue"), array("background"=>"lightblue"), array("height"=>300, "crop"=>"scale") )))
Becomes:
#SDK 2.x ImageTag::fromParams("actor", array("transformation"=>array( array("effect"=>"cartoonify"), array("radius"=>"max"), array("effect"=>"outline:100", "color"=>"lightblue"), array("background"=>"lightblue"), array("height"=>300, "crop"=>"scale") )));
Additional types
If content within your delivery URL where an image is delivered from a video or vice versa, you’ll need to identify the delivery type and use the correct delivery method. For example, if you wanted to deliver a thumbnail image from a video, with SDK 1.x you could use cl_image_tag
and set the resource_type
to "video":
#SDK 1.x cl_image_tag("dog.jpg", array("start_offset"=>"4", "width"=>350, "height"=>350, "radius"=>20, "effect"=>"grayscale", "border"=>"5px_solid_black", "crop"=>"crop", "resource_type"=>"video"))
For SDK 2.x you need to deliver the correct media type, for this example you would use VideoThumbnailTag
:
#SDK 2.x VideoThumbnailTag::fromParams("dog.jpg", array("start_offset"=>"4", "width"=>350, "height"=>350, "radius"=>20, "effect"=>"grayscale", "border"=>"5px_solid_black", "crop"=>"crop", "resource_type"=>"video"));
- Take a look at the full PHP SDK 2 guide.
- Learn more about uploading images and videos using the PHP SDK.
- See examples of powerful image and video manipulations using PHP code
and see our image transformations and video manipulation docs. - Check out Cloudinary's asset administration capabilities.
- Stay tuned for updates, tips and tutorials in Product Updates and Blog Posts.