Gravity Forms Cloudinary Premium Add-on Setup Guide

The Gravity Forms Cloudinary Premium Add-on sends the files and images that visitors upload through Gravity Forms to your own Cloudinary account. Each file is sent with a signed upload, can be transformed on the way in or in the link that is stored, and the Cloudinary CDN link is saved in the entry, in the notes, in the notifications and in a merge tag. Your Cloudinary account is yours: the add-on has no account of its own, no middle server and no usage fee.

This guide explains the setup, every option, what happens when something fails, and what the add-on does and does not do.

What you need

• WordPress 6.5 or newer and PHP 7.4 or newer.
• Gravity Forms 2.9 or newer. The add-on is tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.
• A Cloudinary account (the free plan works) and its API key and API secret.
• An active license key for this add-on.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else.

Install and connect

1. Install and activate the add-on like any plugin, after Gravity Forms.
2. Open Forms → Settings → Cloudinary and enter your license key.
3. In the section Cloudinary account enter the cloud name, the API key and the API secret. You find all three on the Cloudinary dashboard under API Keys.
4. Press Save, then Test connection. The test asks Cloudinary for its status with your key; nothing is uploaded.

How the API secret is kept

The API secret is stored encrypted in the WordPress database, with a key that is derived from your site’s secret keys in wp-config.php. It is never shown again after you save it: the field stays empty, a line under it tells you that a secret is saved, and saving with the field empty keeps the saved secret. A tick box removes it. If you change the secret keys of the site, the secret can no longer be read and you type it again.

If you prefer to keep the credentials out of the database altogether, define the constants GFCLOUDINARY_CLOUD_NAME, GFCLOUDINARY_API_KEY and GFCLOUDINARY_API_SECRET in wp-config.php. They win over the saved values.

Largest file to send

The setting Largest file to send (MB) is 20 by default and can be raised to 100, the limit of a single Cloudinary upload request. A file that is bigger stays on your server and the entry gets a note that says so. Files over 100 MB would need Cloudinary chunked uploads, which this version does not use.

Create a feed

The add-on works with Gravity Forms feeds, so every form can have one or several Cloudinary feeds. Open the form, go to Settings → Cloudinary and add a feed. A form without a File Upload field cannot have one, and the screen says so.

Which files

Tick the File Upload fields to send. Single and multiple file fields both work. A feed can have a condition, as every Gravity Forms feed can: for example send the files only when a drop-down says Public.

Where they go in Cloudinary

• Folder in Cloudinary: a path with tokens {form_id}, {form_slug}, {field_id}, {entry_id}, {Y}, {m} and {d}. The default is gravity-forms/{form_slug}/{Y}/{m}. Only letters, digits, space, dot, dash and underscore are kept, so a token can never make a path that escapes the folder. Accounts that use fixed folders put the folder in the public ID; accounts with dynamic folders use it as the asset folder and as the start of the public ID.
• Kind of file: detect automatically (the default; images, video and audio, PDF and every other file), or force image, video or raw.
• File names in Cloudinary: the original name plus a short random ending (the default, so two visitors can never overwrite each other), the original name only (an existing file with that name is kept, never replaced), or a random name. The add-on always asks Cloudinary not to overwrite.
• Tags: up to ten, comma separated. Allowed formats: for example jpg,png,pdf. Cloudinary refuses other formats and they stay on your server.

Transformations

Cloudinary can resize, crop, convert and compress an image with a transformation written in its URL syntax. The feed offers two places for one, and each has four ready choices (none, optimize, resize to 1600 pixels, a square thumbnail of 400 pixels) and a custom box.

• In the stored CDN URL (default: optimize, which is f_auto,q_auto): the transformation is added to the link that is saved in the entry. The original stays in Cloudinary unchanged and you can build other sizes later. This is the safe choice. It applies to images and video; other files get the plain link.
• On upload (permanent): the transformation is applied before Cloudinary stores the file, so the stored original is the changed version. Use it to cap the size of huge phone photos. It is off by default.

A custom transformation is checked before it is used: letters, digits and the characters comma, underscore, dot, colon, dash and slash only, so a chain such as c_fill,w_800,h_600,g_auto/q_auto is fine and anything else is dropped.

The entry and your server

• Store the CDN URL in the entry (default on): the value of the file field becomes the Cloudinary link, in the same form as before (a single link or a list). The entries list, the entry screen, exports, notifications and every other add-on then show the Cloudinary link. Notifications are sent after the upload, so they carry it too.
• With it off, the entry keeps the link to your server, and the Cloudinary link is saved next to it. You can still use it in a notification with the merge tags below.
• Delete the local copy (default off, only available when the CDN URL is stored): the file is removed from your server after Cloudinary confirmed the upload. Only files that were uploaded successfully are removed.

What a visitor and you will see

The visitor fills in the form and sends it as always. The upload happens while the form is processed, one signed request per file, before the notifications are sent, so a large file adds a little time to the submission. If Cloudinary is slow or down, the visitor still gets the confirmation: the file stays on your server and the entry gets a note.

On the entry screen a box named Cloudinary lists every file with its CDN link and size, and a note says Cloudinary: 1 file sent. or lists the files that were not sent and why.

Send files again

The Send files again button on the entry screen runs the active feeds of the form once more for that entry. Files that were already sent are skipped, so pressing it twice never uploads a file twice. Use it after you fixed a wrong key or after a Cloudinary outage. It needs the permission to edit entries.

Merge tags and developer functions

• {cloudinary_url}: the first Cloudinary link of the entry. {cloudinary_urls}: all links, separated by a comma and a space.
• {cloudinary_url_3} and {cloudinary_urls_3}: the same for the field with ID 3.
• gfcloudinary_get_assets( $entry_id ) returns what was sent: per field a list with the source link, public ID, secure URL, link with transformation, size, format, kind, feed and time. gfcloudinary_get_urls( $entry_id, $field_id ) returns the links.
• The filter gfcloudinary_upload_params changes the signed parameters of one upload before they are signed (for example to add context or a moderation setting of your account).

How the upload is signed

The add-on uses the Cloudinary Upload API, REST version v1_1, and the signed upload method. For every file it builds the list of parameters (timestamp, folder, name flags, tags, transformation, allowed formats), sorts them by name, joins them as name=value pairs, appends your API secret, and sends the SHA-1 hex digest as the signature, together with your API key and the file in a multipart request to https://api.cloudinary.com/v1_1/your-cloud-name/auto/upload. The file, the API key, the cloud name and the resource type are not part of the signed text. A signed upload needs no upload preset, and the request is only accepted by Cloudinary for one hour after its timestamp. Certificate verification is always on.

Privacy and security

• Files go from your server to your Cloudinary account over HTTPS. Nothing is sent to GravityExtra or to anyone else. Mention Cloudinary in your privacy policy as a processor of uploaded files.
• Only files inside the Gravity Forms upload folder are ever sent; the add-on resolves the real path and refuses anything else, including links with dot-dot parts.
• The API secret is encrypted at rest, never printed, never written into notes or logs, and the error texts that Cloudinary sends back are shown as plain text.
• Every admin action (Test connection, Send files again) checks a nonce and a capability.

Troubleshooting

• Nothing is sent: check the license, that the connection settings are saved, that the feed is active and its condition is met, and that the form has a File Upload field ticked in the feed.
• HTTP 401 Invalid Signature: the API secret is wrong, or the server clock is off by more than an hour. Save the secret again and use Test connection.
• HTTP 400 and a message: Cloudinary refused the file, for example because the format is not in your allowed formats or your plan does not accept it. The file stays on your server.
• bigger than the limit: raise the largest file setting, up to 100 MB.
• A link without a transformation: raw files (documents, text files) are delivered as they are; only images and video accept a transformation.

Questions

Do I need an upload preset?

No. The add-on uses signed uploads with your API key and secret. You can still use an upload preset of your account through the filter that changes the parameters.

Does it work with several files in one field?

Yes. Every file is its own signed upload and a list value is rewritten as a list of Cloudinary links.

What happens to files that were uploaded before I installed the add-on?

Nothing automatically. Open an old entry and press Send files again to send its files.

Will my visitors wait for the upload?

The upload runs while the form is processed, so a very large file makes the submission a little slower. Keep the largest file setting at a value that suits your plan and your hosting.

Can I keep the file on my server and in Cloudinary?

Yes. That is the default: the local copy is only removed if you switch Delete the local copy on.

Which Gravity Forms versions does it support?

Gravity Forms 2.9 and newer. It is tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.