Security in 5.2

Post originally written by Scott Arciszewski.

Protection Against Supply-Chain Attacks

Starting with WordPress 5.2, your website will remain secure even if the wordpress.org servers get hacked.

We are now cryptographically signing WordPress updates with a key that is held offline, and your website will verify these signatures before applying updates.

Signature Verification in WordPress 5.2

When your WordPress site installs an automatic update, from version 5.2 onwards it will first check for the existence of an x-content-signature header. If one isn’t provided by our update server, your WordPress site will instead query for a filenamehere.sig file and parse it.

The signatures were calculated using Ed25519 of the SHA384 hash of the file’s contents. The signature is then base64-encoded for safe transport, no matter how it’s delivered.

The signing keys used to release updates are managed by the WordPress.org core development team. The verification key for the initial release of WordPress 5.2 is fRPyrxb/MvVLbdsYi+OOEv4xc+Eqpsj+kkAS6gNOkI0= (expires April 1, 2021).

(For the sake of specificity: Signing key here means Ed25519 secret key, while verification key means Ed25519 public key.)

To verify an update file, your WordPress site will calculate the SHA384 hash of the update file and then verify the Ed25519 signature of this hash. If you’re running PHP 7.1 or older and have not installed the Sodium extension, the signature verification code is provided by sodium compat.

Our signature verification is implemented in the new verify_file_signature() function, inside wp-admin/includes/file.php.

Modern Cryptography for WordPress Plugins

The inclusion of sodium_compat on WordPress 5.2 means that plugin developers can start to migrate their custom cryptography code away from mcrypt (which was deprecated in PHP 7.1, and removed in PHP 7.2) and towards libsodium.

Example Functions

<?php
/**
 * @param string $message
 * @param string $key
 * @return string
 */
function wp_custom_encrypt( $message, $key )
{
    $nonce = random_bytes(24);
    return base64_encode(
        $nonce . sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
            $message,
            $nonce,
            $nonce,
            $key
        )
    );
}

/**
 * @param string $message
 * @param string $key
 * @return string
 */
function wp_custom_decrypt( $message, $key )
{
    $decoded = base64_decode($message);
    $nonce = substr($decoded, 0, 24);
    $ciphertext = substr($decoded, 24);
    return sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
        $ciphertext,
        $nonce,
        $nonce,
        $key
    );
}

How to Seamlessly and Securely Upgrade your Plugins to Use the New Cryptography APIs

If your plugin uses encryption provided by the abandoned mcrypt extension, there are two strategies for securely migrating your code to use libsodium.

Strategy 1: All Data Decryptable at Run-Time

If you can encrypt/decrypt arbitrary records, the most straightforward thing to do is to use mcrypt_decrypt() to obtain the plaintext, then re-encrypt your code using libsodium in one sitting.

Then remove the runtime code for handling mcrypt-encrypted messages.

<?php
// Do this in one sitting
$plaintext = mcrypt_decrypt( $mcryptCipher, $oldKey, $ciphertext, $mode, $iv );
$encrypted = wp_custom_encrypt( $plaintext, $newKey );

Strategy 2: Only Some Data Decryptable at Run-Time

If you can’t decrypt all records at once, the best thing to do is to immediately re-encrypt everything using sodium_crypto_secretbox() and then, at a later time, apply the mcrypt-flavored decryption routine (if it’s still encrypted).

<?php
/**
 * Migrate legacy ciphertext to libsodium
 * 
 * @param string $message
 * @param string $newKey
 * @return string
 */
function wp_migrate_encrypt( $message, $newKey )
{
    return wp_custom_encrypt(
        'legacy:' . base64_encode($message),
        $newKey
    );
}

/**
 * @param string $message
 * @param string $newKey
 * @param string $oldKey
 * @return string 
 */
function wp_migrate_decrypt( $message, $newKey, $oldKey )
{ 
    $plaintext = wp_custom_decrypt($message, $newKey);
    if ( substr($plaintext, 0, 7) === 'legacy:' ) {
        $decoded = base64_decode( substr($plaintext, 7) );
        if ( is_string($decoded) ) {
            // Now apply your mcrypt-based decryption code
            $plaintext = mcrypt_decrypt( $mcryptCipher, $oldKey, $decoded, $mode, $iv );

            // Call a re-encrypt routine here
        }
    }
    return $plaintext;
}

Avoid Opportunistic Upgrades

A common mistake some developers make is to try to do an “opportunistic” upgrade: Only perform the decrypt-then-re-encrypt routine on an as-needed basis. This is a disaster waiting to happen, and there is a lot of historical precedence to this.

Of particular note, Yahoo made this mistake, and as a result, had lots of MD5 password hashing lying around their database when they were breached, even though their active users had long since upgraded to bcrypt.

Detailed technical information about this new security feature, written by Paragon Initiative Enterprises (the cryptography team that developed it) are available here.

#5-2 #dev-notes

Site Health Check in 5.2

WordPress 5.2 will include two new pages in the admin interface to help end users to self-service their site through common configuration issues and other elements that go along with having a healthy online presence. It also provides a standardized location for developers to add debugging information.

The new pages can be found under the Tools menu, as Site Health, and presents the user with a fresh new admin interface. As we hope users will regularly ensure their site is up to standards, focus has been put on creating an interface you want to return to in the future.

Site Health Status

Screenshot of the WordPress Site Health Status page

The first page runs a series of tests on the user’s site, and will be categorized as critical, recommended, or good responses. These outcomes also affect the percentage of completion you have (where critical is weighted more heavily than recommended).

Each test result can be expanded to get an explanation of what you as a user should be paying attention to, and which problems are there if any, that need addressing.

Most of the bundled tests will also have actionable items, and provide links directly to the appropriate areas of your dashboard where you can improve upon the relevant settings.

Filtering the Tests

The tests are filterable via site_status_tests, meaning plugins or themes may add their own tests, or remove existing ones. We’ve also split these into two different types of tests: direct  and async. This was done as some tests may require more time to run, so to avoid potential timeouts within admin pages, any tests added to the async section will be run in succession via AJAX calls after the page is loaded.

Specifically of interest to server admins is the companion filter site_status_test_php_modules, which is based off the WordPress Hosting Team list of recommended and required PHP extensions.

Removing a Test

An example of a filter use would be a hosting provider that does automated updates. They may wish to remove the test for background updates being enabled or disabled as follows:

function myhost_remove_update_check( $tests ) {
	unset( $tests['async']['background_updates'] );
	return $tests;
}
add_filter( 'site_status_tests', 'myhost_remove_update_check' );

Adding a Test

This is an example of how a caching plugin might check to ensure that it’s cache setting is enabled.

function myplugin_add_caching_test( $tests ) {
	$tests['direct']['caching_plugin'] = array(
		'label' => __( 'My Caching Test' ),
		'test'  => 'myplugin_caching_test',
	);
	return $tests;
}
add_filter( 'site_status_tests', 'myplugin_add_caching_test' );

function myplugin_caching_test() {
	$result = array(
		'label'       => __( 'Caching is enabled' ),
		'status'      => 'good',
		'badge'       => array(
			'label' => __( 'Performance' ),
			'color' => 'orange',
		),
		'description' => sprintf(
			'<p>%s</p>',
			__( 'Caching can help load your site more quickly for visitors.' )
		),
		'actions'     => '',
		'test'        => 'caching_plugin',
	);

	if ( ! myplugin_caching_is_enabled() ) {
		$result['status'] = 'recommended';
		$result['label'] = __( 'Caching is not enabled' );
		$result['description'] = sprintf(
			'<p>%s</p>',
			__( 'Caching is not currently enabled on your site. Caching can help load your site more quickly for visitors.' )
		);
		$result['actions'] .= sprintf(
			'<p><a href="%s">%s</a></p>',
			esc_url( admin_url( 'admin.php?page=cachingplugin&action=enable-caching' ) ),
			__( 'Enable Caching' )
		);
	}

	return $result;
}

myplugin_add_caching_test() is hooked to the site_status_tests filter. It adds a new test called caching_plugin to the direct tests list. The value of test in this array is the function that will be called when the tests run on the Site Health Status page.

Note: If you add a test to the async test list, then you will also need to register the test function as an AJAX action using the wp_ajax_{$action} hook.

The test function should return an array with data about the result of the test. This array includes:

  • label: What the header of the section should say.
  • status: Section the result should be displayed in. Possible values are good, recommended, or critical.
  • badge: Array containing:
    • label: What the badge should say.
    • color: Applies a CSS class with this value to the badge. Core styles support blue, green, red, orange, purple and gray.
  • description: Additional details about the results of the test.
  • actions: A link or button to allow the end user to take action on the result.
  • test: The name of the test.

In the above example, the test function, myplugin_caching_test() sets an initial baseline value for the result, and then overrides portions as needed if the call to its internal function myplugin_caching_is_enabled() returns false.

Site Health Info

Screenshot of the WordPress Site Health Information page

The Information tab is meant for debug purposes. It provides a plethora of information about the website and server setup for sharing when looking for support in various locations, alongside a button to quickly copy any non-private information so you can easily paste this to others.

The page is split up into sections. Plugins and themes may introduce their own entries to this page using the debug_information filter, either by adding entries to existing sections, or by creating their own sections.

As mentioned, the copied information only includes non-private information, this can of course be subjective, and is therefore also included in the filter. Marking either a full section, or just individual entries as private can be done by setting the corresponding $private value to true.

For example, the database prefix is shown under the Database section, and is marked as private, so when I go to copy all the information, it’s not there:

Example of the database section of the Site Health Information page

The content that gets added to the clipboard for the entire Database section is shown below:

### Database ###

Extension: mysqli
Server version: 5.5.5-10.1.38-MariaDB-1~jessie
Client version: mysqlnd 5.0.12-dev - 20150407 - $Id: 7cc7cc96e675f6d72e5cf0f267f48e167c2abb23 $

A security plugin may for example think that any database information is always seen as private, and would filter this in the following way:

function secplugin_remove_database_info( $debug_info ) {
	$debug_info['wp-database']['private'] = true;
	return $debug_info;
}
add_filter( 'debug_information', 'secplugin_remove_database_info' );

Adding a new section may also be of interest. The example below adds your own plugin and its license key, but marks it as private, to the list:

function myplugin_add_debug_info( $debug_info ) {
	$debug_info['my-plugin-slug'] = array(
		'label'    => __( 'My Plugin', 'my-plugin-slug' ),
		'fields'   => array(
			'license' => array(
				'label'    => __( 'License', 'my-plugin-slug' ),
				'value'   => get_option( 'my-plugin-license', __( 'No license found', 'my-plugin-slug' ) ),
				'private' => true,
			),
		),
	);

	return $debug_info;
}
add_filter( 'debug_information', 'myplugin_add_debug_info' );

Each new section that’s added should use your plugin or theme slug to avoid name collisions. All core entries are prefixed with wp-.

All debug information is added in an unescaped manner, the Information page will run all data through wp_kses, and only allows a, strong, em and span tags (used for emphasis or linking to documentation).
Debug information is expected to be plain text, and is escaped before showing on the page. The displayed data is ran through esc_html(), and data that can be copied is ran through esc_attr().

#5-2, #dev-notes

Miscellaneous Developer Updates in 5.2

New wp_body_open Theme Hook

5.2 will introduce a new wp_body_open() function that is used to trigger a wp_body_open action. This action is intended to allow developers to inject code immediately following the opening <body> tag.

Themes are encouraged to begin using this hook as soon as 5.2 is released. The function should be placed just inside the opening <body> tag of the template file. For example:

<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

Usage of this hook should be reserved for output of unseen elements like <script> tags or additional metadata. It should not be used to add arbitrary HTML content to a page that could break layouts or lead to unexpected situations.

Backward Compatibility

In order to support previous versions of WordPress, it is recommended you use a shim in your theme to prevent fatal errors from the undefined function.

if ( ! function_exists( 'wp_body_open' ) ) {
    function wp_body_open() {
        do_action( 'wp_body_open' );
    }
}

Note that if your theme is going to be submitted to the theme repository, then you won’t be able to use the wp_ prefix, as it will get flagged by the Theme Check. An alternative is to call do_action directly where the wp_body_open() function is placed in the first example, like this:

<body <?php body_class(); ?>>
<?php 
if ( function_exists( 'wp_body_open' ) ) {
    wp_body_open();
} else {
    do_action( 'wp_body_open' );
}

Plugins can detect the use of this function in a theme by calling did_action( 'wp_body_open' ) and falling back to alternative methods if the action has not fired.

See #12563 and #46679 for more information.

Login Header Adjustments

The <h1> on wp-login.php previously used the title attribute inconsistently between multisite and single site. In multisite, the value of this attribute was the title of the network, but on a single site, it merely duplicated the link text. As part of #24766, many of the title attributes throughout core have been removed, as they are often redundant or useless.

In WordPress 5.2, this title attribute has been removed and its associated filter, login_headertitle, has been deprecated. If the deprecated filter is used, it now applies to the link text. A new login_headertext filter has been added in its place.

In addition to the <h1> changes, the link on the WordPress logo now always points to WordPress.org by default. In prior versions, it would point to the primary site of the network on multisite. This URL can still be filtered using login_headerurl.

See: #42537

Editor Image Caption Styles

In the block editor, the font-size and color attributes were removed from the figcaption element unless the active theme has opted into default block styles.

Additionally, a margin: 0; attribute applied to .block-editor-rich-text__editable was removed from the RichText component, so as to allow theme styles to control those margins without high specificity. If your plugin relied on this margin, you’ll need to add this back to the necessary elements.

See: wordpress/gutenberg/pull/14366

Walker_Category HTML Attributes

A new category_list_link_attributes filter has been added to Walker_Category to allow customization of the HTML attributes applied to a category list item’s anchor element.

This complements the page_menu_link_attributes filter in Walker_Page and the nav_menu_link_attributes filter in Walker_Nav_Menu.

See #40666

New Additional Content Filter on User Delete Action

When users are deleted from a site, WordPress checks to confirm that they do not have posts or links assigned to them. However, there are cases where a plugin may have content associated with them outside of a post_author or link_owner relationship.

WordPress 5.2 introduces a new users_have_additional_content filter, which allows plugins to run additional checks for custom content relationships.

Note: This filter specifically doesn’t override the system users_have_content checks to avoid any undesired suppression of the reassign functionality. Instead it enables the ability to flag that a user has additional content.

Developers should note that this filter doesn’t conduct the reassignment operations on the data, this will be done by the delete_user or deleted_user actions which provide the ID of the user as well as the ID of the user for reassignment if selected.

Using the Filter

Below is a simple example of how a plugin could use the filter along with the delete_user action to allow the re-assignment of non-standard content.

First the filter returns true to signify that users have additional content. This triggers the content reassignment UI to appear in the admin for all users being deleted.

It then uses the delete_user action hook to reassign additional content at the same time as any standard core content.

function myplugin_users_have_additional_content( $has_content, $user_ids ) {
	if ( ! $has_content ) {
		// Check if any of the the users being deleted have additional content
		if ( myplugin_check_users_have_content( $user_ids ) ) {
			return true;
		}
	}
	return $has_content;
}
add_filter( ‘users_have_additional_content’, ‘myplugin_users_have_additional_content’, 10, 2 );

function myplugin_reassign_user_content( $deleted_user, $reassigned_user ) {
	if ( $reassigned_user ) {
		// Re-assign the content from the deleted user
		myplugin_reassign_coauthor( $deleted_user, $reassigned_user );
	}
}
add_action( ‘delete_user’, ‘myplugin_reassign_user_content’, 10, 2 );

See: #36860

Other Updates of Note:

  • As part of the 2019 focus of improving automatic updates, the sodium_compat library will now be included in WordPress. Sodium Compat is a polyfill for the Sodium cryptography library for PHP versions <7.2. Including this will facilitate security enhancements, with the initial focus of enabling more secure signing and verification of update packages. See: #45806
  • Twemoji is now updated to version 12.0.1. See: #46805
  • Fixed a bug where an Allow header was not being returned for OPTIONS requests to the REST API. See: #45753
  • A $domain parameter has been added to translate_user_role(). This will allow translations of custom user roles added in plugins. See: #38736

#5-2, #dev-notes, #editor, #themes

Notable Accessibility Changes in 5.2

In addition to the semantic improvements to tabs in the admin area, there are a few additional accessibility changes developers should make note of in WordPress 5.2.

Post Formats in List Tables

When post formats were used prior to WordPress 5.2, icons representing the specific format were displayed beside the post title in the Posts list table. These icons served as links that filtered the list by the associated post format.

These icons have now been removed in favor of a dedicated dropdown select filter above the list table.

See: #35497, #46591

Admin Bar Submenu Link Markup

In the WordPress admin bar, menu items with nested items used arrow icons generated via CSS with a .ab-item:before pseudo element. Starting with WordPress 5.2 these arrow icons use a wrapper <span> element:

<span class="wp-admin-bar-arrow" aria-hidden="true"></span>

This change should only affect plugins that modify the admin bar using custom icons. Plugin authors are encouraged to use the new markup and adjust their plugin CSS accordingly.

This change is part of a broader effort—tracked in #40428—to progressively introduce best practices to make screen readers ignore CSS generated content when it’s not intended to be available for speech output.

See: #37513

Archive Widget Dropdown Improvements

To add consistency with the Categories Widget, and to improve contextual awareness for those using screen readers and other assistive technologies, WordPress 5.2 will now pre-select the currently viewed archive in the Archive Dropdown Widget.

This is handled through the addition of a new $selected boolean parameter in the get_archives_link() function. By default, $selected is set to true if the current page is the selected archive page. The new parameter is also available in the associated get_archives_link filter.

In addition, four new date-based parameters have been added to wp_get_archives(). By default, $year, $monthnum, $day, and $w are set to the their current date values, and are used to determine the value of $selected to pass to get_archives_link(), as noted above.

Developers utilizing wp_get_archives() may pass in different date values through these parameters to use as the comparison for the currently viewed archive page.

See: #40662

Other Changes of Note

  • A new media view, wp.media.view.Heading, was added to facilitate adding accessibility friendly headings to the media library/modal. This enables those using screen readers to quickly jump between sections of the interface. See #36925
  • Similarly, headings were added to the data tables on the Export Personal Data and Erase Personal Data pages. See #46041
  • Some minor adjustments have been made to the Alt text and URL fields in the media modals. The Alt text field is now the first field displayed, and it has an explanation below it to help educate on proper usage. The label for the “URL” field now says “Copy link” instead of “URL”. See #41612

#5-2, #accessibility, #dev-notes

Developer Focused Privacy Updates in 5.2

WordPress 5.2 brings several improvements for developers working with Privacy Policy pages and data exports.

New Privacy Policy Page Helpers

Four new features have been added to make customizing and designing the Privacy Policy page easier:

  • A new function, is_privacy_policy(), can be used in conditionals to identify whether the current $wp_query is for the Privacy Policy page.
  • A new theme template file, privacy-policy.php, is used for rendering the page assigned as the Privacy Policy.
  • .privacy-policy has been added as a body class and is inserted when the currently rendered page is the Privacy Policy page.
  • .menu-item-privacy-policy has been added as a menu item class to specify the menu link that points to the Privacy Policy page.

Backwards Compatibility

The only backwards compatibility concern with using these new helpers is with the is_privacy_policy() function, which would trigger a Call to undefined function fatal error.

Themes and plugins that would like to support the is_privacy_policy() function in older versions of WordPress can use the following shim:

if ( ! function_exists( 'is_privacy_policy' ) ) {
    function is_privacy_policy() {
        return get_option( 'wp_page_for_privacy_policy' ) && is_page( get_option( 'wp_page_for_privacy_policy' ) );
    }
}

For more information, see #44005.

Loosened Tag Restrictions in User Data Exports

User Data exports no longer use a hardcoded list of allowed tags, limited to just <a> and <br>. They will now use the default list of allowed tags in wp_kses().

Furthermore, the code facilitating the export now passes a personal_data_export context to wp_kses(), so that the allowed tags and attributes can be filtered using the wp_kses_allowed_html filter and checking for the personal_data_export context.

Here’s a filter example that adds support for the <sub> and <sup> tags to the personal data export:

function prefix_allowed_html_filter( $allowedtags, $context ) {
	// Only target personal data export.
	if ( 'personal_data_export' !== $context ) {
		return $allowedtags;
	}

	// Add support for the sub tag.
	if ( ! isset( $allowedtags['sub'] ) ) {
		$allowedtags['sub'] = array();
	}

	// Add support for the sup tag.
	if ( ! isset( $allowedtags['sup'] ) ) {
		$allowedtags['sup'] = array();
	}

	return $allowedtags;
}
add_filter( 'wp_kses_allowed_html', 'prefix_allowed_html_filter', 2, 10);

For more information, check out the documentation for the wp_kses_allowed_html filter.

See: #44044

#5-2, #core-privacy, #dev-notes, #privacy, #themes

Block Editor Detection Improvements in 5.2

In 5.0, WP_Screen::is_block_editor() was introduced to allow developers to conditionally execute code depending on whether the block editor is being loaded. This method returns the is_block_editor property of the WP_Screen instance. However, there were some large gaps in the loading process where an incorrect value could potentially be returned.

For example, when using the current_screen action hook, the value was always false, even when the user was visiting a block editor enabled screen. This happened because block editor support is flagged much later in the loading process when edit-form-blocks.php is included.

function myplugin_current_screen( $screen ) {
	if ( $screen->is_block_editor ) {
		// This conditional would never execute.
	}
}
add_action( 'current_screen', 'myplugin_current_screen' );

This has been fixed in 5.2 to account for all possible scenarios when a post is edited. However, there are still a few very narrow edge cases when a new post is created where WP_Screen::is_block_editor() may still incorrectly indicate block editor support.

Edge Cases When Creating New Posts

The use_block_editor_for_post() function and replace_editor filter require a WP_Post object to be passed as a parameter. Because a new post has not yet been created when WP_Screen is instantiated, it can only make its best guess whether the page is loading the block editor.

When creating a new post, WP_Screen will set is_block_editor property to the value returned by use_block_editor_for_post_type() for the current post type. In most cases, this guess will be correct. But, the following scenarios have edge cases to consider.

  • When the replace_editor filter is used to replace the editor, this value may be incorrect.
  • When the use_block_editor_for_post filter is used to change block editor support.

For both of these scenarios, the use_block_editor_for_post_type filter can be used to ensure the correct value in most circumstances.

function myplugin_replace_editor_filter( $replace_editor, $post ) {
	// Logic to replace editor.
}
add_filter( 'replace_editor', 'myplugin_replace_editor_filter', 10, 2 );

function myplugin_replace_editor_post_type( $use_block_editor, $post_type ) {
	// Similar logic to replace editor, but without a WP_Post object to work with.
}
add_filter( 'use_block_editor_for_post_type', 'myplugin_replace_editor_post_type', 10, 2 );

With this filter, all scenarios that do not require checking a specific property of a post (a taxonomy term, meta value, etc.) can be accounted for. For example, filtering based on user capability, site option, or user meta value for editor preference are all possible using use_block_editor_for_post_type.

When WordPress creates a new post, it uses the get_default_post_to_edit() function. This function creates a new post in the database using wp_insert_post() and then allows the default content, title, and excerpt to be filtered. When terms, post meta, or content are added to posts with actions such as save_post or wp_insert_post, it is possible that this could change the block editor support for the post being created.

This scenario would result in WP_Screen:is_block_editor possessing an incorrect value from the current_screen action until roughly the load-{$pagenow} action.

Logic should be added to the use_block_editor_for_post_type filter to account for these scenarios (which are normally post type specific) and guarantee the accuracy of WP_Screen::is_block_editor().

For more information on this, consult the ticket on Trac (#46195), or the changeset ([45224]).

#5-2, #block-editor, #dev-notes, #gutenberg

Fatal Error Recovery Mode in 5.2

WordPress 5.2 will allow administrators to fix or mitigate fatal errors on their site that would previously have been impossible to address without developer interference and modifying the codebase. Even in the case where a fatal error would commonly have made the backend completely inaccessible (for example through a so-called “white screen of death”), administrators will now still have the chance to log in and do something about the issue.

When a fatal error occurs, a user-facing error screen will display that informs the user/visitor that the site is experiencing technical difficulties. More importantly though, when such an error occurs, an email will be sent to the admin email address, informing about the issue and including a secret link to new feature called the “recovery mode”. Clicking this link will have the user enter this recovery mode, which works by placing a cookie on the current client.

When in recovery mode, plugins and themes (also referred to as “extensions”) which are causing a fatal error are paused for that client, ensuring they can work around these errors and access their admin backend as regularly. After entering recovery mode, the user needs to log in. It should be highlighted though that recovery mode itself is not tied to a specific user, but only to the cookie existing on the client.

After logging in, an admin notice will indicate that recovery mode is enabled. Furthermore, the user will be informed about which plugins/themes are currently paused due to fatal errors, and what exactly these errors are. They then have the possibility to address the issue in their preferred way:

  • They can completely deactivate the extension, e.g. when maintaining a working version of the site matters more than that extension’s functionality. This is typically a temporary solution, but provides an immediate resolution.
  • They can fix the problem if they have the technical capabilities, and afterwards resume the extension.
  • They can file a support ticket with the author of the respective extension or contact a developer, pointing out the exact error.

At any time, the user can decide to exit recovery mode, by clicking a button that permanently appears in the admin bar while in recovery mode. Exiting recovery mode will wipe the cookie from the client and thus cause all extensions to run as usual again. Keep in mind that if an extension is still broken, the fatal error will remain.

Admin backend while in recovery mode. Highlighted are the notice and the exit button in the admin bar, indicating recovery mode is active.
Admin backend while in recovery mode

The main benefit of recovery mode is to inform administrators about fatal errors on their site and allow them to still access their backend and decide what to do about the problem, rather than presenting them with the typical “white screen of death” which they cannot do anything about. It is impossible to automatically fix such errors, but recovery mode allows working around them by pausing the broken extensions. Pausing only happens for the client that is in recovery mode, and thus does not have any global implications. With a broken extension, only the user in recovery mode can access the broken areas; for the other users the site remains in a broken state until the issue has been fixed or mitigated.

Developers

There are a couple of ways that developers can integrate with the new recovery mode features:

  • Plugins that would like to enhance recovery mode can call a new function wp_is_recovery_mode() to check for whether it is active.
  • Environments can override the way that recovery mode is set up and validated if they prefer to use a different method or to purely enable it via code. A must-use plugin for example can set a constant WP_RECOVERY_MODE_SESSION_ID that needs to contain an arbitrary session ID, which will then be used to store recovery mode-specific data for that session. Having the constant available will force-enable recovery mode. However, this mechanism must be used with special care, as setting the constant unconditionally would result in recovery mode being globally enabled.
  • The template for the screen indicating that a fatal error occurred can be customized by using a php-error.php drop-in, similar to other previously existing drop-ins such as db-error.php.
  • The entire shutdown handler can be overridden by using a fatal-error-handler.php drop-in. This drop-in must return an instance of a class extending the default WP_Fatal_Error_Handler class. If that is the case, the instance will be used instead of the default one.
  • Environments that would like to disable the fatal error handler and recovery mode functionality altogether can do so by setting a WP_DISABLE_FATAL_ERROR_HANDLERconstant, typically in wp-config.php. The enabled status for the handler should be checked for by using a new function wp_is_fatal_error_handler_enabled().

Background

The fatal error recovery mode is a revised approach for what was originally the fatal error protection mechanism slated for WordPress 5.1, but then reverted due to some critical concerns. The client-specific recovery mode mitigates these concerns, so this time it is here to stay.

For further background information, please refer to the announcement post for the revised approach, the overarching Trac ticket, and generally the list of related 5.2 tickets.

#5-2, #dev-notes, #servehappy

Dashicons in WordPress 5.2

It’s been over 3 years since Dashicons has been updated (see #34221 from version 4.5). But, they have not been forgotten about! In 5.2, the Dashicons will see several changes, including 13 awesome new icons.

New Build Process

A new build process has been implemented in the Dashicons GitHub repository to make adding new icons easier. Now, when SVG files are added for new icons they are automatically included in the font and CSS files. This change will not be noticeable from the WordPress Core code base, but it’s worth noting.

New Font File Format: WOFF 2.0

This release will see the introduction of a new font file format, WOFF2 (Web Open Font Format 2). WOFF2 is a more modern replacement for the original WOFF 1.0 format that uses an improved compression, which results in lower network consumption.

WOFF2 is supported by all modern browsers, but is not supported in Internet Explorer.

WOFF 1.0 Format

The WOFF 1.0 file will remain in WordPress Core to ensure backwards compatibility for plugins and themes loading the wp-includes/fonts/dashicons.woff file directly. This file has not been updated to include the new icons below. The new build process currently only allows one WOFF format file to be built. Since WOFF2 is more modern, that is the file format being built moving forward.

However, WOFF 1.0 is compiled and included as an embedded font directly in the dashicons.css file. The embedded WOFF format has been updated to include the new icons. If you wish to use the new Dashicons and require the WOFF 1.0 format for IE support, it is recommended that you use the dashicons.css file included in core to define the Dashicons font face.

Alternatively, you can use the Embedded OpenType format file at wp-includes/fonts/dashicons.eot (supported by all versions of IE). This file does include the new icons.

New Icons

In 5.2, 13 completely new icons were added. However, 18 additional icons that were previously included in the font files but did not have a corresponding CSS declaration are now available. These icons are marked with an asterisk (*) below.

Buddicons

The Buddicons were all previously included in the icon font, but each is now accompanied by new a dashicons-buddicons-* class.

Icon CSS Class Code
dashicons-buddicons-activity * f452
dashicons-buddicons-bbpress-logo * f477
dashicons-buddicons-buddypress-logo * f448
dashicons-buddicons-community * f453
dashicons-buddicons-forums * f449
dashicons-buddicons-friends * f454
dashicons-buddicons-groups * f456
dashicons-buddicons-pm * f457
dashicons-buddicons-replies * f451
dashicons-buddicons-topics * f450
dashicons-buddicons-tracking * f455

Editor

Icon CSS Class Code
dashicons-editor-ol-rtl f12c
dashicons-editor-ltr f10c

Core Teams

Three new icons have been introduced for some newer teams: Tide, REST API, and Coding Standards.

Icon CSS Class Code
dashicons-tide f10d
dashicons-rest-api f124
dashicons-code-standards f13a

Sites

With the introduction of 3 new icons in 5.2, there are now 4 total site icons. No matter where you are located in the world, there is now an icon for you! (GH-95)

Icon CSS Class Code
dashicons-admin-site-alt f11d
dashicons-admin-site-alt2 f11e
dashicons-admin-site-alt3 f11f

Menus

Icon CSS Class Code
dashicons-menu-alt * f228
dashicons-menu-alt2 * f329
dashicons-menu-alt3 * f349

Social

Icon CSS Class Code
dashicons-instagram f12d

Miscellaneous

Icon CSS Class Code
dashicons-businesswoman f12f
dashicons-businessperson f12e
dashicons-email-alt2 f467
dashicons-yes-alt f12a
dashicons-camera-alt * f129
dashicons-plugins-checked * f485
dashicons-update-alt * f113
dashicons-text-page * f121

A very special thanks goes out to @joen, @empireoflight, @folletto, @netweb, @aduth, @dsifford, @SergioEstevao, @cathibosco1, @jaymanpandya, @oztaser, @ryelle, @joshuawold, @nateallen, @desrosj, @bahia0019, and @liljimmi for their contributions to Dashicons since the last update!

To get a complete overview of all icons please visit developer.wordpress.org/resource/dashicons/.

#5-2, #dashicons, #dev-notes, #ui

New Network and Sites Query Filters

WordPress 5.2 introduces new short circuit filters to WP_Site_Query and WP_Network_Query.

These two filters, sites_pre_query and network_pre_query, were introduced in [44983] and run before the database queries are executed. This enables short-circuiting the database query entirely to return custom results. Returning a non-null value from either filter will bypass WordPress’s default network and sites queries respectively (similar to the users_pre_query filter introduced in #44373).

Sites Query Filter

Developers should note that filtering functions that require pagination information are encouraged to set the found_sites property of the WP_Site_Query object (which is passed to the filter by reference). If WP_Site_Query does not perform a database query, it will not have enough information to generate these values itself.

Using the Filter

Below is a rough example of how a plugin can use the filter to replace the default behavior of WP_Site_Query with a call to a remote data store.

function myplugin_do_external_site_query( $sites, $site_query ) {
	$response = wp_remote_get( 'https://my-remote-data-store/foo/bar' );

	if ( 200 === wp_remote_response_code( $response ) ) {
		$response           = json_decode( wp_remote_retrieve_body( $response ) );
		$sites              = array_map( 'intval', $response->site_ids );
		$query->found_sites = (int) $response->found_sites;
	}

	return $sites;
}
add_filter( 'sites_pre_query', 'myplugin_do_external_site_query', 10, 2 );

Networks Query Filter

Developers should note that filtering functions that require pagination information are encouraged to set the total_networks property of the WP_Network_Query object (which is passed to the filter by reference). If WP_Network_Query does not perform a database query, it will not have enough information to generate these values itself.

Using the Filter

Below is a rough example of how a plugin can use the filter to replace the default behavior of WP_Network_Query with a call to a remote data store.

function myplugin_do_external_network_query( $networks, $network_query ) {
	$response = wp_remote_get( 'https://my-remote-data-store/foo/bar' );

	if ( 200 === wp_remote_response_code( $response ) ) {
		$response              = json_decode( wp_remote_retrieve_body( $response ) );
		$networks              = array_map( 'intval', $response->network_ids );
		$query->total_networks = (int) $response->total_networks;
	}

	return $networks;
}
add_filter( 'network_pre_query', 'myplugin_do_external_network_query', 10, 2 );

Other Similar Query Filters

Similar filters for WP_User_Query and count_users() were added in WordPress 5.1.

Several additional filters for similar query objects are currently being explored and worked on, and are currently slated for a future release:

  • A short circuit for WP_Comment_Query (#45800).
  • A short circuit for WP_Term_Query with a plan to add a terms_pre_query filter (#41246).

Why Add These Filters?

These query pre-filters enable plugins to use an alternate database store for queries, for example returning results from an external service such as an Elasticsearch server. The process started with the main post query, and these are now being expanded that to other queries in WordPress.

#5-2, #dev-notes, #multisite, #networks-sites

The Block Editor JavaScript module in 5.2

One of the goals of the Gutenberg project’s phase 2 is to expand the usage of the Block Editor to other WordPress admin pages like the widgets screen.

In order to achieve this goal, it’s important to be able to reuse the block editor in a context independent from the post editor without any dependency to the post object. That’s where the new block-editor module comes in.

Reorganization

In WordPress 5.1 and earlier, the block editor relied on the editor JavaScript module in order to fetch the post being edited and render the block editor corresponding to this post. This module is available as a registered WordPress script using the wp-editor script and style handles and under the wp.editor global variable.

WordPress 5.2 extracts some parts of the editor module into a new module called block-editor. This module is now available as a registered WordPress script using the wp-block-editor script and style handles and under the wp.blockEditor global variable.

Important distinctions about the new block-editor module:

  • The editor module is kept, but is only responsible for fetching/updating post objects, and rendering post specific UI components.
  • The block editor module is a generic module responsible for rendering block editor UI, updating the list of blocks, and providing reusable components for third-party blocks.

Backward Compatibility

There’s no backward compatibility breakage involved in this reorganization, as usage of the editor module provides proxies for APIs that were moved to the block-editor module in WordPress 5.2.

For example, in WordPress 5.1, blocks had to use the wp.editor.BlockAlignment component to support alignment. This component will continue to work as expected, but wp.editor.BlockAlignmentToolbar is now just a proxy to the block editor component wp.blockEditor.BlockAlignmentToolbar.

However, relying on the editor module as a dependency means that your block/code is loading the full editor module, which might not be needed for the block editor that will be included in the widgets screen in the future.

For this reason, it’s recommended that you make your blocks independent from the editor module and any post object. Instead of relying on the editor module proxies, you are encouraged you to your code to target the block-editor APIs instead.

This involves:

  • Using wp-block-editor instead of wp-editor as script and style dependencies for your WordPress registered/enqueued scripts and styles.
  • Using the wp.blockEditor.* components instead of wp.editor.* ones.
  • Using the core/block-editor data module selectors and actions instead of the core/editor ones.

Components and Higher-Order Components Moved to block-editor

This is the exhaustive list of the components and higher-order components that were moved to the block-editor module.

  • Autocomplete
  • AlignmentToolbar
  • BlockAlignmentToolbar
  • BlockControls
  • BlockEdit
  • BlockEditorKeyboardShortcuts
  • BlockFormatControls
  • BlockIcon
  • BlockInspector
  • BlockList
  • BlockMover
  • BlockNavigationDropdown
  • BlockSelectionClearer
  • BlockSettingsMenu
  • BlockTitle
  • BlockToolbar
  • ColorPalette
  • ContrastChecker
  • CopyHandler
  • createCustomColorsHOC
  • DefaultBlockAppender
  • FontSizePicker
  • getColorClassName
  • getColorObjectByAttributeValues
  • getColorObjectByColorValue
  • getFontSize
  • getFontSizeClass
  • Inserter
  • InnerBlocks
  • InspectorAdvancedControls
  • InspectorControls
  • PanelColorSettings
  • PlainText
  • RichText
  • RichTextShortcut
  • RichTextToolbarButton
  • RichTextInserterItem
  • UnstableRichTextInputEvent
  • MediaPlaceholder
  • MediaUpload
  • MediaUploadCheck
  • MultiBlocksSwitcher
  • MultiSelectScrollIntoView
  • NavigableToolbar
  • ObserveTyping
  • PreserveScrollInReorder
  • SkipToSelectedBlock
  • URLInput
  • URLInputButton
  • URLPopover
  • Warning
  • WritingFlow
  • withColorContext
  • withColors
  • withFontSizes

Selectors Moved to block-editor

This is the exhaustive list of the data module selectors that moved to the core/block-editor store.

  • canInsertBlockType
  • getAdjacentBlockClientId
  • getBlock
  • getBlockAttributes
  • getBlockCount
  • getBlockDependantsCacheBust
  • getBlockHierarchyRootClientId
  • getBlockIndex
  • getBlockMode
  • getBlockName
  • getBlockOrder
  • getBlockRootClientId
  • getBlockInsertionPoint
  • getBlockListSettings
  • getBlocks
  • getBlocksByClientId
  • getBlockSelectionStart
  • getBlockSelectionEnd
  • getClientIdsOfDescendants
  • getClientIdsWithDescendants
  • getFirstMultiSelectedBlockClientId
  • getGlobalBlockCount
  • getInserterItems
  • getLastMultiSelectedBlockClientId
  • getMultiSelectedBlockClientIds
  • getMultiSelectedBlocks
  • getMultiSelectedBlocksEndClientId
  • getMultiSelectedBlocksStartClientId
  • getNextBlockClientId
  • getPreviousBlockClientId
  • getSelectedBlockCount
  • getSelectedBlockClientId
  • getSelectedBlock
  • getSelectedBlocksInitialCaretPosition
  • getTemplate
  • getTemplateLock
  • hasInserterItems
  • hasMultiSelection
  • hasSelectedBlock
  • hasSelectedInnerBlock
  • isAncestorMultiSelected
  • isBlockInsertionPointVisible
  • isBlockMultiSelected
  • isBlockSelected
  • isBlockValid
  • isBlockWithinSelection
  • isCaretWithinFormattedText
  • isFirstMultiSelectedBlock
  • isMultiSelecting
  • isSelectionEnabled
  • isTyping
  • isValidTemplate

Actions Moved to block-editor

This is the exhaustive list of the data module actions that moved to the core/block-editor store.

  • clearSelectedBlock
  • enterFormattedText
  • exitFormattedText
  • hideInsertionPoint
  • insertBlock
  • insertBlocks
  • insertDefaultBlock
  • mergeBlocks
  • moveBlocksDown
  • moveBlocksUp
  • moveBlockToPosition
  • multiSelect
  • receiveBlocks
  • removeBlock
  • removeBlocks
  • replaceBlocks
  • resetBlocks
  • selectBlock
  • setTemplateValidity
  • showInsertionPoint
  • startMultiSelect
  • startTyping
  • stopMultiSelect
  • stopTyping
  • synchronizeTemplate
  • toggleBlockMode
  • toggleSelection
  • updateBlock
  • updateBlockAttributes
  • updateBlockListSettings

Styles and Class Names

The components that moved from the editor module to the block-editor module are internally using CSS class names that follow the package they’re declared in.

For example, the editor-inserter__toggle class name is now renamed block-editor-inserter__toggle.

The old class names have been retained to minimize any backward compatibility concern, but the CSS styles are now targeting the new class names.

Ideally, you should rely on components in your own code instead of the internal class names used in the WordPress admin. But if you do use those classes, make sure to rename them accordingly.

#5-2, #dev-notes, #gutenberg