More Products
Menu

Extending Magento 2 with the Cloudinary extension: A developer's guide

Last updated: Jul-25-2025

Introduction

  • The Cloudinary Magento (Adobe Commerce) extension leverages the Cloudinary PHP SDK to authenticate, manage assets, and generate dynamic media URLs.
  • The extension automatically handles media URL generation for standard Magento entities like products, swatches, and some CMS/Widget blocks. However, custom code and third-party extensions often require manual integration to utilize Cloudinary URLs.
  • This guide is for developers aiming to extend Cloudinary support to custom functionalities, integrate with third-party extensions, or enhance the official extension with additional business logic.

On this page:

Before adding code

  • For simple use cases where you only need a Cloudinary URL for a known asset and don't require Magento's fallback mechanisms or dynamic transformations based on extension settings, consider using the Cloudinary asset URL directly (e.g., from the Cloudinary DAM).
  • The primary downside of using raw Cloudinary URLs is the lack of Magento-side fallback to default media URLs if an asset isn't available on Cloudinary or if the extension is disabled.

Core concepts

Cloudinary PHP SDK integration

The extension stores your Cloudinary credentials, modifies Magento to serve media assets from Cloudinary, and embeds Cloudinary widgets and players into Magento product pages. The powerful and well-documented Cloudinary PHP SDK is used by the extension to sync assets between Cloudinary and Magento, and for URL generation, among other things.

Getting Cloudinary configuration

  • If your use case is not covered by the extension's UrlGenerator class, you may need to use the SDK directly. You'll need to initialize it with your Cloudinary account details (cloud name, API key, API secret) which are stored by the Magento extension.
    • Images synced from Magento to Cloudinary typically use their Magento file path (starting from media/) as the public ID (e.g., catalog/product/s/a/sample.jpg).
    • You can use the path with the file extension (e.g., sample.jpg) or without (sample) as the public ID.

Fallback URLs

The Magento extension includes mechanisms (like its ImageFactory) to serve local Magento URLs if the Cloudinary extension is disabled or if a specific image hasn't been synced to Cloudinary. This is crucial for frontend display.

Automatic setup: Use extension classes (recommended)

When the extension's UrlGenerator class is used, the underlying Cloudinary SDK is instantiated for you.

Manual setup: Initializing a Cloudinary PHP SDK instance

The recommended approach for URL generation is to use the extension's UrlGenerator class. However, for more advanced use cases you may need to instantiate and configure the Cloudinary SDK using the credentials stored by the Magento 2 extension. You can do this by injecting the extension's ConfigurationInterface and ConfigurationBuilder into your class.

Option 1: Instance-scoped SDK (recommended if you must use the SDK directly)

This approach creates an instance-scoped, encapsulated Cloudinary SDK instance. It's generally preferred for better dependency management and testability. You'll use helper methods on this instance (e.g., $this->cld->image('public_id')).

Option 2: Application-wide SDK configuration

This approach configures a single, application-wide SDK instance. Use this if the SDK is needed in multiple disparate parts of your code without wanting to pass around a Cloudinary object. After this setup, you'll use SDK classes directly (e.g., new \Cloudinary\Asset\Image('public_id')).

Generating URLs

From file paths using the Cloudinary Magento extension's UrlGenerator class (recommended)

The most straightforward way to obtain Cloudinary URLs is using the extension's UrlGenerator class.

The benefit of this approach is that the PHP SDK configuration and fallback logic for URL generation are automatically handled.

From file paths using the extension's ImageFactory alongside the SDK

For frontend rendering where you need a reliable URL (either Cloudinary or a local Magento fallback), the extension's ImageFactory is invaluable. It checks if the image is synced and if the Cloudinary extension is active.

From URLs

On occasion, you'll only have access to the Magento URL and not the file path. In such cases, you'll need to perform string manipulation to extract the original path.

Examples of string manipulations from the extension source code:

Working with transformations

Using the extension's default transformations

The Magento extension defines default transformations (e.g., auto-format, auto-quality).

When the extension's UrlGenerator class is used, these default transformations are automatically applied to the generated URL.

For more advanced use cases, you can retrieve these settings and apply them using the SDK.

Handling videos

The Cloudinary Magento extension stores the raw Cloudinary URLs for product videos with no local copy. The URL is then parsed to extract the public ID and passed to the Cloudinary Product Gallery widget or Video Player. You can store the public ID directly in your own code or store the full URL and leverage the extension's helpers to extract the public ID.

Using the extension's parseCloudinaryUrl method

Common strategies for modifying core and third-party code

Plugins (interceptors)

  • Plugins (interceptors) are the most common and Magento-recommended approach for modifying external code behavior.
  • Plugins allow you to intercept public methods of other classes. You can change arguments before a method is called (before), change the result after it's called (after), or wrap the original method entirely (around).
  • When modifying methods that generate image/video URLs in third-party extensions, you can use the techniques described in Generating URLs within your plugin logic.
  • Caution: If you resort to parsing HTML returned by a method to replace <img> tag src attributes, be mindful of performance. Extensive HTML parsing can impact Time To First Byte (TTFB). Ensure your parsing logic is efficient and targeted.

Dependency injection (preferences)

  • You can configure Magento's ObjectManager to replace an external class with your own modified class (a subclass or a complete re-implementation).
  • This approach is more intrusive than plugins and should be used cautiously. It can fail if the external classes aren't instantiated by Magento's ObjectManager (e.g., if they're created directly using the new keyword).

Advanced use

Direct SDK usage for specific backend tasks

For specific backend tasks, like custom synchronization scripts or batch operations where Magento's fallback or extension-specific logic isn't needed, you can initialize and use the Cloudinary PHP SDK directly. You'd only need to retrieve the Cloudinary configuration from the extension (as shown in the Setup section) and then proceed with full SDK capabilities.

Troubleshooting / common pitfalls

  • Caching: Magento relies heavily on caching. After making configuration changes in the Cloudinary extension settings or deploying code changes, always clear relevant Magento caches (e.g., config, block_html, full_page).

Additional resources

Documentation

Source code

✔️ Feedback sent!

Rate this page: