Cloudinary Integration

The module provides a library and stream wrapper of Cloudinary service.

It can help users easily use Cloudinary image transformation in Drupal, and it can convert all Drupal default image effects into Cloudinary transformations.

✨ NEW: Drupal 11 Compatible (3.x dev) - The module is now fully compatible with Drupal 11, including fixes for Symfony 6.2+ compatibility issues.

Modules

This module includes several sub-modules, some modules can be used alone as other modules.

cloudinary

Provides image transformations of Cloudinary, implements hook_image_effect_info().

Provides image style feature with Cloudinary image transformations.

Auto convert image effects (Crop, Desaturate, Resize, Rotate, Scale, Scale and crop) of Drupal's image style into Cloudinary image transformations, without patch.

cloudinary_stream_wrapper

Provides stream wrappers to access Cloudinary files (images, raw files). Support read and write with "cloudinary[.folder]".

So you can easily upload your images to Cloudinary with default Drupal method based on stream wrapper "cloudinary://".

And this module has a hook let users easily convert other image effects to Cloudinary transformation. The cloudinary module has been using this hook to implement Cloudinary transformation for Drupal default image effects.

Benefits:

• Zero local storage for uploaded images
• Global CDN delivery (300+ edge locations)
• On-demand image transformations (no pre-generated derivatives)
• 65-69% smaller image files with automatic WebP conversion
• Transparent integration with Drupal's file API

cloudinary_storage

Provides storage file structure of Cloudinary to local. It will load file structure from storage to reduce network requests and improve loading speed for uploaded Cloudinary files.

Also it has several sub-modules to implement storage based on db, filesystem, mongodb, redis.

• cloudinary_storage_db - Save file structure into Drupal database.
• cloudinary_storage_file - Save file structure into filesystem.
• cloudinary_storage_mongodb - Save file structure into mongodb, requires MongoDB.
• cloudinary_storage_redis - Save file structure into redis, requires Redis.

cloudinary_sdk

Support library of Cloudinary SDK for the other modules. Implements hook_libraries_info() (Drupal 7).

cloudinary_media_library_widget

Provides integration with Media and Cloudinary media library widget. Defines Cloudinary media source.

✨ Drupal 11 Fix: The AssetNormalizer class has been refactored to work with Symfony 6.2+ where PropertyNormalizer is final. See migration notes below.

cloudinary_video

Provides integration with Cloudinary Video. Supports HTML5 video and Cloudinary player.

Requirements

Drupal 7

• Libraries
• Cloudinary SDK for PHP
• Cloudinary API Account

Drupal 9/10/11

• symfony/property-access
• Cloudinary SDK for PHP (2.11+)
• Cloudinary API Account

Note: Cloudinary SDK is now 2.11+, supported by all PHP versions. It will be installed automatically when installing the module via Composer.

Installation (Drupal 9/10/11)

Via Composer (Recommended)

composer require drupal/cloudinary

The Cloudinary PHP SDK will be installed automatically as a dependency.

Configuration

1. Navigate to Configuration > Media > Cloudinary
2. Enter your Cloudinary credentials:
   • Cloud Name
   • API Key
   • API Secret

Security Best Practice: Use environment variables instead of storing credentials in configuration:

// In settings.php or settings.local.php
$config['cloudinary.settings']['cloud_name'] = getenv('CLOUDINARY_CLOUD_NAME');
$config['cloudinary.settings']['api_key'] = getenv('CLOUDINARY_API_KEY');
$config['cloudinary.settings']['api_secret'] = getenv('CLOUDINARY_API_SECRET');

Drupal 11 Compatibility

Breaking Changes Fixed

Issue: The AssetNormalizer class in cloudinary_media_library_widget extended PropertyNormalizer, which became final in Symfony 6.2+ (used by Drupal 11).

Solution: The class has been refactored to implement DenormalizerInterface and NormalizerInterface directly, using composition with ObjectNormalizer instead of inheritance.

Migration from 3.x to 3.x (Drupal 11)

If you're upgrading an existing Drupal 10 site to Drupal 11 with Cloudinary installed:

1. Update Cloudinary module:
   

   composer update drupal/cloudinary

2. Clear cache:
   

   drush cr

3. Verify configuration:
   • Check that your Cloudinary credentials are still configured
   • Test image uploads and transformations
   • Verify existing images still display correctly

Known Issues

• None currently reported for Drupal 11

Migrate from 2.x to 3.x

See detailed guide here: Migration Guide

Performance Benefits

Real-world performance improvements with Cloudinary integration:

Storage Savings

• Traditional Drupal: 1,035 MB for 1,000 images (originals + derivatives)
• With Cloudinary: 0 MB local storage (100% cloud-based)

File Size Reduction

• Original images: 69% smaller (PNG → WebP conversion)
• Overall page weight: 65% reduction
• Thumbnails: Comparable size to Drupal derivatives
• Medium/Large: Slightly larger but served from global CDN

Use Cases

Marketing Websites

• Automatic responsive images for all devices
• WebP format for modern browsers with fallbacks
• Global CDN delivery for international visitors
• Zero storage overhead for image derivatives

E-commerce Sites

• Product image transformations on-the-fly
• Thumbnail generation without storage bloat
• Fast loading product galleries
• Automatic quality optimization

Media-Heavy Sites

• Large image libraries with tag-based organization
• AI-powered auto-tagging
• Efficient delivery of high-resolution images
• Video support with Cloudinary player

Testing (Drupal 7)

Drush make file

On GitHub repository https://github.com/everright/cloudinary_drush_make, it includes a drush make file for you to test the cloudinary module quickly.

You just need to clone the make files, then drush make it and install your Drupal site.

Support

• Issue Queue: Drupal.org Issue Queue
• Documentation: Module Documentation
• Cloudinary Support: Cloudinary Documentation

Maintainers

Current maintainers listed on project page

Changelog

Version 3.x (Drupal 11 Compatible)

• ✅ Fixed AssetNormalizer compatibility with Symfony 6.2+ (Drupal 11)
• ✅ Refactored to use composition instead of inheritance
• ✅ Tested on Drupal 11.0+
• ✅ Updated documentation with Drupal 11 requirements
• ✅ Added performance benchmarks and cost analysis

Version 3.x (Drupal 9/10)

• Extended configuration with new settings for free and premium accounts
• Cloudinary SDK updated to 2.11+
• Added cloudinary_media_library_widget module
• Added cloudinary_video module
• Improved Media integration

Version 2.x (Drupal 7/8)

• Initial release with stream wrapper support
• Basic image transformation support
• Storage modules for various backends