Codebase language improvements in 5.5

Edit: 7/23/2020: A note was added to make developers aware that one of the option keys renamed prior to betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1 was renamed again after beta 3 to avoid confusion with the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. – @desrosj

In version 5.5, WordPress will see several changes aimed at maintaining a welcoming environment for all contributors while improving the clarity and inclusivity of the codebase. This is a separate but related effort to a recent proposal to update the default branches for all of the project’s GIT repositories.

The WordPress open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. community cares about diversity. We strive to maintain a welcoming environment where everyone can feel included, by keeping communication free of discrimination, incitement to violence, promotion of hate, and unwelcoming behavior.

WordPress Etiquette

“Whitelist” and “Blacklist”

Whitelist and blacklist are terms that specify allowed and disallowed or blocked things. However, many times when these two words are used, what is being allowed or blocked is not clear. This ambiguity can make for poor readability, and can also make it harder for non-native English speakers to understand the purpose of the variable, or how to properly translate a string.

In WordPress 5.5, these words have been removed from CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and only remain where absolutely necessary for backwards compatibility. A large percentage of the occurrences existed within inline documentation and the names of locally scoped variable, but a few instances were found in function names, option keys, action/filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., and global variables.

While most of the changes made do not require any action to be taken, a few may need some small adjustments to plugins, themes, or custom code.

Here is what you need to know!

Renamed Options

The following options have been renamed:

  • blacklist_keys has been renamed to disallowed_keys.
  • comment_whitelist has been renamed to comment_previously_approved.

Upon upgrading to WordPress 5.5, these options will be renamed as part of the normal upgrade process and no action is required.

However, when using the Options APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. (add_option(), delete_option(), update_option(), get_option()), specifying one of the deprecated options will trigger a deprecated warning but the value for the new option name will be correctly returned.

Example

These two examples will return the same values.

$option_value = get_option( 'disallowed_keys' );

// This produces the same result, but will also trigger a deprecated warning.
$option_value = get_option( 'blacklist_keys' );

Any Options API function calls should be adjusted to look for the new option name whenever possible. For code that still needs to support support WordPress < 5.5, the following snippet will do the trick:

if ( false === get_option( 'disallowed_keys' ) ) {
    // Assume this is WP < 5.5. Option does not exist.
} else {
    // Assume this is WP >= 5.5
}

If disallowed_keys exists in the database, the stored value will be returned (which is an empty string by default, or a space separated list of keys and/or IP addresses). get_option() will return explicit false by default, which is a good indicator that the option does not exist.

There are a few things to be aware of, though.

  • Options API related filters associated with deprecated option keys will not be triggered. For example, the pre_option_blacklist_keys filter. Some basic text searches of the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party directory found that the usage of any Options API hooks specific to the two changed option keys was almost none.
  • Direct Cache API calls for these options will not be reliable. For example, wp_cache_get( 'blacklist_keys', 'options ). Instead of accessing the option directly from the Cache API, get_option() should be used instead.
  • Queries directly modifying, updating, retrieving these options form the database will potentially cause issues. This is incorrect usage and the Options API functions should always be used instead.
  • Prior to 5.5 beta 1, blacklist_keys was renamed to blocklist_keys. However, to avoid any potential confusion with block editor related features or functionality, it was renamed to disallowed_keys after 5.5 beta 3. This will be fixed automatically when updating to the next development version or installing 5.5, but any code that was changed to use blocklist_keys will need to be updated once more.

In 5.6, adding a more proper _deprecate_option() will be explored to handle future occurrences like this.

For more information, see #50413 on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress..

Deprecated functions

The following functions have been deprecated in 5.5. Though this should not cause any problems in your code, the following functions will now trigger a _deprecated_function() warning:

  • add_option_whitelist() has been replaced with add_allowed_options().
  • remove_option_whitelist() has been replaced with remove_allowed_options().
  • wp_blacklist_check() has been replaced with wp_check_comment_disallowed_list().
  • _wp_register_meta_args_whitelist() has been replaced with _wp_register_meta_args_allowed_list() (this is a private function, so should not be used outside of Core).
  • wp.passwordStrength.userInputBlacklist() was replaced with wp.passwordStrength.userInputDisallowedList() (JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.)

For more information, see #50413 on Trac.

Deprecated actions and filters

The following action and filter hooks have been deprecated in 5.5. Any code hooked to them will still be executed. However, a deprecated warning will now be triggered. The replacement hooks will run after the deprecated hooks.

  • The whitelist_options filter hook has been replaced with allowed_options.
  • The wp_blacklist_check action hook has been replaced with wp_check_comment_disallowed_list.

For more information, see #50413 on Trac.

Deprecated global Variables

  • $whitelist_options has been replaced with $allowed_options.
  • $new_whitelist_options has been replaced with $new_allowed_options (more information below)

A scan of the plugin directory showed that only 2 plugins are explicitly accessing the $whitelist_options global and performing no modifications.

A second scan of the plugin directory showed a small number of plugins with a low amount of active installs potentially manipulating the value of $new_whitelist_options. However, it was enough to require consideration.

Because of this, the new $new_allowed_options variable is now passed by reference to the old $new_whitelist_options variable.

Unless a plugin is intentionally destroying this global variable and recreating it from scratch, this will create a seamless transition to a more inclusive name until a standardized way to deprecate a global variable can be created (such as _deprecate_global()), or the implementation can be revised to not require a global variable at all.

For more information on this change, see #50434 and #50413 on Trac.

“Webmaster”

In addition to potentially having racist undertones, the word “webmaster” has become dated and quite cryptic. One person managing all aspects of a site is, for the most part, no longer the norm. The term has also become ambiguous, potentially referring to anyone fulfilling any of the following duties involved with managing a website: web architects, web developers, site authors, website administrators, website owners, etc..

The two occurrences of this string have been replaced with alternatives that better communicate who is being referenced.

See #50394 on Trac for more information.

Props @cbringmann and @jorbin for pre-publishing review.

#5-5, #dev-notes