Prepare to gracefully drop support for older PHP versions

[JDGrimes]

We should ideally wait until WordPress ups its PHP version before we up ours. However, I think that we should be prepared for every eventuality, like Travis dropping 5.2 support again, or something else unseen that would affect us but not cause WordPress to update. Also, note that WordPress is less burdened by supporting many PHP versions than we are. WordPress only has to test against each PHP version, we have to test against each version of WordPress that we support for each PHP version. For modules, they have to test against each version combination of WordPoints, WordPress, and PHP. We limit the number of WordPoints and WordPress versions supported, but the list of PHP versions keeps growing, and eventually this will become unsustainable.

So let's get some code into WordPoints that will give us the option to up the PHP version if we want to, while minimizing the pain caused to users. Often plugins just put a version check into the main plugin file, and exit with an error if the PHP version isn't met. This doesn't take into account when users haven't just installed the plugin and somehow ignored the PHP version requirements, but instead had installed it before and are now updating to a new version that has upped the PHP requirements.

We can do better. We could hide the update from the users, or tell them about it but not let them install it until they've updated their PHP version. They shouldn't have to wait until they've updated to find out that they just killed the WordPoints plugin and it is basically inactive until they update PHP. That's why to get this in now, because if the user hasn't updated to a version of WordPoints that will check this for them, then they won't know that an update is incompatible until after they update WordPoints. I don't think that there is anything that we can do for those users, other than tell them to update PHP, or automatically roll ourselves back to the last compatible version.

So basically, we aren't going to actually do #271 yet, we're just going to put some things in place that will make it possible for us to do it in a future version with the least frustration to our users.

[JDGrimes]

One big question is how we will know that a new version of WordPoints requires a greater version of PHP. Ideally, we don't want to "phone home" to anywhere, we'd like to be able to determine this just from the information about the update that WordPress.org already supplies via the plugin API. It doesn't supply PHP version information directly at this point (though see WP#23880), but I suppose that we could come up with a syntax for specifying this in the readme or something, since I think that that is sent with the other plugin info.

Alternatively, we could just plan far in advance when we are going to drop which PHP versions, and hard-code this. That also reminds me that we've previously suggested that it would be best to actually up the version in concert with a major version bump (like the release of 3.0.0), since that would also contain other breaking changes. I guess if we did that, we wouldn't have to be quite as worried about doing this gracefully, but still, I think we should try.

[JDGrimes]

I suppose if we just wanted to show the user a message about the change in requirements we could just put that in the update notice or the changelog. The problem is that the user is not guaranteed to see that, I don't know how many users really read the changelogs. We also have to consider people who have automatic updates enabled on their sites. There is nothing like going to your site and finding out that a plugin has been killing it for the last week due to an automatically installed update that upped the required PHP version.

[JDGrimes]

A plugin users might find useful to check their PHP version: https://wordpress.org/plugins/display-php-version/

And to be clear the "official policy" of the WordPress.org plugin directory regarding PHP version requirements is that you can pretty much do whatever you want as long as you degrade more-or-less gracefully.

[JDGrimes]

The data obtained by wp_update_plugins() looks like this:

    'wordpoints/wordpoints.php' => 
    stdClass::__set_state(array(
       'id' => 'w.org/plugins/wordpoints',
       'slug' => 'wordpoints',
       'plugin' => 'wordpoints/wordpoints.php',
       'new_version' => '2.2.2',
       'url' => 'https://wordpress.org/plugins/wordpoints/',
       'package' => 'https://downloads.wordpress.org/plugin/wordpoints.2.2.2.zip',
    )),

So short of downloading the plugin package, we can't get info about the requirements from that, if we expect to just indicate that in the readme.txt.

[JDGrimes]

Just a reminder: we'd still need to check the PHP version in the main plugin file, in case the user installs the plugin manually (or their PHP version is downgraded somehow, maybe migrating to a different server). But we'd like to have that be a last resort, if possible.

[JDGrimes]

We can use the plugins_api() function to retrieve the description or all of the readme.txt sections. You can see the available data here: https://api.wordpress.org/plugins/info/1.0/wordpoints.json

Basically, the readme sections are returned, but not the headers from the readme (or unnecessary sections, like Update Notices). That just means that we can't just add a custom header to the readme if we are going to utilize this function, we've got to specify the version in the description or changelog or something. Possibly we could even hide this using an HTML comment if we wanted to, I'm not sure. (We'd still need to tell users, but a more parser friendly version could be specified in that way and be hidden.)

[JDGrimes]

I just found BP#7196, which shows how the BuddyPress developers handled the update in requirements to PHP 5.3 in BP 2.8.0. Basically, they hard-coded the version, and replaced the regular update notice in the plugins list table with an error notice, while hiding the update on the Updates screen. In addition, they added a dismissible notice that was displayed in BP 2.7.0 if the site was running a lower version of PHP.

We can probably take that and adapt it to be more flexible—or we can consider hard-coding our PHP version updates in advance. Also hard-coding when to begin warning users about the next version is more difficult though, if we are talking about trying to do that far in advance. Ideally, it would be good to be able to be more circumspect, and decide when to bump the version based on the events as they unfold. We generally would like to plan something like that well in advance, of course, due to the potential implications, but I guess we should also consider the possibility that we might be forcing ourselves to up the PHP requirement before we might actually want to, just due to a lack of foresight.

[JDGrimes]

The only problem with they BuddyPress approach is that it doesn't give the user an opportunity to see the changelog, which could possibly be reducing the incentive to upgrade (or just frustrating the user as they have to find their way to the plugin's homepage on WordPress.org in order to see it). Possibly we could still show a "see changelog" link, but we'd want to disable the update button in the popup, I guess.

[JDGrimes]

The vast majority of users should ideally never find themselves in this situation, so for now I am fine with not showing the changelog. If we think that we may be affecting a larger proportion of users in the future, we may want to give some thought though.

Actually, it looks like you can see the changelog using the "View Details" link that WordPress now displays beneath each plugin's description. And there you can also hit a button at the bottom to install the plugin:

But we can disable that using the same trick that hides the update on the Updates screen:

[JDGrimes]

So here is what the plugin row looks like:

Note that the checkbox is also disabled, to prevent bulk updates.

[JDGrimes]

One thing that I have been wondering is what we should do when a user has not updated WordPoints in so long that there are actually several PHP version jumps. Think if a situation like this: The user is running PHP 5.3, and the latest version of WordPoints requires PHP 5.4. So they can't update to the latest version. However, the previous version of WordPoints only required 5.3, but the user didn't update in time, they are still 3 or 4 versions back. They sound like somebody who probably isn't going to ever update their PHP anyway, so why do we even care? (Just kidding. Mostly.) But in a situation like this, the user could potentially update WordPoints to a newer version, but they won't be able to because they can't update to the latest version.

I've been wondering how WordPress handles this for the WordPress version requirements. WordPress will ignore an update for a plugin if that update requires a newer version of WordPress. I suspected that possibly an older update would still be provided to the user, if it was compatible. However, after firing up an instance of WordPress 4.1 and installing an ancient version of WordPoints, no update for WordPoints was indicated, even with a forced check on the Updates dashboard. So I guess WordPoints currently only ever offers updates to the latest version, even if intervening versions might have been compatible.

That doesn't mean that we have to follow its lead here, of course, but it makes it less of a priority. And as noted above, if a user doesn't update WordPoints for that number of versions (which generally should be a significant number between PHP version jumps), then they are just asking for trouble anyway. So let's not add that extra complexity here, for such a small edge-case.

[JDGrimes]

The user docs for this is here: http://wordpoints.org/user-guide/php-compatibility/

We'll probably want to update that when we actually do up the PHP version, with some specifics about the version of WordPoints affected, etc.