WordPress Plugin developer guide

If you're an experienced WordPress developer and are looking to customize and extend the Cloudinary WordPress plugin, you can make use of some additional tools and options to get the best out of your setup.

Setting the connection string as a constant

One way you might want to configure the plugin is to define your Cloudinary connection string as a constant. Setting the constant prevent any users from editing or updating the associated Cloudinary cloud via the WordPress UI. To set your connection string, add the following line to your wp-config.php file, replacing the key, secret and cloudname with your own values:

Actions and filters

The Cloudinary WordPress plugin exposes a number of actions and filters that you can hook into to customize and extend the functionality of the plugin.

See the Cloudinary WordPress Plugin page for a full reference of the available options.

Managing media sync using the WP-CLI

The WP-CLI can be used to perform a number of tasks on your WordPress site using the command line. The Cloudinary plugin extends this capability by adding two additional CLI commands:

• The analyze command analyzes the current state of your media assets, telling you how many assets you have that are "synced", "unsynced" or "unsupported".

• The sync command triggers the sync of any unsynced assets to Cloudinary. You can use this as an alternative method for syncing your assets in bulk.

Syncing external assets

When using the Cloudinary WordPress plugin, by default, you can only sync internal media assets, i.e, the GUID of the assets has to belong to the domain of your WordPress website. External assets are marked as "unsupported".

How to know which assets are internal or external?

Usually, when the sync process kicks off, the plugin tries to sync internal assets to Cloudinary while for external media assets, you should see a blue icon with a Not syncable. This is an external media. message when you hover the icon as you can see below:

In which cases media assets can be external?

It mostly happens when migrating your website to another domain or when migrating your website to a staging/dev environment while keeping the original database.

How to sync those external media assets?

There are 2 ways to fix it depending on the guid of those assets being accessible or not, so you need to find out first what the guid of those assets look like by following these instructions:

If you aren't a developer or you don't have access to the database

1. Enable the Cloudinary System Report as explained in How to generate a system report on the WordPress plugin.

2. In your Media Library, click on the asset to edit it:

1. Scroll down to the Cloudinary Metadata Viewer and locate the guid of the asset by scrolling the viewer to its last line.

If you are a developer or you have access to the database

Connect to your database and launch the following query:

Syncing assets based on guid accessibility

When you have the guid URL, you can paste it into your browser and see if it's accessible.

If the guid URL is accessible:

Go to General Settings under the Cloudinary plugin and scroll down to the External Asset Sync Settings section and add the domain of the guid URL to the whitelist and save your changes:

The assets should now start syncing to Cloudinary.

If the guid URL isn't accessible:

You need to find out where this asset is stored. Usually, it happens if you have migrated your assets to a new domain and deleted the previous one while the guid URLs use the previous domain so you need to rewrite the URLs of the guid values. For example, https://dev-loic-cloudinary.pantheonsite.io/wp-content/uploads/2022/02/img.png isn't accessible but https://dev-loic-cloudinary-play.pantheonsite.io/wp-content/uploads/2022/02/img.png is.

If you aren't a developer or you don't have access to the database

1. Install the Better Search Replace plugin and go to Tools > Better Search Replace.

2. In the Search for field, add the non-accessible domain.

3. In the Replace with field, add the accessible domain.

4. Select the wp_posts table and check the Replace GUIDs box.

5. Untick the Run as dry run? box to replace the URLs. You can leave it checked as a first attempt to check the results before altering the database.

If you are a developer or you have access to the database

Connect to your database and launch the following query:

When the query either from the database or via the Better Search Replace plugin has completed, the assets should now start syncing to Cloudinary.