Introducing the Cloudinary PHP SDK, Mark II

Cloudinary supports a wide range of SDKs, many of which have been around for quite some time now. The PHP SDK was initially released in 2012, nine years ago, and much has changed since then with regard to programming languages and development concepts. This means that the SDKs need a refresh in order to be aligned with the latest standards and best practices, also to comply with the current language standards and syntax usage.

Since our existing SDKs have to support a wide range of specific technology versions, reducing support in a minor release is unacceptable. So, Cloudinary is revamping the entire SDK suite, making it more modern, intuitive, and user friendly. The PHP SDK is the first to undergo a major overhaul with a major release. Our main focus for v2 is on enhancing developer experience with the following features:

• Structured action-based syntax
• High discoverability with integrated autocomplete
• Maintainability
• Error handling
• Preserving flexibility and future compatibility
• Comprehensive reference documentation

Actions

Cloudinary’s SDK v1 suite was all about wrapping our URL syntax, which requires knowledge of the URL’s transformation syntax. For example, when creating a simple transformation on an image that includes rotating, cropping, and an effect, the v1 code reads as follows:

#SDK 1
cloudinary_url("bike", 
  array(
    "angle"=>20, 
    "crop"=>"crop", 
    "gravity"=>"face", 
    "effect"=>"cartoonify"));

As part of our focus on the developer experience, we want the new SDK to have an easy, strongly typed, discoverable syntax, enabling developers to write their code quickly, without compromising the flexibility and future compatibility in the current SDKs. To that end, we introduced a structured way of building action-oriented transformations. The new code for the example above reads this way:

#SDK 2
$cld = new Cloudinary();
$cld->image('bike')
  ->rotate(Rotate::byAngle(20))
  ->resize(Resize::crop()->gravity(Gravity::focusOn(FocusOn::face()))
  ->effect(Effect::cartoonify())->toUrl();

Discoverability

The action-oriented structure in v2 improves discoverability, meaning that you need not learn the URL transformation syntax and can code more easily. The new structure also means that—

• You work in a typed environment, in which the classes, methods, and variables of the SDK are autocompleted by the IDE, with the relevant options and values listed in a pop-up while you’re typing.
• The IDE verifies the validity of your code, catching errors early on with no time lag for server errors.

Maintainability and Configuration

SDK v2 enables the adoption of new features quickly, reduces support of old technologies, and simplifies the configuration options. With the new modular structure, you can decide what parts of the SDK to use, configuring settings in several levels through a configuration hierarchy. For example, to set the configuration globally via a JSON object, code like this:

use Cloudinary\Configuration\Configuration;
Configuration::instance([
  'cloud' => [
    'cloud_name' => 'my_cloud_name', 
    'api_key' => 'my_key', 
    'api_secret' => 'my_secret'],
  'url' => [
    'secure' => true]]);

The new SDK also supports multiple instances, each of which you can configure with a Cloudinary object. For example:

use Cloudinary\Configuration\Configuration;
$cloudinary = new Cloudinary([
  'cloud' => [
    'cloud_name' => 'my_cloud_name',
    'api_key'  => 'my_key',
    'api_secret' => 'my_secret',
  'url' => [
    'secure' => true]]]);

Management APIs

PHP SDK v2 offers revamped Upload and Admin API methods for managing, organizing, and creating media assets. See the examples below.

To upload an asset to your account:

use Cloudinary\Api\Upload\UploadApi;
(new UploadApi())->upload('my_image.jpg')

To list all the image tags that begin with shoe:

use Cloudinary\Api\Admin\AdminApi;
$result = (new AdminApi())->tags(["prefix" => "shoe"]);

Documentation

PHP SDK v2 includes extensive documentation strings within the code, making it much easier to understand our code and its purpose. The strings are displayed within the IDE tooltips and automatically exported into an autogenerated PHP SDK Reference Guide, an addition to the Cloudinary PHP SDK User Guide.

Backward Compatibility and Migration

Be assured that all your existing URLs embedded in webpages will continue to work. Only the way in which PHP SDK v2 generates transformations has changed, not the output. So, just keep the URLs that are in place and start creating new ones with v2.

Even though the new syntax is much clearer, more logical, and more intuitive, a significant conceptual change does exist between the two syntaxes. Moving to a new SDK generally entails updating your code.

To help you with that update with minimal changes and without having to figure out the nuances and to translate your code to the new syntax, we’ve added a special action called fromParams with which you can enclose the code syntax in v1 of the SDK.

For example, this code in SDK v1—

#SDK 1
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 the following:

#SDK 2
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")
)));

For more details and examples on upgrading to v2 of the SDK, see our PHP Migration Guide.

Summary

PHP SDK v2 offers an action-oriented, structured syntax; high discoverability; integrated autocomplete, an intuitive migration path; along with in-depth reference documentation. Consequently, coding to leverage Cloudinary’s capabilities is much easier. For details, check out our PHP documentation and the PHP Reference Guide.