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

On-Demand Viewing of Live Video Presents New Opportunities

In early 2020, Cloudinary was planning its fourth annual ImageCon conference, a two-day event in the heart of San Francisco, where we’d congregate with curious digital-media minds to brainstorm best practices for media management. Instead, the COVID-19 pandemic forced the entirety of ImageCon 2020 online. As with all other events being planned, we had to overhaul the content to be communicated on video. Gratifyingly, we found the right partner—the event platform Bizzabo—to turn that into a reality.

Read more
Why the Future of E-commerce Is Live

In a previous post, I discussed how “going live” is gaining popularity across industries and verticals. What began as a way for gamers to jam together has evolved into a medium for broader entertainment and business purposes. To continue the conversation, this post unpacks the current trends of shoppable live streams to shine a light on how brands are leveraging “lives” to connect with shoppers in new ways.

Read more
An Overview of Live-Streaming Video Trends

“Let’s go live.” For decades, that’s what newscasters say as they cut to real-time footage of a colleague reporting in the field. The live-video feed adds visual interest and perspective to a story beyond what can be communicated by someone sitting behind the news desk. In the same way, live-streaming video nowadays adds context to other consumer environments. From gaming and events to shopping and social media, “going live” enhances everyday experiences, and it’s something anyone can do with relative ease.

Read more
Readying Live Streams for Video on Demand

When planning a live broadcast or stream, companies often overlook the redistribution phase, but live-stream videos are useful well beyond their initial streaming. Why? Because not everyone watches the first run. For a wider audience, it makes sense to repost live content on your website under an “events” tab, on YouTube, and other social sites for video on demand (VOD). However, preparing footage for reposting can be a lot of work.

Read more