How to successfully upgrade to Gravity PDF 5.0

Gravity PDF 5.0 is a major update that sees the minimum version requirements for PHP, WordPress and Gravity Forms increased. We have updated the PDF library we use (mPDF) from v6 to v7, we've removed a legacy directory used in v3 and we no longer bundle the PDF fonts directly in the plugin.

Gravity PDF v4 End of Life

Gravity PDF v4 reached its End of Life on 2019-10-04 and is no longer supported in any way.

Below you'll find the main problems that can occur during an upgrade to Gravity PDF v5 and ways you can go about overcoming them.

New Software Requirements

Both the server and software requirements have changed. Gravity PDF 5.0 requires the following:

• PHP 5.6+ (PHP 7.1+ is recommended)
• WordPress 4.8+
• Gravity Forms 2.3.1+

Verify you meet these requirements by viewing the System Status page, which can be accessed from the WP Admin menu Forms -> System Status. If you aren't running a compatible version of PHP, contact your host and ask them how you can upgrade. If you're running an older version of WordPress or Gravity Forms, use WordPress's one-click update feature before updating Gravity PDF.

Premium Templates

If you've purchased a premium PDF template from our online store, make sure you've installed the latest version of the template. All premium templates had an update so they'd be fully compatible with v5. To check the latest version of a template, navigate to the product on our website and see the "Current Version" value in the sidebar. To check the version you have installed on your website, navigate to the PDF Template Manager and drill down to the Template Details. You'll see the current version you've installed. Active license holders can download the latest version of a template by logging into your GravityPDF.com account. If your license has lapsed you will need to purchase a new one. Once you've downloaded the latest template zip install it via the PDF Template Manager.

mPDF v7

The library we use to generate PDF documents is called mPDF and it also got a major version bump. Our team has worked closely with the mPDF developers over the past 12 months to ensure there's little (if any) differences to PDFs generated using Gravity PDF v4 and v5 when using the standard templating functionality. However, any developers who are accessing the mPDF library directly – either in a custom template or using a filter – may need to modify their code. Notable changes in mPDF v7 include:

1. Moved class mPDF to namespace Mpdf\Mpdf. Note: we've polyfilled the mPDF object for backwards compatibly reasons.
2. The configuration files have been removed, now configured via the _construct
3. Progressbar support is removed
4. Bundled JpGraph support removed (can still be utilised independently)
5. An exception is thrown when mbstring.func_overload is set
6. Removed a number of global constants
7. Moved a number of global functions to classes or namespaced functions
8. Removed deprecated methods.

You can see the full changelog here.

Removed /resources/ Directory

The /resources/ directory, which contained assets (images and CSS) used in v3 example template files, has been removed. If your custom template(s) relied on files in this directory then you'll need to move them to the PDF Working Directory and update your template(s).

Gravity PDF Customers

If you're a Gravity PDF customer and are having trouble with your Bespoke template, get in touch with our team for a quote to upgrade your templates.

Upgrading to Gravity PDF v5

Now that you are aware of the potential issues that can occur during an upgrade, let's go through the steps needed to complete v4 to v5 migration.

1. Before you begin, you should take a full backup of your website before attempting the update. Better yet, test the update in a staging environment so you can check for any problems without affecting your live website.

2. To verify there have been no visual changes in your PDF, it's helpful to download a number of PDFs before beginning the update. This will allow you to compare them to v5's PDFs once successful. Just make sure you write down which entries the PDFs come from.

3. The actual update process is as simple as using WordPress's one-click update feature.

4. Once the update is completed, generate new versions of your sample PDFs (see step 2) and verify there are no changes.

5. Submit test entries to all forms that have PDFs configured and verify the functionality.

Optional Tasks

The following are optional tasks you can take after completing the migration process.

Install Core Fonts

In Gravity PDF v5 all fonts have been removed from the core plugin files and now need to be installed when the plugin is first activated. Note: you won't need to reinstall the fonts after every upgrade, only the initial installation.

If you upgraded from v4.3+, the software automatically copied the fonts to the PDF Working Directory's font subfolder. However, mPDF v7 includes additional fonts which support even more languages out of the box. To take advantage of this, it is recommended to run the Core Font Installer. This feature is available from the Tools tab of the Global PDF settings. If you upgraded from v4.2 or below you'll be prompted to run the Core Font Installer automatically. Click the Install Core Fonts button to start the process.

Enable Background Processing

New to Gravity PDF v5 is the option to turn on PDF Background Processing to reduce your form submission time. This option can be enabled from the Global PDF Settings page. Before enabling this feature, you should first verify that your website can support it. To do this look for a green tick next to “Background Tasks” on the Gravity Forms System Status page. Gravity Forms has a great guide on why Background tasks might not be functional for your website.

Rollback to v4

If something broke during the v5 update all is not lost and you can rollback to v4 without much difficulty. First, if you are experiencing the "white screen of death" please follow these instructions to help resolve the problem. If you still have full control over your website, but there's some compatibility issues with v5, we recommend installing the WP Rollback plugin. With little effort on your behalf you can downgrade from v5 to v4. Once installed, just click the Rollback link on the Gravity PDF row on the plugin's page, then select the latest stable release of v4 and rollback.

Help and Support

If you run into trouble during your migration, get in touch with our friendly support team, and we will be happy to assist you.