Download the PHP package aysnc/wordpress-dynamic-media without Composer

WordPress Dynamic Media

Automatically transform WordPress media URLs into dynamic, optimized URLs powered by image transformation services like Cloudinary.

Requirements

• PHP 8.3+
• WordPress 6.2+
• A Cloudinary account with auto-upload mapping configured

Installation

The plugin auto-activates through Composer's wordpress-plugin type. If your setup doesn't support that, activate it manually in wp-admin.

What It Does

When you upload an image to WordPress, it gets stored at a URL like this:

With this plugin active, that same image is served through Cloudinary with on-the-fly transformations:

The plugin hooks into WordPress's image handling at multiple levels, so this happens automatically - no need to change your templates or content.

Here's what gets transformed:

• wp_get_attachment_image() and related functions
• Responsive srcset attributes
• Images embedded in post/page content
• Any code using image_downsize()
• REST API media endpoints (/wp/v2/media)

REST API Support

The plugin transforms URLs in REST API responses by default. When you fetch media via /wp/v2/media, both source_url and all size URLs in media_details.sizes are transformed.

This is enabled by default. To disable it globally:

Or disable it per-request (useful for admin/editor contexts):

Generating URLs

The real power is in generating dynamic URLs on demand. Given any attachment ID, you can build a URL with whatever transformations you need.

The Basics

These parameters work across all adapters:

Adapter-Specific Transforms

Need more than dimensions? The transform array lets you pass parameters directly to your adapter:

On portability: width, height, and hard_crop work across all adapters - the plugin translates these for each service. The transform array does not. It's passed directly to your adapter, untouched.

This is intentional. Image services have different capabilities - Cloudinary's gravity: 'face' has no equivalent in every provider. Rather than maintain a leaky abstraction, we give you direct access. The trade-off: if you switch adapters, any code using transform needs to be updated.

Best practice: Don't call Media::get_dynamic_url() with transform scattered throughout your codebase. Wrap it in your own function:

That way if you change adapters - or just want to tweak your transforms - you have one place to update instead of hunting through templates.

Configuration

The plugin needs to know your Cloudinary details. Add this filter to your theme or a mu-plugin:

That's the minimum config. The auto_mapping_folder should match the folder name you set up in Cloudinary's auto-upload settings.

Full Configuration Options

Using Environment Variables

Since configuration happens through a filter, you can pull values from wherever makes sense for your setup:

Hooks & Filters

aysnc_wordpress_dynamic_media_config

Global plugin configuration.

aysnc_wordpress_dynamic_media_rest_enabled

Control REST API transformation on a per-request basis. Receives the request and attachment objects for context.

Parameters:

• $enabled - Whether REST API transformation is enabled (default: true)
• $request - The REST request object
• $attachment - The attachment post object

aysnc_wordpress_cloudinary_config

Configure the Cloudinary adapter. See Configuration above.

aysnc_wordpress_cloudinary_args

Modify transformation arguments before the Cloudinary URL is built. Use this for site-wide settings like auto-optimization:

This filter is Cloudinary-specific. If you switch adapters, you'll replace this with the equivalent for your new service.

Supported transformation parameters:

See Cloudinary's transformation reference for the complete list.

aysnc_wordpress_dynamic_media_url

Modify the final dynamic URL before it's returned. Works with any adapter.

Parameters:

• $url - The generated URL
• $attachment_id - WordPress attachment ID
• $args - Transformation arguments (width, height, hard_crop, etc.)

aysnc_wordpress_dynamic_media_srcset_dimensions

Adjust dimensions for individual srcset entries.

Parameters:

• $dimensions - Array with width, height, and optionally hard_crop
• $attachment_id - WordPress attachment ID
• $image_meta - WordPress attachment metadata
• $image_src - Original image source URL

aysnc_wordpress_dynamic_media_content_image_src

Override the URL for images in post content. Return a string to use your custom URL, or null to let the plugin generate one.

Parameters:

• $src - Current source (null on first pass)
• $attachment_id - WordPress attachment ID
• $original_src - The original src attribute value
• $width - Image width attribute
• $height - Image height attribute
• $size - Image size name extracted from class (e.g., large, thumbnail)

aysnc_wordpress_cloudinary_upload_url

Override the base upload URL used to determine the path within Cloudinary. Useful for multisite or custom upload configurations.

Custom Adapters

The plugin uses an adapter pattern, so you can add support for other image services:

Switching Adapters

If you have multiple adapters registered, you can switch between them:

Pausing the Plugin

Need to temporarily disable transformations? Maybe for debugging or a specific request:

Development

Setup

Running Tests

Code Quality

Full Test Suite