Cloudinary Blog

Introducing the Cloudinary PHP SDK, Mark II

New Cloudinary PHP SDK Released

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:

Copy to clipboard
#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:

Copy to clipboard
#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:

Copy to clipboard
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:

Copy to clipboard
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:

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

To list all the image tags that begin with shoe:

Copy to clipboard
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—

Copy to clipboard
#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:

Copy to clipboard
#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.

Recent Blog Posts

How to Use the Cloudinary Media Editor Widget

At Cloudinary, we manage the entire pipeline of media assets for thousands of customers of varying sizes from numerous verticals.

As part of our commitment to support the entire flow of media assets, we are now introducing an intuitive media editing widget: an out­-of­-the-­box, interactive UI providing your users with a set of common image editing actions for immediate use on your website or web app. The widget is interactive and simple, built on Cloudinary's transformation capabilities, and requiring only a few lines of code to integrate. Afterwards, you can seamlessly and effortlessly add content to your site or app with no need for in-house image editing capabilities.

Read more
Shoppable Video Is Becoming Popular in E-Commerce

As pandemic restrictions necessitated, many shopping trips in 2020 took place outside the traditional brick-and-mortar store, or at least void of the physical aisle-browsing experience. Same-day curbside pickup became a safe and convenient alternative, and e-commerce transactions skyrocketed as consumers shopped online. In fact, Digital Commerce 360 estimates that, compared to 2019, e-commerce transactions grew by more than 40% last year.

Read more
Enhance Your Travel Site With Cloudinary in Anticipation of a Return to New Normal

Read more
The Benefits of Headless DAMs

Headless is not a buzzword anymore. In fact, the concept of headless architecture is gaining momentum due to the flexibility it offers for composing new experiences and for tackling the undue complexity of an ever-evolving technology stack. That’s because while the evolution of the martech landscape has enabled disruptive, digital innovations, the approach of buying point solutions for solving specific challenges can expose companies to the complicated nature of new technologies, systems, and platforms.

Read more

Building Display Ads With Transparent Video

By Afzaal Ahmad Zeeshan
Build Web Ads With Transparent Video to Attract User Engagement

Billions of views on the Internet every day drive one of the biggest industries on the planet: advertising. The sheer size of that market and the competitive nature of vying for consumer attention results in a constant need for innovation. Readers are jaded, and display ads are blind spots.

Read more