How to upgrade to WooCommerce 3.0+ with deprecated/out-of-date Plugins

WooCommerce 3.0 has landed and you’re in one of two camps, either you’ve updated (living dangerous!) or you’re waiting until a good time to upgrade which will never come. Here’s how to get from WooCommerce 2.6.14 to 3.0+ without breaking much of sweat by learning from my mistakes.

Updating from WooCommerce 2.6.14 to WooCommerce 3.0+ is just so easy, open up Dashboard > Updates from the WordPress Administration and hit Update, done! … and that’s where some store owners (me included) go from having a stable, operating WooCommerce storefront to a downed WordPress site with no visibility and lost earnings.

If you haven’t updated to WooCommerce 3.0+ my suggestion is don’t, at least not until you know the following details:

that the Theme you are using as well as other Plugins for WooCommerce you have installed and activated within your WordPress site have tested and released compatibility updates for WC 3.0+
you’ve done a full backup of site files and database via cPanel or your preferred hosting software
but most importantly you’re ready – and able – to de-activate Plugins and/or remove PHP snippets in your Theme’s functions.php causing upgrade problems
if you’re a forward thinker you’ve set up a staging site and tested the above (nice but not necessary)

If you’re unsure of #1, #2 or #3 then hold off updating until you are. #3 is critical, #1 and #2 are going to save you time as Plugins tested for WooCommerce 3.0 are less likely to break and having a backup is pretty handy, #4 is nice to have.

Note: I’m not going to cover setting up a WordPress staging site, we’re here to fix downed live WooCommerce stores, not execute well-planned upgrades.

What will break

The basic rule here is if the Plugin for WooCommerce (or Theme) has anything to do with Checkout/Orders/Tax Rates then it will likely break without a WooCommerce 3.0 compatibility release, this is due to fundamental changes to WooCommerce 3.0 with little deprecation support (meaning support for older versions of WooCommerce).

If you run the WooCommerce 3.0 update before installing the above compatibility release by Plugins for WooCommerce developers then there’s a good chance you’ve already shot yourself in the foot and after WooCommerce has updated you will be greeted with either:

a white screen with a PHP fatal error scrawled across the screen,
a totally blank white screen (that’s where PHP error display is turned off),
a 404 Page Not Found (that’s a friendly fatal error in disguise),
or if you’re really lucky a 500 Internal Server Error (the black coffee of fatal PHP errors)

Note: Once you’ve updated to WooCommerce 3.0 drop the idea of downgrading to 2.6.14, yes you can drop the old 2.6.14 Plugin files ontop of WooCommerce and it will probably load but your WordPress database will already have been altered by WooCommerce 3.0 and 2.6 changes will be toast, ontop of that data conflicts will only become more obvious as you use your now downgraded WooCommerce store. If you have to downgrade WooCommerce restore a backup and merge the database changes (e.g. new Orders, new Users, etc.) to minimise lost data.

How to identify what’s crashing your WordPress site/WooCommerce store

If you’ve already upgraded to WooCommerce 3.0 and are now staring at a white screen with a PHP fatal error, a blank white screen, a 404 Page Not Found or a 500 Internal Server Error then it’s very likely a Plugin for WooCommerce is responsible. If your WordPress Theme is optimised for WooCommerce or adds functionality to WooCommerce then it too could be at fault but let’s focus on Plugins for WooCommerce here.

If you can see the PHP fatal error in-front of you then you’re most of the way home, identifying the issue causing your WordPress site downtime is paramount, if you’re in this group jump ahead to the section How to manually de-activate a Plugin for WooCommerce without access to the WordPress Administration, if you’re staring at a blank screen or 500 Internal Server Error then read on.

How to identify what Plugin for WooCommerce is crashing your WordPress/WooCommerce store

Since we don’t yet know what’s crashing your WordPress site let’s turn on the WordPress debugging mode (aka WP_DEBUG), debugging in WordPress can only be turned on by editing your WordPress site’s wp-config.php file, you can do this using a FTP manager like FileZilla to connect to your hosting server or if you’re a cPanel user opening the File Manager.

Here’s the change we need to make to the wp-config.php file to turn on PHP error logging:

// Enable WP_DEBUG mode
define( 'WP_DEBUG', true );

// Enable Debug logging to the /wp-content/debug.log file
define( 'WP_DEBUG_LOG', true );

// Disable display of errors and warnings 
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Use dev versions of core JS and CSS files (only needed if you are modifying these core files)
define( 'SCRIPT_DEBUG', true );

Once you’ve made the above file change and saved it to your hosting server then refresh WordPress site within your preferred browser by clicking the Refresh button or hitting F5 on the keyboard, you’ll see the blank white screen, a 404 Page Not Found or a 500 Internal Server Error just as before only this time we’re saving the PHP fatal error to a file we can now download.

Download the WordPress error log file using your existing FileZilla or File Manager for cPanel FTP session:

Open up the /wp-content/… directory
Download the debug.log file to a preferred directory on your computer; the Desktop, your Downloads directory or a dedicated Websites directory
Open debug.log with your preferred plain-text file editor (e.g. Notepad, UltraEdit, etc.)
Scroll to the bottom of the debug.log file; it can get big really fast… 100+ MB big under the correct circumstances
A fatal PHP error will be prefixed by the current date and time in square brackets followed by “PHP Fatal error: …”, here’s an example from an outdated Plugin release that is not compatible with WooCommerce 3.0:”[10-Apr-2017 07:00:38 UTC] PHP Fatal error: Call to a member function is_skeleton() on boolean in /public_html/wp-content/plugins/woocommerce-bookings/includes/admin/class-wc-bookings-details-meta-box.php on line 57″
Looking at the filepath in the example above we can see WooCommerce Bookings (woocommerce-bookings) within the Plugins directory is the Plugin causing the fatal PHP error. That’s an easy one, guessing the Plugin title for “dgrundel-woo-product-importer” is a little harder, in that case you need to open the Plugin’s readme.txt or README.md as it has no readme.txt file
Hopefully you’ve identified what Plugin for WooCommerce is causing your WordPress site downtime, let’s de-activate it, jump over to the next section to do this.

Note: There may be more than one Plugin for WooCommerce causing fatal PHP errors. What happens behind the scenes is the PHP process stops rendering the WordPress page as soon as it encounters the first PHP error so once you’ve de-activated one Plugin don’t be surprised if you see a different fatal PHP error caused by another Plugin for WordPress. Rinse and repeat this step and the next until your WordPress site is back up and running.

How to manually de-activate a Plugin for WooCommerce without access to the WordPress Administration

Normally you could just open the Plugins screen from the WordPress Administration and de-activate the Plugin responsible but with a fatal PHP error you’re going to need to get creative as WordPress is essentially offline, that means using a FTP manager like FileZilla to connect to your hosting server or if you’re a cPanel user opening the File Manager.

If you’re using FileZilla follow these first steps:

Connect to your hosting server using the FTP logins provided by to you by your hosting provider
The Host is typically your website domain, if your website is http://www.mywoocommercestore.com then enter mywoocommercestore.com in the Host field
The Username and Password is typically the same as your cPanel login provided to you by your hosting provider
Click Quickconnect to connect to your hosting server

For both FileZilla and File Manager for cPanel users:

For FileZilla users the right panel will be populated with a list of directories and files whereas File Manager users will see a screen with directories and files
Expand the base WordPress directory, this is usually called the httpdocs, public_html or www directory; you’ll know you’re here when you see the wp-config.php file in the list of files
Browse to the /wp-content/plugins/… directory
Rename each Plugin directory that has woocommerce, woo or wc in the directory name to be prefixed by a “_” (underscore character) *1 so “woocommerce-exporter” would become “_woocommerce-exporter”
Repeat this renaming action for all Plugins for WooCommerce
Refresh your WordPress site within your preferred browser by clicking the Refresh button or hitting F5 on the keyboard

Your WordPress site should be operational again now, yay! Before you run off into the sunset let’s do a quick clean up and turn off WP_DEBUG. If you’re staring at a new fatal PHP error then jump back to the above section, How to identify what Plugin for WooCommerce is crashing your WordPress/WooCommerce store and rinse and repeat.

*1 – You can rename a directory in FileZilla by right clicking the directory and selecting rename, the same goes for File Manager within cPanel.

My WooCommerce store is back online

Let’s turn off debugging mode in WordPress, this is as simple as commenting out or deleting the PHP snippet we added to the wp-config.php file mentioned in the above section How to identify what Plugin for WooCommerce is crashing your WordPress/WooCommerce store. That’s it, you’re good to go! 🙂