Hooking into the WordPress Site Health screen
- Updated on: 2023-04-04
- Read original article here
WordPress 5.2 gave us the Site Health screen, a convenient way for users to check on the vitals of their website. It performs some tests and also gives the option to copy all debug data to the clipboard for easy sharing.
However, four years later, very few plugin developers seem to utilize it. This is possibly due to the fact that documentation on it is very limited and hard to find. This may lead you to think that it is hard to work with the Site Health screen, but in fact it is actually very easy to hook into it.
The Tweet I recently wrote about this subject garnered a lot of response, which prompted me to write this more in-depth article.
To add a custom test we have to use the filter hook. There are two types of tests, direct tests and asynchronous tests. Tests that take little time to execute can be executed directly. If a test takes more time to run, its better to make it asynchronous.
The key points to a function (the value should be a function callback). That function should perform the test and return the results. Let’s create a testing function that checks if the PHP extension is loaded and the function is available (…disregarding the fact that one of the built-in tests already checks if mbstring is enabled):
The result should look like this:
Adding an asynchronous test is a bit more involved. With asynchronous tests, WordPress will make a request to an Ajax endpoint to run the test, so it won’t slow down the page.
Asynchronous tests are registered like this:
In this case the does not expect a function callback, but a string with the name of your Ajax callback function. Note that you should use dashes and not underscores.
points to the test function directly and should be a function callback. This is used when the test is ran in the background.
The definition of the test itself is the same as in the Adding a “direct” test section above.
All we have to do is register an Ajax endpoint for it:
Note that WordPress also adds the prefix to the Ajax action name before your test name. This had me scratching my head for a while when my test wouldn’t get triggered.
After registering the Ajax endpoint, your test should show up at the bottom of the tests list:
Adding a custom section to the Info tab is really easy. You can do this by adding a function to the action hook like so:
This should add your custom section to the info tab:
And that’s how you add custom tests and debug info to the WordPress Site Health page!
You can find a fully working example plugin on my GitHub page.
I’m curious to see how you’ll implement this into your plugins! If more developers implemented this we could all point users into the same direction for getting debugging info.
Having said that, we should aim to keep it useful and not clutter it up with commercial messages or useless tests/debug info.
Don’t forget to share this if you found this useful, and follow me on Twitter for more guides like this!
