Support requires and requires_php in plugin/theme list and update command

[mrsdizzie]

This introduces a new update sate of 'unavailable' which is when there is a new version of a theme/plugin upstream but the local WordPress / PHP requirements do not meet the requirements set by the authors.

What this changes:

Changes the update field of an item from a bool which laters gets turned into 'available' or 'none' to a string which will be either 'available', 'none', or 'unavailable'. New unavailable is based off a check against WordPress and PHP requirements via the requires and requires_php fields.

$ wp plugin list
+----------------+----------+-------------+---------+----------------+-------------+----------+--------------+
| name           | status   | update      | version | update_version | auto_update | requires | requires_php |
+----------------+----------+-------------+---------+----------------+-------------+----------+--------------+
| akismet        | inactive | available   | 5.1     | 5.3.5          | off         | 5.8      | 5.6.20       |
| edit-flow      | inactive | none        | 0.9.9   |                | off         | 6.0      | 8.0          |
| wp-super-cache | inactive | unavailable | 1.9.4   | 1.12.4         | off         | 6.5      | 7.0          |
+----------------+----------+-------------+---------+----------------+-------------+----------+--------------+

$ wp plugin update wp-super-cache
Warning: wp-super-cache: Requires a newer version of WordPress [6.5] than installed [6.2]
Error: No plugins updated.

This works similarly for PHP versions too:

$ php -v
PHP 7.4.33 (cli) (built: Dec 16 2024 20:48:31) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.33, Copyright (c), by Zend Technologies
$ wp plugin list
+----------------+----------+-------------+---------+----------------+-------------+----------+--------------+
| name           | status   | update      | version | update_version | auto_update | requires | requires_php |
+----------------+----------+-------------+---------+----------------+-------------+----------+--------------+
| akismet        | inactive | available   | 5.1     | 5.3.5          | off         | 5.8      | 5.6.20       |
| edit-flow      | inactive | unavailable | 0.9.8   | 0.9.9          | off         | 6.0      | 8.0          |
| wp-super-cache | inactive | unavailable | 1.9.4   | 1.12.4         | off         | 6.5      | 7.0          |
+----------------+----------+-------------+---------+----------------+-------------+----------+--------------+
$ wp plugin update edit-flow
Warning: edit-flow: Requires a newer version of PHP [8.0] than available [7.4.33]
Error: No plugins updated.

This also fixes issues like #428 by removing incompatible updates from a command like:

$ wp plugin list --update=available
+---------+----------+-----------+---------+----------------+-------------+----------+--------------+
| name    | status   | update    | version | update_version | auto_update | requires | requires_php |
+---------+----------+-----------+---------+----------------+-------------+----------+--------------+
| akismet | inactive | available | 5.1     | 5.3.5          | off         | 5.8      | 5.6.20       |
+---------+----------+-----------+---------+----------------+-------------+----------+--------------+

This also adds the fields requires and requires_php. While these aren't default fields, I did change it so that it will include them by default if one of the plugins has an update sate of unavailable (so it is immediately clear why the update is unavailable).

I've also written it so that requires and requires_php fields will use either what is provided for the latest version in the case of an update (unavailable or not) or whatever is listed in the current plugin file.

This means that in the case of 'none' it i showing the requirements for the current version, while in the case of 'available' or 'unavailable' it is showing the requirements for the update_version. This could be a bit confusing, but it made even less sense the other way to have it list an update as 'unavailable' while showing the older and already met requirements from the currently installed version. Those were just my initial idea, so any feedback welcome there. Similar to the field names, etc...

Finally, I couldn't find much documentation about the wordpress.org update API, but what I saw in testing is:

For plugins, the wordpress.org api will check the version of WordPress sent in the header of the request from wp core and if the latest upstream version requires a newer version of WordPress, it moves that plugin into the no_update section of the response, along with any other plugins that just don't have an update available. It doesn't know the current version of PHP, so it can't check that. The current situation is that if an upstream update requires a newer version of WordPress then WP CLI doesn't see it at all, because it doesn't look for it in the no_updates section of the response. If it requires a newer version of PHP, WP CLI will show it as an available update because it doesn't know about the PHP incompatibility.

For themes, it doesn't seem to do that same filtering.

This PR fixes both those cases by correctly showing the updates as unavailable rather than not existing or ready to install. My main use case is that I want to be able to run wp plugin list and see if a site is running the latest version of any installed plugin or theme. If not, I want to know if it is because the updates haven't been applied or if they are held back because of requirement changes in newer versions.

[swissspidy]

Thanks a lot for working on this!

I haven't tested it yet, but it looks very promising already. It will be very useful for better managing updates when knowing that newer (albeit incompatible) versions are available.

On that note, what do you think about renaming unavailable to incompatible?

IMO unavailable sounds too similar to none, almost a synonym in that context.

[mrsdizzie]

On that note, what do you think about renaming unavailable to incompatible?

IMO unavailable sounds too similar to none, almost a synonym in that context.

Interesting, I picked unavailable because its an antonym of the other option available but I can see that : )

incompatible could work too and I don't really have a strong preference on that. I think whatever word also gives the most confidence that wp cli isn't going to install it if you do something like wp plugin update --all

[swissspidy]

On that note, what do you think about renaming unavailable to incompatible?
IMO unavailable sounds too similar to none, almost a synonym in that context.

Interesting, I picked unavailable because its an antonym of the other option available but I can see that : )

incompatible could work too and I don't really have a strong preference on that. I think whatever word also gives the most confidence that wp cli isn't going to install it if you do something like wp plugin update --all

@wp-cli/committers @wp-cli/maintainers any preference here on the wording? Also generally a review here is appreciated :)