WordPress (plugins) compatibility check to prevent fatal errors

How to prevent predictable conflicts between incompatible plugins, themes, WordPress core and PHP versions? Disclaimer: this post and the plugin and test setup are no guarantee to prevent a so-called "WordPress white screen of death" (WSOD) in the future.

A WordPress Playground

Note for everyone without npm and Docker (propbably not you but maybe one of your customers): WordPress Playground might become an alternative without local installation, much like Codesandbox for ReactJS and Codepen for general web development. Announced in WordPress meetups in late 2022, there will hopefully be and update soon at the test-driving WordPress documentation.

How to update WordPress and Plugins without "killing" your Website

Who is in charge of updating (your own or your customers') WordPress installations and plugins? Will the update automatically? Will you receive an advance note before the web hoster will apply a major PHP upgrade?

Ever saw error messages like these?

Array and string offset access syntax with curly braces is no longer supported in /customers/617/example.com/htdocs/wp-content/plugins/cookie-law-info/includes/class-cookie-law-info.php on line 617

Meet the Idle Fisher

Then you probably also know the idle fisher, maybe the most annoying cute doodle characters because it only ever comes up if there is not a single result for your search and Google doesn't even find any paid adverts to match your query either.

Do we have to give up our mission?

Try to rephrase and use more generic terms or possible variations of error messages, especially remove local installation paths and don't paste localized warnings that might appear in Portoghese, German or Ukrainian on your screen while others might have used the Englisch version when discussing an error on GitHub, WordPress.org or StackOverflow.

Fatal error: Array and string offset access syntax
with curly braces is no longer supported in 
/customers/617/example.com/htdocs/wp-content/plugins/cookie-law-info/includes/class-cookie-law-info.php
on line 617

would thus become

Fatal error: Array and string offset access syntax
with curly braces is no longer supported in 
cookie-law-info/includes/class-cookie-law-info.php 
on line 617 WordPress

and

Fatal error: Unparenthesized `a ? b : c ? d : e` is not supported.
Use either `(a ? b : c) ? d : e` or `a ? b : (c ? d : e)`
in /customers/617/example.com/htdocs/wp-content/themes/Avada/includes/avada-functions.php
on line 438

could become

Avada Unparenthesized a b c d e is not supported.
Use either in themes avada avada-functions.php
on line 438

which actually yields helpful discussions now!

Likewise for the same type of error in the multilingual system:

WPML Trying to access array offset on value of
type null in sitepress-multilingual-cms installer
includes class-installer-theme.php on line 565
Fatal error: Unparenthesized plugins
sitepress-multilingual-cms twig lib
Node.php on line 42

Pragmatically, we can now proceed and check only the top search results (which might be the most popular, most relevant, or most recent) and compare error / setup details to quickly sort out if they are relevant to my current situation. Hopefully assuming that, given the number of web developers, content creators, and active WordPress installations, I will probably never be the first one to run into any fatal error, unless it's caused by my own custom code or a very unlikely edge case.

• PHP version
• WordPress (core) version
• version of to the plugin that emitted the specific PHP error message

Screenshot above: we can search for the error message in wordpress.org forums, but at the time of writing, it was hard to tell the plugin context of the topics, unless we include the plugin name or title in the query, like searching for

"CookieYes Array and string offset access syntax with curly braces is no longer supported"

to find out if the cookie-law (name / text domain) / "CookieYes" (title) plugin has already been updated for PHP 8.

If still in doubt, we could also check the official changelogs for a possible bug fix. So if there are bug reports for some plugin being incompatible with PHP 8.0.24 in plugin versions 1.2.3 and 1.2.4, a notice about a compatibility fix in 1.3.0 might (or might not) be enough to reassure us that we feel safe using plugin 1.3.3 with PHP 8.0.26.

Heads up! Although the above screenshot seems to tell us too "upgrade to PHP 8.1 now!" let's not blindly follow suit. See my earlier post about possibly upgrading to PHP 8 too soon.

We could, and we should also check the plugins' technical details, especially "tested up to":

Tested up to

where it should state the minimum requirements and latest tested versions, like

WordPress Version: 5.0.0 or higher
Tested up to: 6.1.1
PHP Version: 5.6 or higher

But as we can see, there is usually no "tested up to PHP version" stated explicitly.

Wouldn't it be helpful to try out actual plugins with specific PHP versions without messing with our customers' production server settings?

Even if there is no staging environment, we can install WordPress locally, matching PHP and plugin versions, and see if it crashes or not.

Thanks to Docker, and the helpful open-source community, it has become easy to run various server configurations on a local computer.

A Simple WordPress Setup in a local Docker container

I have provided a setup built on top of the existing WordPress Docker images, automating plugin installation and version check as good as possible.

Clone

https://github.com/openmindculture/wp_cli_docker

and run npm start to set up a local host.

You can choose which WordPress core, PHP, and server version to use (based on the available images from Docker hub) and which plugins and themes to install.

https://wordpress.org/plugins/incompatibility-status/

The local host also includes my WordPress plugin incompatibility-status, which is a work in progress to query and display WordPress core, PHP, and some specific plugin and theme versions, and check for some known problems, currently focused on block editor ("Gutenberg"), block themes, and (full) site editing (FSE) capabilities.

Plugin titles vs. slugs / text domains

Plugins are technically identified by their so-called "slugs" or "text domains" which is usually the same as the directory name. As popular plugins evolve over time and companies get acquired and renamed, so do official trade marks and titles, so it might not be easy to find out the appropriate slug.

But if you have access to the file system, you can inspect a plugin directory and look into the top-level files like readme.txt, PLUGIN_NAME.php, or style.css.

How to find out the technical names of plugins without file system access? On the installed plugins page, click on the link "view details" if there is, otherwise try one of the other links to open the official WordPress plugin page. Some plugins like Advanced Custom Fields (acf) don't directly provide any of those. Without access to the file system, maybe we have to guess and google?

In a local Docker setup, you can enter the container's file system using docker exec or mount the plugin directory to your local file system to use IDE annotations, debugging, and static code analysis.

In my wp_cli_docker, I specified a shared volume in docker-compose.yml:

    volumes:
      - wp_data:/var/www/html
      # increase allowed upload file size so that we can import shop data:
      - ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
      # uncomment/modify the following line to plugin code available for local search/debugging:
      # - ./plugins/:/var/www/html/wp-content/plugins

If we still need to enter our container, we can do so, depending on the actual docker image name or id:

docker exec -it wordpress_setup_test_wordpress_1 bash

Replace wp_cli_docker_wordpress_1 with the appropriate name found in docker ps, if necessary.

Inside the docker container, we will find WordPress in /var/www/html and system settings and error logs in their appropriate places as well.

Adding non-free themes and plugins

Some plugins can't be installed or updated automatically or locally due to licensing reasons, like WPML, which also does not automatically get upgraded to the latest version. Well, it should have auto-updated itself, but that won't happen when the incompatibility error prevents the update. A chicken and egg problem.

After subscribing to WPML (the cheapest plan, which I hope will use the same plugin code), first thing I saw in their customer backend was the announcement: "To avoid breaking your site, you must update to WPML 4.5.13 and String Translation 3.2.3 before updating to WordPress 6.1." This makes sense, as my customer was using an older WPML version on their WordPress webssite, which got automatically upgraded to WordPress 6.1 and PHP 8.0 by their web hosting provider.

WordPress 6.1 introduces breaking changes
To avoid breaking your site, you must update to WPML 4.5.13 and String Translation 3.2.3 before updating to WordPress 6.1.

But even without purchasing licenses for any software that our customers might be using, we can still validate the open source parts and use publicly available information, which often reveals problems with the paid plugins, too.

And if we have access to our customer's WordPress file system, we can try to download the plugins (as subdirectories of wp-content/plugins and ask for a license key if necessary.

• We can google error messages and check WordPress.org support forums and GitHub issues related to open-source plugins for known problems.

• We can do a quick check to see which versions we got, even without file system access. We can even install phpmyadmin (temporarily) as a wp plugin.

Check, update, verify, clean up

After checking, researching, and testing, we could finally make use of our knowledge to update or repair our customer's WordPress installation. First,

• make a backup,
• ensure you got access, permissions,
• ensure someone will receive the recovery emails that are sent when WordPress crashes with a "white screen of death",
• ensure someone can grant access via two-factor authentication (2FA) if needed for specific tasks like accessing the server's file system.

When you feel ready to take action,

• communicate before starting to do anything.

When you proceed with the updates, document what you do. If you are lazy, you can take screenshots and discard the irrelevant ones after you're done.

Finally, clean up everything:

• remove unused plugins,
• log out,
• inform your customer to change passwords and/or remove temporary accounts and permissions, and
• delete personal data, obsolete credentials, and unlicensed source code from your computer.