New wp_get_environment_type() function in WordPress 5.5

Edit: 7/28/2020: Previously, this feature included filters to modify the environment type and available environment types. These were removed in [48662] as the function is called too early for any plugins to properly hook into these filters. This post was updated to remove mention of those filters appropriately.

WordPress 5.5 introduces a new wp_get_environment_type() function that retrieves a site’s current environment type. This allows 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 and theme authors to more easily differentiate how they handle specific functionality between production and development sites in a standardized way.

By default, this function will return production. Other values supported by default are development and staging.

Below is an example of how this new function can be used to determine a site’s environment type.

switch ( wp_get_environment_type() ) {
    case 'development':
        do_nothing();
        break;
    
    case 'staging':
        do_staging_thing();
        break;
    
    default:
        do_production_thing();
        break;
}

Of course care should be taken with this kind of functionality to test all the possible routes. Keep in mind that site owners and hosts are are always free to add more types as necessary.

Setting the environment type

There are two ways to set the environment type for a site. They are processed in the following order with each sequential option overriding any previous values: the WP_ENVIRONMENT_TYPE PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 environment variable, and the WP_ENVIRONMENT_TYPE constant.

For both of them, if the environment value is not in the list of allowed environments, the default production value will be returned.

The simplest way is probably through defining the constant:

define( 'WP_ENVIRONMENT_TYPE', 'staging' );

Note: When development is returned by wp_get_environment_type(), WP_DEBUG will be set to true if it is not defined in the site’s wp-config.php file.

Specifying approved environment types

Similar to setting the environment type, there are two ways to specify approved environment types. They are processed in the same similar manner as setting the type above with each sequential option overriding any previous values: the WP_ENVIRONMENT_TYPES PHP environment variable, and the WP_ENVIRONMENT_TYPES constant.

Assume a site wishes to support a test environment type. Below is an example of defining the constant:

define(
    'WP_ENVIRONMENT_TYPES',
    array(
        'production',
        'staging',
        'development',
        'test',
    )
);

Request to all hosts and development environments

All hosts that support setting up staging environments are requested to set this feature to staging on those staging environments. Similarly we ask all developers with development environments to set this value to development appropriately.

Plugin and theme developers should also add support for this feature and adjust functionality appropriately based on the specified environment.


For reference, see the related ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.: #33161

Props @desrosj, @audrasjb, and @sergeybiryukov for reviewing.

#5-5, #dev-notes