WordPress.org

Make WordPress Core

Opened 3 months ago

Closed 3 weeks ago

#47644 closed enhancement (fixed)

Improve wording for PHP update warning in Site Health

Reported by: danieltj Owned by: marybaum
Milestone: 5.3 Priority: normal
Severity: minor Version: 5.2
Component: Site Health Keywords: has-patch has-copy-review commit
Focuses: Cc:
PR Number:

Description

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

Attachments (18)

wp-sitehealth-php-warning.png (60.9 KB) - added by danieltj 3 months ago.
The PHP check made in Site Health
47644.diff (609 bytes) - added by chetan200891 3 months ago.
Created initial patch.
wp-sh-php-73x.png (28.0 KB) - added by danieltj 3 months ago.
Running php version 7.3.x
wp-sh-php-72x.png (28.4 KB) - added by danieltj 3 months ago.
Running php version 7.2.x
wp-sh-php-71x.png (28.4 KB) - added by danieltj 3 months ago.
Running php version 7.1.x
wp-sh-php-56x.png (28.5 KB) - added by danieltj 3 months ago.
Running php version 5.6.x
47644.2.diff (2.4 KB) - added by danieltj 3 months ago.
Proposed patch for PHP test.
wp-sh-dj-patch-73x.png (30.2 KB) - added by danieltj 3 months ago.
Patch applied using PHP 7.3.x
wp-sh-dj-patch-72x.png (30.8 KB) - added by danieltj 3 months ago.
Patch applied using PHP 7.2.x
wp-sh-dj-patch-56x.png (30.8 KB) - added by danieltj 3 months ago.
Patch applied using PHP 5.6.x
47644.3.diff (2.6 KB) - added by garrett-eclipse 3 months ago.
Updated patch to introduce translator comments and update description verbiage to indicate it's the 'minimum recommended'
47644.3.revert-is_secure.diff (2.7 KB) - added by garrett-eclipse 3 months ago.
Proposing re-introducing the seperation of is_supported and is_secure
Screen Shot 2019-07-07 at 8.12.19 AM.png (79.4 KB) - added by garrett-eclipse 3 months ago.
When PHP 7.2 the update is only recommended
Screen Shot 2019-07-07 at 8.14.14 AM.png (79.1 KB) - added by garrett-eclipse 3 months ago.
When on PHP 7.1 the admin should update PHP
47644.4.diff (3.1 KB) - added by garrett-eclipse 4 weeks ago.
Refresh to address 'we', 'power' and 'security' for the strings but kept it simple
Screen Shot 2019-09-19 at 1.32.09 PM.png (85.6 KB) - added by garrett-eclipse 4 weeks ago.
Latest display with version tied to PHP word
47644.5.diff (3.0 KB) - added by garrett-eclipse 4 weeks ago.
Refresh of copy
47644.6.diff (3.0 KB) - added by garrett-eclipse 4 weeks ago.
Patch receiving spelling correction, thanks @afragen

Download all attachments as: .zip

Change History (47)

@danieltj
3 months ago

The PHP check made in Site Health

#1 follow-up: @swissspidy
3 months ago

  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to Future Release

Great to see you here again, Daniel!

These sound like some good improvements to me.

@chetan200891
3 months ago

Created initial patch.

This ticket was mentioned in Slack in #core by justinahinon. View the logs.


3 months ago

#3 @afragen
3 months ago

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

#4 @garrett-eclipse
3 months ago

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

#5 in reply to: ↑ description @SergeyBiryukov
3 months ago

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

#6 in reply to: ↑ 1 @danieltj
3 months ago

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.

#7 @garrett-eclipse
3 months ago

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

#8 @afragen
3 months ago

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.

#9 @JeffPaul
3 months ago

  • Milestone changed from Future Release to 5.3

#10 @danieltj
3 months ago

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
3 months ago

Running php version 7.3.x

@danieltj
3 months ago

Running php version 7.2.x

@danieltj
3 months ago

Running php version 7.1.x

@danieltj
3 months ago

Running php version 5.6.x

#11 @danieltj
3 months ago

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
3 months ago

Proposed patch for PHP test.

@danieltj
3 months ago

Patch applied using PHP 7.3.x

@danieltj
3 months ago

Patch applied using PHP 7.2.x

@danieltj
3 months ago

Patch applied using PHP 5.6.x

#12 follow-up: @danieltj
3 months ago

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
3 months ago

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

@garrett-eclipse
3 months ago

Proposing re-introducing the seperation of is_supported and is_secure

#13 in reply to: ↑ 12 @garrett-eclipse
3 months ago

  • Keywords has-patch 2nd-opinion added; needs-patch removed

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
3 months ago

When PHP 7.2 the update is only recommended

@garrett-eclipse
3 months ago

When on PHP 7.1 the admin should update PHP

#14 @garrett-eclipse
3 months ago

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

#15 follow-up: @danieltj
3 months ago

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.

#16 in reply to: ↑ 15 ; follow-up: @garrett-eclipse
3 months ago

  • Keywords needs-copy-review added

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.

#17 follow-up: @SergeyBiryukov
3 months ago

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.

#18 @davidbaumwald
4 weeks ago

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

#19 @marybaum
4 weeks ago

  • Owner set to marybaum
  • Status changed from new to assigned

#20 in reply to: ↑ 17 @marybaum
4 weeks ago

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.

#21 in reply to: ↑ 16 @marybaum
4 weeks ago

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
4 weeks ago

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

#22 follow-up: @garrett-eclipse
4 weeks ago

  • Keywords needs-testing has-copy-review added; 2nd-opinion needs-copy-review removed

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&#8217;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
4 weeks ago

Latest display with version tied to PHP word

#23 in reply to: ↑ 22 @marybaum
4 weeks ago

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&#8217;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
4 weeks ago

Refresh of copy

#24 follow-up: @garrett-eclipse
4 weeks ago

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&#8217;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.

#25 in reply to: ↑ 24 @marybaum
4 weeks ago

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&#8217;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.

#26 @garrett-eclipse
4 weeks ago

  • Keywords commit added; needs-testing removed

Thanks @marybaum moving it forward for final review.

#27 @afragen
4 weeks ago

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

@garrett-eclipse
4 weeks ago

Patch receiving spelling correction, thanks @afragen

This ticket was mentioned in Slack in #core-site-health by afragen. View the logs.


3 weeks ago

#29 @SergeyBiryukov
3 weeks ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 46267:

Site Health: Improve wording for PHP update warning.

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

Note: See TracTickets for help on using tickets.