The ultimate WordPress update guide
If you read this, I assume you know very well, that updating is important for WordPress security and security of those who visit the website. Additionally, you are probably aware how time-consuming and boring the update process is. In this guide I will show you some tricks how to speed up this process.
All tools & tricks we use in a single guide
Managing websites is a challenge that our team has been facing for years. During this time, our web developers have tested lots of tools and learnt many tricks to ease the pain of updating. To help you with this struggle, I gathered all know-how we have acquired over the years of managing websites in this guide.
Start preparations earlier
There are several things you can do in advance to be ready for the zero day.
List custom modifications
From our experience almost every WordPress website, that is not a very simple blog, has some customizations in the code. It is very common for developers to, at least, modify theme to their customers’ needs and it’s not rare to customize plugins or even WordPress Core. Unfortunately, those changes are often hard coded, so they will be overridden by the WordPress update. That’s why, it is beneficial to list all these customizations as you will need to paste them into an updated website.
How to find hard coded custom modifications?
If you use a version control system (such as Git or SVN) you can observe changes by going through your commit history in the files you haven’t created yourself. If don’t like the idea of digging in your past commits, you don’t use a version control system or you manage a website you haven’t created yourself you may have problem with listing all hard coded modifications. Here’s how we do it. Our secret sauce is to use an IDE (Integrated Development Environment), such as NetBeans or phpStorm to create diff showing all hard coded changes in the code.
Creating diff with NetBeans
First of all, download again unmodified version of WordPress you currently use. For example if your websites runs WordPress 4.2.4 and you think of updating it to version 4.4, download Wordpress 4.2.4. Now, compare your current files to the unmodified files, you have just downloaded. The same is correct when it comes to any theme or plugin you use.
NetBeans enables you to diff files even if you are not using versioning:
- Select the two files in the Projects, Files or Favorites view.
- Invoke the context menu and choose Tools | Diff to compare the two files. Note that this submenu appears only if you select two files.
- A diff window is opened highlighting all the differences.
Creating diff using phpStorm
First step is same as above, download again unmodified version of WordPress you currently use. For example if your websites runs WordPress 4.2.4 and you think of updating it to version 4.4, download Wordpress 4.2.4. Now, compare your current files to the unmodified files, you have just downloaded. The same is correct when it comes to any theme or plugin you use.
- Keeping the Ctrl key pressed, click two files in the Project tool window.
- On the context menu of the selection, choose Compare Files, or press Ctrl+D. The Differences Viewer for Files opens, with the differences being color-highlighted.
Finding alterations in WordPress database core tables
Apart from modifications in flies you should also mind checking alterations in WordPress database core tables, because those changes may be overridden as well. In some rare cases, it may even break the update process. Modifications in the WordPress core tables are the main thing you should be looking for.
Creating database structure diff with phpStorm
To compare databases’ structure using phpStorm select two data sources or tables, then select ‘Compare’ and press Ctrl+D. To save, right-click the table and choose output format and then specify desired location.
Transform hard coded changes - if you can
99% hard coded WordPress modifications can be rewritten along with good practices. It’s just the matter of time and resources available. If you can - do it! It will save you time in future updates. More tips on that in paragraph “Add custom modification” below. If you can't, I advice you to - at least - mark custom modifications in the code using such comments:
/* CUSTOM CORE CHANGE - START */
/* CUSTOM CORE CHANGE - STOP */
You don’t use it = you don’t need this
Usually, during web development process you try different plugins and themes. If you didn’t get rid of all downloaded, but unused plugins and themes earlier - now it’s time. Moreover, it will be beneficial to empty WordPress trash and optymize database. In this later case we usually use WP-Optimize or WP-Sweep. All these cleaning will help you with the upcoming updates because it:
- reduces size of backup
- decrease number of plugin updates
No longer in the directory
It’s not a rare, that a plugin that you use isn’t in WordPress Directory anymore. In this case, you won’t get information on the possible updates and compatibility. It’s also probable it won’t be updated. If you have resources, it is worth to change it as soon as possible.
You can check if plugins are in WordPress Directory using a No Longer In the Directory plugin. It shows which plugins are no longer in WordPress Directory and which weren’t updated for over two years.This plugin doesn’t automatically run in the background, so you have to manually run it every few months.
Be cautious, plugins presence in the Directory doesn’t automatically mean they are updated. Nearly half of the WordPress plugins in the Directory haven’t been updated since at least two years.
Browse through beta version. Uncover potential problems
We browse through WordPress beta version often, and I truly recommend you this. If you have time don’t hesitate to compare beta code version to the actual one. It’s always worth doing, because it allows you to find the differences in the code and identify potential problems you may encounter after the update.
Turn off Automatic Background Updates
Automatic Background Updates were introduced in WordPress 3.7. It’s a great tool for very simple websites that are not managed by a professional. If a website depends on third party plugins/themes (which is almost always the case) or has any customizations in the code (even if they are not hard coded), we don’t recommend using this feature. Firstly, any automatic update will override your hard coded customizations or may influence the way other modifications work. For example when WordPress 4.2.3 security fix has been released, it removed all shortcodes that contained HTML code, which caused problems on many websites. Secondly, there will be no backup before the update, so you don’t have a safe point of return. Thirdly, your plugins or themes may not be fully compatible with the updated WordPress. Simply speaking, your website will often crash as a result of the automatic update.
To completely disable all types of automatic updates add the following to your
define( 'AUTOMATIC_UPDATER_DISABLED', true );
or use Disable All WordPress Updates plugin.
Things to do before the update
Be sure you have a current backup of the files and database, to restore the website easily, if something goes wrong while updating. I hope it’s not the case, but if you have never done the backup, this is the time.
Bad things happen to good people. That’s why, it is extremely important to verify the backup you created before the update. It is the only way to know if the website can be restored just in case. There are 2 ways to approach it, that we recommend. Here are the details.
Compare structure and file size
The first thing you can do to ensure you have a good backup is restoring WordPress from your backup on another server or your local computer and compare size of the uncompressed website with the one on the server. Additionally, make sure you can see all the folders and files and you are able to browse them. It’s not a 100% safe method, but at least you will be able to notice some big issues.
The better idea is to compare checksums of all the files. Again you will need to restore the backup somewhere first. Then i recommend creating a script in either PHP or Bash (if you have console access on the hosting). First, you run the script on the deployment server to get the full list of the files with checksums (XML is a great output idea). Then you run it again on the server where you have restored the website. And finally you comprate both XMLs to see if they are identical. This way you know that your backup is rock solid.
Verify database backup
Apart from verifying the files, it is also important to check the database backup. At least consider opening a .sql file in a text editor to see if the tables and data are represented. To do it the proper way I recommend SQL Schema Compare or SQL Data Compare.
Should I use development environment?
If you have resources, it is always worth to update Wordpress on development environment. To migrate website from one location to another easily you can use WordPress Duplicator Plugin or Akeeba Kickstart, especially if you already use Akeeba Backup.
Preparing test scenarios
A white screen of death is noticeable immediately after something went wrong. But what about missing meta tag or widget? You won’t see it missing right away, if you don’t have something to compare it with. Preparing a test scenario will solve this problem for you. Here’s how we do it.
Preparing screenshots for visual comparison
To compare the visible elements of the website you can do a visual comparison. In order to do that, you need to generate screenshots before the update. Here are some tools to help you with preparing screenshots:
If you plan to update on development environment, you can just compare old and updated website displaying them side by side on two screens.
Writing test scenarios with Codeception
2 most popular solutions for websites testing are Codeception and Casper.JS. In this example we will show how to write a simple test scenario in Codeception. Here you can find the information how to set up the testing environment.
Here’s a sample test scenario that checks if I can log to WordPress admin panel.
Once you are ready with your test scenarios run them and make sure that they all pass. You can find information how to run Codeception tests in section “Running test scenarios with Codeception” below.
Having your websites covered with automated tests gives you confidence. But it is never 100%, because you are not able to predict all the possible scenarios not to mention writing test scenarios for all of them.
Although writing test scenarios takes a while, they will be very helpful to check if nothing get broken after the update. You can use them during every future update so it’s investment that pays off in time.
Plugins and themes compatibility
Make sure that your themes and plugins are compatible with the new WordPress version. We know it’s not an easy task though. You can find the information in plugin readme.txt, change log or at wordpress.org, if plugin was downloaded from WordPress Directory. Remember, that just because there is no information they are compatible, it doesn't mean they are not. You can also check theme or plugin developers’ website. Seems like a huge waste of time? My sentiments exactly. To be honest our web developers often used to take the risk (you always have a verified backup, don’t you?) and update the website even if they lacked information on plugin compatibility.
Make sure with Better Plugin Compatibility Control your plugins are updated
Some help in this is offered by a plugin called Better Plugin Compatibility Control. It adds version compatibility information to the plugins page in WordPress admin panel to inform the admin at a glance if a plugin is compatible with the new WordPress version.
Deactivate plugins or not?
This is an uneasy question. Some plugins may conflict with WordPress update process because of incompatibility and cause update failure or a white screen of death. On the other hand, sometimes during plugin deactivation some actions influencing website may be executed. For instance plugin’s settings may be removed or deleting data from database may occur You may either take the risk (you have backup, right?) or check every plugin code before deactivation. Both cases are examples of bad practices in plugin development, but we all see such solutions from time to time.
Apart from the above, make sure you aren’t caching sites during the update. Deactivate cache plugin, as it may interfere with the updating process. The most popular plugins that may be responsible for caching are Super Cache and W3 Total Cache. Very popular chaching plugin was Quick Cache but it was discontinued last year. Here are some alternatives.
The time has come. Update
The moment is now
Finally, you are well prepared, and ready to proceed to updating WordPress. There are two ways to do this:
- one site after another
- all websites at once
Way of conduct in context of plugins’ deactivation
Updating WordPress core is not everything, you have to update plugins too. Regarding this, there are two, significant rules:
- if you have deactivated plugins before - update WordPress core first, then plugins
- if you haven’t deactivated plugins before - update plugins first, then WordPress core
One site after another
Since WordPress 2.7 you can update your site with a single click. You can launch the update by clicking the link in the new version banner or by going to the Dashboard > Updates screen. Once you are on the "Update WordPress" page, click the button "Update Now" to start the process off.
All websites at once
If you manage multiple websites, it can be time-consuming to go to every website admin panel and update WordPress core,e themes and plugins There are several tools which can help you to cope with this challenge, such as: Manage WP, InfiniteWP, WP Remote or MainWP.
After the update
Activating all your plugins you’ve deactivated before the update not always works. In such case, do it one by one and every time check if any errors occurred and what is going on with your website.
Add custom modifications
If there were any custom modifications in the code you need to add them again. If possible, do this along with good practices, and don’t hard code it again. It will help you to save time on future updates. Here are some tips how to do it “the right way”.
Child themes are the best way to go. I recommend it, because using them allows you to customize themes without losing your changes when updating the parent theme. On our blog you can find a guide how to override themes safely.
For smaller changes, you can use Simple Custom CSS plugin, which adds custom CSS styles that override CSS without any hassles.
Depending on modification type, you may use one of the following solutions to implement your hard coded core changes along with WordPress best practices.
- Plugins. That’s a default, if none of the solutions below are suitable, but it’s also the most troublesome option.
- Drop-ins. “WordPress allows to replace some functions with Drop-ins. The list of possibilities isn't big and not well documented. But I like to use Drop-ins to enhance the possibilities of caching, especially APC and Memcache. But also to adjust uploads, permalinks and similar things are a typical scenario for Drop-ins.” That’s an excerpt from Frank post on WP Engineer blog. If you think Drop-in is a solution I recommend you read the entire post.
- Pluggable Functions. That’s another option for overriding functions. Here’s a full list of available functions. However there are rumors that they will be deprecated sooner than later, so I would suggest using filters instead.
- Filters. Filters are great to do almost anything with data fetched from database before it will be sent to the browser. Here’s an official documentation, and here’s a handy guide.
- Actions. Use, if you need to change the order of resources being loaded or fire certain code when some event will occur. Here’s an official documentation.
Although there are no child plugins officially, creating another plugin to extend the existing one is a way to achieve the same result. This approach was suggested by Ian Dunn in his post “The Right Way to Customize a WordPress Plugin”. This way you can still update the plugin that was extended and you don’t lose your modifications.
Everything is ready now, so if you followed the instructions above and have created test scenarios or screenshots, now it’s time to use them.
Running test scenarios with Codeception
Run your test in Codeception with the
$ php codecept.phar run
Here's the output you should see:
Let's get a detailed output:
$ php codecept.phar run acceptance --steps
You should see a step-by-step report on the performed actions.
In /output folder you will also find a screen and HTML code for every test scenario that have failed.
Comparing screenshots with CSS
First of all, create screenshot of the updated website the same way you have done it before.
Then, I recommend using a CSS filter to find the difference between screenshots. This simple trick is very useful and easy
This can be achieved with a single CSS filter:
-webkit-filter: invert(100%) opacity(50%);
Here you can find more information how to do this.
Rollback when updating fails
You updated your website but the site is not working properly? Sometimes, when WordPress upgrading fails, you need to rollback to the previous version, especially if you updated a live website.
Restoring website with Akeeba Backup and Akeeba Kickstart
Download current version of Akeeba Kickstart and upload kickstart.php file and the translation INI files to the server on which you want to restore your website. Upload all parts of the backup archive to this server. Then, go to the Kickstart URL on your target server and click ‘Start’ to begin your website restoring. Detailed information you can find on Akeeba Backup site.
Restoring website with BackUpWordPress Plugin
You need to download the latest backup file either by clicking download on the backups page or via FTP. Unzip the backup files and upload all the files to your server overwriting your site. You can then import the database using a database management tool provided by hosting company (likely phpMyAdmin). Here are some more detailed instructions.
Is it possible to make it easier?
Dreaming of a perfect solution
Tools and tricks mentioned above were very helpful, but we had been dreaming of something that will make a significant difference. We were looking for something, what could further improve time-consuming and laborious web admins’ work. Eventually, we decided to create a solution by ourselves.
Wasting time? Never again
We were fed up with restoring every backup and verifying if no file got corrupted, so we made a tool to do this for us. It wasn’t once or twice, when we haven’t noticed a bug during manual tests after the update and it was our customer to discover it. You can imagine he wasn’t happy. To avoid such unpleasant situations we designed test engine automatically pointing out potential errors to fix. We were in need of one platform to see update status of all websites we were responsible for running different CMS? We made a TODO list that refreshes automatically every day. We have saved countless hours thanks to this solution. Recently, we decided to share it and make it available for everyone. If you want, you can try it here.
Together we can make the Internet a safer place
I really hope, you will find my post useful and helpful while updating your WordPress to the newest version. You know it is great you’re doing this? If you’re not aware you should know and remember: thanks to people like you the Internet is safer place for all of us.
In the end of this post, I would like to thank Perfect Web's developers team. Especially, I thank Aleksander Kuczek, Jan Krzywanek, Piotr Moćko and Tomasz Dziuda for help and all the advices.