WordPress (plugins) compatibility check to prevent fatal errors
Tags: webdev, wordpress, security, showdev
Published: 2022-12-12 09:55:24

How to prevent predictable conflicts between incompatible plugins, themes, WordPress core and PHP versions? Disclaimer: this post and the [plugin](https://github.com/openmindculture/wp-incompatibility-status) and [test setup](https://github.com/openmindculture/wp_cli_docker) are no guarantee to prevent a so-called ["WordPress white screen of death" (WSOD)](https://wordpress.org/support/article/common-wordpress-errors/#the-white-screen-of-death) 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](https://codesandbox.io) for ReactJS and [Codepen](https://codepen.io) for general web development. Announced in WordPress meetups in late 2022, there will hopefully be and update soon at the [test-driving WordPress documentation](https://wordpress.org/support/article/test-driving-wordpress/).

## 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.

![Idle Fisher Doodle screenshot of an empty google result page: about 0 results: your search - array and string offset access syntax with curly braces is no longer supported in customers ... - did not match any documents. Suggestions: make sure that all words are spelled correctly. Try different keywords. Try more general keywords. Try fewer keywords](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/539sqesxyfz5g1kp56cu.png)

### 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!

![Screenshot of a google result page: about 12 results: Fatal error: Array and string offset access syntax with curly brances is ... wordpress.org: array and string offset syntax with curly braces is no ... missing: 617, must include: 617, stackoverflow.com: php - Array and string offset access syntax with curly braces is ... since PHP 7.4 curly brances method etc. missing: law 617](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7pr2k7j35g6lh6dhmq49.png)

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 of search results on wordpress.org: learn: Array and string offset access syntax with curly brances is no longer supported: support forums: about 264 results](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5kvm4lf58h1c33vh60ja.png)

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`.

![Screenshot of php.net website: PHP 8 ChangeLog Version 8.1.13, 24 Nov 2022. PHP 8.1 released! PHP 8.1 is a major update of the PHP language ... upgrade to PHP 8.1 now!](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/huyam29vedfxaxm6q116.png)

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](https://dev.to/ingosteinke/check-your-wordpress-plugins-before-upgrading-to-php-8-485n).

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](https://wordpress.org/plugins/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.

![Screenshot of Gutenberg incompatibility warnings in the plugin's status widget](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gw1mm7u23wp9vlpkyc03.png)

### Plugin titles vs. slugs / text domains

Plugins are technically identified by their so-called ["slugs" or "text domains"](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#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](https://github.com/openmindculture/wp_cli_docker), I specified a shared volume in `docker-compose.yml`:

```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](https://wpml.org/), 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.

![Screenshot of WPML website: WordPress 6.1 was released on November 1st and contains critical, breaking issues with WPML. We recently released WPML 4.5.13 and String Translation 3.2.3 to fix these. WordPress 6.1 introduces breaking changes. To avoid breaking changes, you must update to WPML 4.5.13 and String Translation 3.2.3 before updating to WordPress 6.1](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/90d70uhnquropq7dd7sd.png)

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](https://wordpress.org/support/) 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](https://www.phpmyadmin.net) (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.