Improve wording for PHP update warning in Site Health

[danieltj]

In the Site Health section of WordPress there is a warning about PHP being out of date needing to be updated to the latest version. This wording needs improvement for a number of reasons.

1. It uses the word 'we' when no other checks use such language, this one thing is specifically personal and not uniform across other checks made.

2. It doesn't include the version of PHP you are currently using. This can only be viewed under the 'Info' tab, this should be included in the check rather than forcing you to find out what it is.

3. Most importantly, it doesn't include the PHP version you should be using. The development environment I'm currently using which I saw this on is using PHP 7.2.x. I thought it was the latest (and I'm not getting a PHP warning on the dashboard homepage). So it's rather confusing to be told it's out of date but not what version I really need.

Changing the wording from...

We recommend that you update PHP

to...

Your PHP version is out of date

This is inline with other checks such as:

• Your WordPress version is up to date (5.2.2)
• Your site can perform loopback requests
• Your site is not set to output debug information

The paragraph of text further explaining the issue should also include the current PHP version (like it does in the WordPress check I've listed above) and the PHP version you need to update to.

[danieltj]

The PHP check made in Site Health

[swissspidy]

Great to see you here again, Daniel!

These sound like some good improvements to me.

[chetan200891]

Created initial patch.

[afragen]

As long as we’re considering changing the language, can we somehow reference that the PHP version is lower than the current recommended version of PHP.

The reason is that currently the warning shows for supported versions like 7.2

[garrett-eclipse]

It would be nice as well if this verbiage showed you what your current version is and what the recommended version is.

[SergeyBiryukov]

Replying to danieltj:

It uses the word 'we' when no other checks use such language, this one thing is specifically personal and not uniform across other checks made.

Related: #46057

[danieltj]

Replying to swissspidy:

Great to see you here again, Daniel!

These sound like some good improvements to me.

Thanks Pascal 🤓

@afragen & @garrett-eclipse

I definitely think that it should include the current PHP version and the version you should update to, yes.

[garrett-eclipse]

Thanks @danieltj another place I've come across that could use PHP version information is when a plugin update is blocked due to minimum PHP not met. I didn't think it directly related here though so opened #47651

[afragen]

It should be easy enough to add text with phpversion(). We would simply need go some sort of blessing and a consensu about what the string would be.

[danieltj]

I've looked at the wording for this specific test and it seems the title for it changes depending on the version, but the description of the test stays the same.

I'll attach some screenshots of the different states that I could find.

[danieltj]

Running php version 7.3.x

[danieltj]

Running php version 7.2.x

[danieltj]

Running php version 7.1.x

[danieltj]

Running php version 5.6.x

[danieltj]

As you can see, the only instance where it states the current version is when you're running the latest one, that's not very helpful really. I'll see if I can do a patch with some proposed wording.

It's more about having a helpful title for the test as the description is largely fine.

[danieltj]

Proposed patch for PHP test.

[danieltj]

Patch applied using PHP 7.3.x

[danieltj]

Patch applied using PHP 7.2.x

[danieltj]

Patch applied using PHP 5.6.x

[danieltj]

I took it upon myself to merge the is_supported and is_secure recommended checks together because to me they didn't seem to serve much of a purpose as 7.2.x and 7.1.x are both out of date PHP version but also both supported anyway so it made little sense to have a slightly different wording for something that is basically the same.

Saves translators doing an additional string. Sorry for so many replies at once!

[garrett-eclipse]

Updated patch to introduce translator comments and update description verbiage to indicate it's the 'minimum recommended'

[garrett-eclipse]

Proposing re-introducing the seperation of is_supported and is_secure

[garrett-eclipse]

Thanks @danieltj this is great. I see them being much more useful with the version clear and available even when unexpanded.

In 47644.3.diff I've made the following additions;

• Translator comments;

Line 653 - translators: %s: The minimum recommended PHP version
Line 676 - translators: %s: The server PHP version.
Line 687 - translators: %s: The server PHP version.
*This also caused the sprintf functions there to become multi-line.

• Verbiage in description was updated for clarity as the value is the recommended_version and not the latest version (as there's more recent minors).

I went with - The minimum recommended version of PHP is %s.
*Used minimum recommended verbiage over just recommended as I would assume the most recent minor (7.3.7) would really be the recommendation but we're using the most recent major (7.3).

Replying to danieltj:

I took it upon myself to merge the is_supported and is_secure recommended checks together because to me they didn't seem to serve much of a purpose as 7.2.x and 7.1.x are both out of date PHP version but also both supported anyway so it made little sense to have a slightly different wording for something that is basically the same.

Saves translators doing an additional string. Sorry for so many replies at once!

I've also supplied 47644.3.revert-is_secure.diff as I feel there's a large difference between is_supported and is_secure and although it may seem slight the difference between the should and recommend verbiage is important.
​https://www.php.net/supported-versions.php
Referring to the support matrix for PHP;

Active support (is_supported) - A release that is being actively supported. Reported bugs and security issues are fixed and regular point releases are made.
Security fixes only (is_secure) - A release that is supported for critical security issues only. Releases are only made on an as-needed basis.

Many government bodies and large companies have a policy of stability in software and stay on the active support versions but don't upgrade to the latest. For these users and many others they should upgrade when their version drops from active support (is_supported) to security fixes (is_secure), but when they are on an actively supported version while it's recommended they upgrade in many cases they probably shouldn't due to their policies.
Note: The reversion patch also has the translator comments and verbiage change.

Happy to discuss that point further.

Again, thanks for the patch @danieltj marked for testing and a 2nd-opinion on the above.

[garrett-eclipse]

When PHP 7.2 the update is only recommended

[garrett-eclipse]

When on PHP 7.1 the admin should update PHP

[garrett-eclipse]

From #core-site-health discussion today some notes;
@clorith;

It's on my radar to look over the input there, ideally I'd like to avoid moving numbers in the "headers", and instead introduce a second paragraph with the relevant numbers in the description to keep the information overload to a minimum whenever possible (edited)

@afragen;

Also, when listing the PHP requirement we need to avoid confusion between 7.3 and 7.3.x versions

@clorith;

Would it be better if we just show the <major>.<minor> and strip out the patch version to keep things simpler for the user, at least when making recommendations ?

@garrett-eclipse;

That makes sense, would suggest using ‘minimum recommended’ verbiage instead of just ‘recommended’ so users don’t just do the 7.3 and will feel ok to go with a 7.3.x

[danieltj]

For what it's worth I don't think the version must be in the title, although it would add some consistency compared to other checks that are made which have versions in them.

I do think usage on the word 'we' needs to go though and the versions need to be included somewhere to say what you have and what you need to update to.

[garrett-eclipse]

Replying to danieltj:

For what it's worth I don't think the version must be in the title, although it would add some consistency compared to other checks that are made which have versions in them.

I do think usage on the word 'we' needs to go though and the versions need to be included somewhere to say what you have and what you need to update to.

Thanks for the input @danieltj looking at other checks I see what you mean about version in the title as that's in the WP version check, on my up to date install it states Your WordPress version is up to date (5.2.2). I'm also with you on dropping the 'we' and agree we need to include what version someone is on and what they need to update too most likely in the description.

Adding 'needs-copy-review' to get thoughts on the use of 'we' and suggest copy for the description portion of the check.

[SergeyBiryukov]

What's the reason for changing "build and maintain WordPress" to "power WordPress"? Maybe it's just me, but the former seems a bit easier to read and translate.

[davidbaumwald]

+1 about the translation. Using "power" would require more disambiguation for I18N than the original wording.

[marybaum]

In English I would suggest we say "run WordPress"

if there's a problem with "power WordPress"

"Build and maintain" might be more accurate, but when we're talking to people who need to do things we recommend, we want to maintain a sense of forward motion, of energy, to engage them in reading the sentence and then finding the energy to do what we ask.

Replying to SergeyBiryukov:

What's the reason for changing "build and maintain WordPress" to "power WordPress"? Maybe it's just me, but the former seems a bit easier to read and translate.

[marybaum]

I do agree we should use the version names, and we can be a little more direct to get around the We issue:

You're running version 5.2.x, which is outdated and could make your site vulnerable. Please update to 5.3 for a faster, more secure site -- and some great new features!

Replying to garrett-eclipse:

Replying to danieltj:

For what it's worth I don't think the version must be in the title, although it would add some consistency compared to other checks that are made which have versions in them.

I do think usage on the word 'we' needs to go though and the versions need to be included somewhere to say what you have and what you need to update to.

Thanks for the input @danieltj looking at other checks I see what you mean about version in the title as that's in the WP version check, on my up to date install it states Your WordPress version is up to date (5.2.2). I'm also with you on dropping the 'we' and agree we need to include what version someone is on and what they need to update too most likely in the description.

Adding 'needs-copy-review' to get thoughts on the use of 'we' and suggest copy for the description portion of the check.

[garrett-eclipse]

Refresh to address 'we', 'power' and 'security' for the strings but kept it simple

[garrett-eclipse]

Thanks @marybaum I appreciate the feedback.

While more clear that is a little too verbose for the accordion label here.

I've taken another attempt here 47644.4.diff and below is a summary of strings in my current patch (%s refers to version string), would love your thoughts @marybaum;

• Description (Used in all types of this test result);

PHP is the programming language used to build and maintain WordPress. Newer versions of PHP are both faster and more secure, so staying up to date will have a positive effect on your site’s overall performance and security. The minimum recommended version of PHP is %s.

• Label for up to date;

Your version of PHP (%s) is up to date

• Label for is_supported when older than recommended but still receiving active support;

Your version of PHP (%s) is out of date

• Label for is_secure when their version is only receiving security fixes

Your version of PHP (%s) should be updated

• Label for no longer secure versions;

Your version of PHP (%s) requires an update
*The main verbiage change I did was minimal to avoid the 'We' and switch recommend to just indicating their version is no longer up to date.
*I've also moved the version number to tie it directly to PHP, and updated the WordPress version string to match. This maps the version directly to the word it's meant for avoiding confusion. I did preserve the version in the label as it's already in convertion for WP version and I felt it more useful at a glance as once users have read the description they'll most likely skip it due to content fatigue, best to have it prominent.
*Overall I tried to avoid a large rewrite and just address the point on 'power' and 'we', and added 'security' to the description.

Note: Thanks @SergeyBiryukov I did switch back from 'power WordPress' to 'build and maintain WordPress'

Would love feedback and testing so this can be committed before Monday. @clorith / @afragen / @SergeyBiryukov / @danieltj / @marybaum

Cheers

[garrett-eclipse]

Latest display with version tied to PHP word

[marybaum]

Replying to garrett-eclipse:

Ah. I think I conflated several different labels.

Let's try this in the description:

<?php
PHP is the programming language developers use to build and maintain WordPress. Newer versions of PHP are faster and more secure, so staying up to date ''[ no hyphens bc after the verb ]'' will help make your site faster and more secure, too. You should be running at least version %s.

Label for is_secure:

<?php
Your version of PHP (%s) needs an update.

Label for no-longer-secure versions:

<?php
Your version of PHP (%s) is not secure and needs an update.

Thanks @marybaum I appreciate the feedback.

While more clear that is a little too verbose for the accordion label here.

I've taken another attempt here 47644.4.diff and below is a summary of strings in my current patch (%s refers to version string), would love your thoughts @marybaum;

• Description (Used in all types of this test result);

PHP is the programming language used to build and maintain WordPress. Newer versions of PHP are both faster and more secure, so staying up to date will have a positive effect on your site’s overall performance and security. The minimum recommended version of PHP is %s.

• Label for up to date;

Your version of PHP (%s) is up to date

• Label for is_supported when older than recommended but still receiving active support;

Your version of PHP (%s) is out of date

• Label for is_secure when their version is only receiving security fixes

Your version of PHP (%s) should be updated

• Label for no longer secure versions;

Your version of PHP (%s) requires an update
*The main verbiage change I did was minimal to avoid the 'We' and switch recommend to just indicating their version is no longer up to date.
*I've also moved the version number to tie it directly to PHP, and updated the WordPress version string to match. This maps the version directly to the word it's meant for avoiding confusion. I did preserve the version in the label as it's already in convertion for WP version and I felt it more useful at a glance as once users have read the description they'll most likely skip it due to content fatigue, best to have it prominent.
*Overall I tried to avoid a large rewrite and just address the point on 'power' and 'we', and added 'security' to the description.

Note: Thanks @SergeyBiryukov I did switch back from 'power WordPress' to 'build and maintain WordPress'

Would love feedback and testing so this can be committed before Monday. @clorith / @afragen / @SergeyBiryukov / @danieltj / @marybaum

Cheers

[garrett-eclipse]

Refresh of copy

[garrett-eclipse]

Thanks @marybaum I appreciate that, some great tweaks here.

I've updated the description in 47644.5.diff to;
'PHP is the programming language used to build and maintain WordPress. Newer versions of PHP are faster and more secure, so staying up to date will help your site’s overall performance and security. The minimum recommended version of PHP is %s.'

• I avoided 'developers' as WP sites can be built and maintained by anyone
• I avoided repeating 'faster and more secure' but do think 'help' is a great improvement
• I avoided 'You should be running at least' simply because this is a uniform description so installs that are at the latest and greatest will still see it in the passed tests but then may get confused when it informs them they should do something. Left as just informative as to what is the minimum recommended version.

I didn't update the other labels as I don't believe we should use the word 'need' for recommendations. 'requires' is the strongest word I'd use here as those versions won't be able to update due to WP requiring a higher version of PHP. But need conveys their site will no longer function without making this action.

[marybaum]

In the interest of letting this horse heal up so we can ride it home, I'll say we have a good meeting of the minds.

There are times when it's okay to repeat a construction to drive home a point -- it's called parallel construction.

"The ingredient is lime-flavored, so the dish is lime-flavored ... " That's not the world's greatest example, but it does reinforce to the reader that the damn thing is going to taste like limes.

Still, the barn door closes Monday, so I think we're good where we are, and we can go ahead and commit beforehand.

Replying to garrett-eclipse:

Thanks @marybaum I appreciate that, some great tweaks here.

I've updated the description in 47644.5.diff to;
'PHP is the programming language used to build and maintain WordPress. Newer versions of PHP are faster and more secure, so staying up to date will help your site’s overall performance and security. The minimum recommended version of PHP is %s.'

• I avoided 'developers' as WP sites can be built and maintained by anyone
• I avoided repeating 'faster and more secure' but do think 'help' is a great improvement
• I avoided 'You should be running at least' simply because this is a uniform description so installs that are at the latest and greatest will still see it in the passed tests but then may get confused when it informs them they should do something. Left as just informative as to what is the minimum recommended version.

I didn't update the other labels as I don't believe we should use the word 'need' for recommendations. 'requires' is the strongest word I'd use here as those versions won't be able to update due to WP requiring a higher version of PHP. But need conveys their site will no longer function without making this action.

[garrett-eclipse]

Thanks @marybaum moving it forward for final review.

[afragen]

@garrett-eclipse I think there’s a typo in a comment receiving not recieving.

[garrett-eclipse]

Patch receiving spelling correction, thanks @afragen

[SergeyBiryukov]

In 46267:

Site Health: Improve wording for PHP update warning.

Props danieltj, garrett-eclipse, marybaum, afragen, chetan200891.
Fixes #47644.