Check the required PHP extensions during WordPress installation and updates

[SergeyBiryukov]

Background: #55603

Currently, marking a PHP extension as required in Site Health displays a warning on existing sites if the extension is unavailable, but it does not block the WP installation for new sites, nor the updates to the new version for older sites.

To avoid fatal errors, WordPress core should check for the required PHP extensions both during installation and updates, similar to how we check for the required PHP and MySQL versions.

As also noted by @jrf in comment:2:ticket:55603:

Might also be a good time to improve the code re-usability in that regards (have one master list of requirements and recommendations, which both the requirements checker on installation/load + the Site Health component draw from).

[JavierCasares]

This has always been a big discussion in the Hosting Team.

​WordPress Handbook PHP extensions

Required:

• ​json
• ​mysqli / ​mysqlnd

Highly recommended:

• ​curl – Performs remote request operations.
• ​dom – Used to validate Text Widget content and to automatically configure IIS7+.
• ​exif – Works with metadata stored in images.
• ​fileinfo – Used to detect mimetype of file uploads.
• ​hash – Used for hashing, including passwords and update packages.
• ​imagick – Provides better image quality for media uploads. See WP_Image_Editor for details. Smarter image resizing (for smaller images) and PDF thumbnail support, when Ghost Script is also available.
• ​mbstring – Used to properly handle UTF8 text.
• ​openssl – Permits SSL-based connections to other hosts.
• ​pcre – Increases performance of pattern matching in code searches.
• ​xml – Used for XML parsing, such as from a third-party site.
• ​zip – Used for decompressing Plugins, Themes, and WordPress update packages.

Fallbacks or optional:

• ​bc – For arbitrary precision mathematics, which supports numbers of any size and precision up to 2147483647 decimal digits.
• ​filter – Used for securely filtering user input.
• ​image – If Imagick isn’t installed, the GD Graphics Library is used as a functionally limited fallback for image manipulation.
• ​iconv – Used to convert between character sets.
• ​intl – Enable to perform locale-aware operations including but not limited to formatting, transliteration, encoding conversion, calendar operations, conformant collation, locating text boundaries and working with locale identifiers, timezones and graphemes.
• ​simplexml – Used for XML parsing.
• ​sodium – Validates Signatures and provides securely random bytes.
• ​xmlreader – Used for XML parsing.
• ​zlib – Gzip compression and decompression.

File changes (depends on hosting):

• ​ssh2 – Provide access to resources (shell, remote exec, tunneling, file transfer) on a remote machine using a secure cryptographic transport.
• ​ftp – Implement client access to files servers speaking the File Transfer Protocol (FTP).
• ​sockets – Implements a low-level interface to the socket communication functions based on the popular BSD sockets.

And, finally, a recommendation we did some time ago:

​Why hosters should install the PHP-intl extension

[costdev]

@SergeyBiryukov @jrf What's the preferred approach here for code reusability? Should we use a new constant, such as WP_PHP_EXTENSIONS in wp-includes/default-constants.php?

In ​this Site Health location, it can still be filtered for BC.

If not, what would you propose?

[desrosj]

Related: #47699.

[audrasjb]

With WP 6.1 RC 1 scheduled tomorrow (Oct 10, 2022), there is not much time left to address this ticket. Given it still needs a patch, let's move this ticket to Future Release.

Ps: if you were about to send a patch and if you feel it is realistic to commit it in the next few hours, please feel free to move this ticket back to milestone 6.1.

[SergeyBiryukov]

Related: #47272, #48116.

As noted in comment:36:ticket:55603:

There is precedent for blocking a site from upgrading when a PHP extension is missing. In WordPress 5.2, the ​native JSON extension was marked as required (see [46455]). When an upgrade was attempted and a site did not have this extension loaded, an error was shown and the update was cancelled.
...
One other thing to note is that an error code specific to the scenario where the JSON extension missing is returned, which allows the number of sites to being blocked from an update to be tracked in .org's mission control to gauge whether this deprecation ends up being problematic or not (see [46560]).

This introduces a new workflow which tests the upgrade process from the three latest major versions to the current branch version. The current branch is built and zipped up, and the zip is used by WP-CLI for the update.

This uses a smaller set of matrix values than the "Upgrade Tests" workflow. I think this is sufficient for now, it can always be expanded at a later date if necessary.

Workflow runs can be seen here: ​https://github.com/WordPress/wordpress-develop/actions/workflows/upgrade-develop-testing.yml

Trac ticket: https://core.trac.wordpress.org/ticket/56017
Trac ticket: https://core.trac.wordpress.org/ticket/62221

Thanks for the ping @johnbillion. While I'm not the best person to checkout this proposal, I just wanted to ask a question about the "a new workflow which tests the upgrade process from the three latest major versions to the current branch" part: if this proposal is accepted, does it mean that we'll have to manually bump the related versions on each major release? This is not a blocker, but definitely something that will need some specific documentation on the major release handbook page :)

@audrasjb Yes that's correct. We already have that in several other workflows, eg the performance tests, old branch tests, and upgrade tests. I'll make a note to get the major release handbook page udpated.

we already generate a ZIP of the code in the current branch during the build test workflow

Yeah, if you take a look at the first few commits in this branch you'll see that I was initially trying to use that build, but it requires using the workflow_run trigger in order to make use of the build artifact once the workflow completes, and that trigger can't be tested in a PR because it only functions when the workflow with the trigger exists in the default branch. I tried workflow_dispatch but similarly this can't be tested in a PR from a fork. So I just went with another build.

I think this could be accomplished with some conditional checks, but we'd likely need to add a 3rd-party action like ​changed-files to know when to run each job

I understand your point but I'm not overly keen on adding further third party actions. Is a bunch of conditionals and an extra third party action better than an additional workflow? I don't think there's much between them.

[johnbillion]

In 59803:

Security: Explicitly require the hash PHP extension and add requirement checks during installation and upgrade.

This extension provides the hash() function and support for the SHA-256 algorithm, both of which are required for upcoming security related changes. This extension is almost universally enabled, however it is technically possible to disable it on PHP 7.2 and 7.3, hence the introduction of this requirement and the corresponding requirement checks prior to installing or upgrading WordPress.

Props peterwilsoncc, ayeshrajans, dd32, SergeyBiryukov, johnbillion.

Fixes #60638, #62815, #56017

See #21022

[johnbillion]

In 59804:

Security: Delete a test file that was missed in [59803].

Props swissspidy.

See #60638, #62815, #56017

Thanks, @johnbillion. I think this is a good idea and things are looking good to me. Just to confirm one of my assumptions here, in addition to ​needing to bump the WP versions in the matrix passed for the reusable upgrade testing workflow, we'll also need to make sure the matrix stays up to date with the supported PHP and DB versions as that support changes over time, correct?

I also notice that the current matrix doesn't include any object cache tests. Is that intentional or do you think there would be some value in including at least one object cache test in the matrix?

@joemcgill That's correct. We have that case already with the other upgrade tests. It's unfortunate, and perhaps going forward we could populate the matrix from .version-support-php.json and .version-support-mysql.json, but that would be better proposed in a separate PR I think.

Good spot on the object caching. Looking at the Installation Tests workflow there's a matrix entry for memcached but it's not actually used. The Upgrade Tests workflow doesn't include any handling for memcached.

Adding testing with and without memcached would require a change to the way these installation and upgrade workflow files work because they all use PHP directly on the host runner instead of using the containers. I'll open a follow-up ticket.

Committed in https://core.trac.wordpress.org/changeset/59815

​Handbook page has been updated.