Explicitly require the hash extension.

[johnbillion]

This marks hash as a required extension and implements checks for required extensions in the same manner as PHP and MySQL version checks during installation, upgrade, and regular runtime. The hash extension is required for the following tickets:

• Trac ticket: https://core.trac.wordpress.org/ticket/60638
• Trac ticket: https://core.trac.wordpress.org/ticket/21022
• Trac ticket: https://core.trac.wordpress.org/ticket/62815
• Trac ticket: https://core.trac.wordpress.org/ticket/56017

If a site doesn't have hash (or json) installed then this prevents the site from updating to 6.8 from a prior version because update-core.php gets put into place during the update routine. More details at https://meta.trac.wordpress.org/ticket/7900 .

Effects

If a version of PHP is being used that does not have the hash extension installed:

• During an update from any prior version, the update will terminate with the error "The update cannot be installed because WordPress 6.8 requires the hash PHP extension", whether the update is performed via the Dashboard -> Updates menu or via the wp core update command in WP-CLI. The site will remain at the prior version and will remain functional because at the point of this error the only file that has been overwritten is update-core.php. If the user installs the missing extension they can proceed with the update.
• If a user manually updates WordPress by overwriting the core files with the new version, their site will become inaccessible and will show the "WordPress 6.8 requires the hash PHP extension" error in the same way it would for an unmet PHP version requirement.
• During a fresh installation, the user will be presented with an error message that says "WordPress 6.8 requires the hash PHP extension", and installation won't proceed. This is the same behaviour as it would be for an unmet PHP version requirement.

Testing steps

This is best tested by manually adjusting the $required_php_extensions array in wp-includes/version.php to include an extension that doesn't exist on your installation. My preferred method is adding extensions named after fruit, but Pete prefers characters from musicals. Do what feels right for you.

1. Ensure missing extensions are caught during bootstrap and shown as an error in the same way that an unmet PHP or MySQL version does. Multiple missing extensions should all be shown at once. An unmet PHP version dependency should always take precedence over an unmet extension dependency.
2. Reset your environment and try to install WordPress. Ensure missing extensions prevent installation. Multiple missing extensions should all be shown at once.
3. Testing an upgrade is difficult because it relies on the incoming update having $required_php_extensions present. Testing steps to follow.
4. Ensure that a site where all required extensions are installed can be installed, upgraded, and run without issue.

Testing on GitHub Actions

I've opened a separate PR at #8285 which combines this branch with #8252 in order to test the upgrade routine on GitHub Actions with an additional extension requirement that is not met. The wp core update step successfully fails with the appropriate error, preventing the upgrade from continuing. After the error the site remains operational at the previous version because no core files have been overwritten at that point except update-core.php. This is the same behaviour as an unmet PHP or MySQL requirement.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props johnbillion, peterwilsoncc, ayeshrajans.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[johnbillion]

@dd32 I would like to ask you to double check those stats you pulled about the hash extension. It's great that only a single site on 6.1+ has json but not hash, but it's also a suspiciously low number. Is there any chance it may not be accurate? Better to be safe than sorry. Thanks!

[Ayesh]

PHP 7.4 is the first version to properly bundle the hash extension, so prior to PHP 7.4, it is technically possible to compile PHP without the hash extension.

[peterwilsoncc]

@johnbillion In it's current form, the error will only show the first extension that is missing. If an install is missing both required extensions, I think it would be helpful to include that in the WP_Error. Does something like this work?

	// Add a warning when required PHP extensions are missing.
	$required_php_extensions = array( 'json', 'hash' );
	$missing_php_extensions  = array();
	foreach ( $required_php_extensions as $required_php_extension ) {
		if ( ! extension_loaded( $required_php_extension ) ) {
			$missing_php_extensions[] = $required_php_extension;
		}
	}

	if ( ! empty( $missing_php_extensions ) ) {
		$php_extension_error = new WP_Error();
		foreach ( $missing_php_extensions as $missing_php_extension ) {
			$php_extension_error->add(
				"php_not_compatible_{$missing_php_extension}",
				sprintf(
					/* translators: 1: WordPress version number, 2: The PHP extension name needed. */
					__( 'The update cannot be installed because WordPress %1$s requires the %2$s PHP extension.' ),
					$wp_version,
					strtoupper( $missing_php_extension )
				)
			);
		}
		return $php_extension_error;
	}

[johnbillion]

@Ayesh Yep that's correct. Dion ran the numbers in #8097 and saw almost zero affected sites with hash disabled, hence this proposal. I've asked him to run the numbers again to double check!

[johnbillion]

@peterwilsoncc Good point, I'll take a look

[johnbillion]

So we've a catch-22 situation here, the code in update_core() cannot introduce any new logic to prevent an update from occurring because its code won't yet be in place during the update. The update_core() function specifically reads $required_php_version and $required_mysql_version from wp-includes/version.php in the update package for the PHP and MySQL version checks.

For future-proofing we could introduce a $required_php_extensions global in this file, but it wouldn't be able to take effect during any update from a version earlier than 6.8.

Edit: This isn't true, the update-core.php file is put into place in order to facilitate checking the dependencies for an update prior to it happening. This is how the requirements for PHP and MySQL are checked.

[peterwilsoncc]

@johnbillion It could be done on the API by only presenting the 6.8 update if the hash extension is available. The main consideration there would be how to handle two situations:

• updating from a version prior to 6.1
• updates from sites running a plugin to remove passing extension data to wordpress.org

Each of these will remain a problem, even if a two step approach is taken (prep in 6.8, implement in 6.9) so the API approach will be needed in some form regardless.

I'm sure patches to meta are welcome but I was unable to find where to create a PR. in the meta repo. It's possible the API is in the private systems repo.

[peterwilsoncc]

This tests well, I was unable to reach the upgrade-core path as noted inline.

As the variable is a global, should it have a wp_ prefix too?

Edit: To test, I added elphaba as a required extension to avoid the need to recompile PHP.

[peterwilsoncc]

I'm happy with this.

To test, I created a plugin that replaced the update API to present a locally hosted zip file. I then modified the required extensions to include a fictional extension as I didn't want to recompile PHP. That was included in the zip file.

Zip file: https://www.dropbox.com/s/dlq4f3dzjp7h2i7/wordpress-fake-ext.zip?dl=0
Hijack plugin: https://gist.github.com/peterwilsoncc/183592b397403e2220c3e511b9dc445f

I tested upgrading via:

• dashboard update: failed due to required extension
• wp cli update: failed due to required extension
• autoupdate: failed -- I did not get an email but presume it's due to the failed extension

I tested installation via WP CLI and it failed too due to the required extension.

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 59803
GitHub commit: 61a39de

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.