Felix Arntz 5:18 pm on July 14, 2023
Tags: , ,   

Configuring development mode in 6.3

WordPress 6.3 introduces a new concept called “development mode”, which affects certain nuances in how WordPress behaves. Going forward, sites will be able to configure their development mode using a new WP_DEVELOPMENT_MODE constant, which is recommended for any development sites.

What is the development mode?

The development mode configured on a site defines the kind of development work that the site is being used for. 

Possible values for WP_DEVELOPMENT_MODE are:

  • “coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.” indicates that this site is used as a WordPress core development environment. For example, this may be relevant when you are contributing directly to WordPress core.
  • “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” indicates that this site is used as a WordPress plugin development environment. For example, this may be relevant when you are working on a plugin for the plugin repository.
  • “theme” indicates that this site is used as a WordPress theme development environment. For example, this may be relevant when you are working on a theme for the theme repository.
  • “all” indicates that this site is used as a WordPress development environment where all three aspects may be modified. For example, this may be relevant when you are working on a specific site as a whole, e.g. for a client.
  • An empty string indicates that no particular development mode is enabled for this site. This is the default value and should be used on any site that is not used for development.

Per this definition, setting a development mode is only relevant for sites where any kind of development is occurring. For example, it is not advised or relevant to use on a production siteProduction Site A production site is a live site online meant to be viewed by your visitors, as opposed to a site that is staged for development or testing..

What specifically does the development mode do?

There are currently only a few use-cases in WordPress core which are determined by the development mode, but this will likely increase in the future. Most usage today relates to theme.json caching.

It is also a great example for the kind of nuance that the development mode of a site affects:

  • On most sites, caching certain data from theme.json is reliable since that data would only be invalidated when the theme is updated.
  • However, if you are actively developing a theme on the site and modifying theme.json constantly, having to manually invalidate the cache all the time would be detrimental to the development workflow. Therefore, that specific caching functionality is bypassed if the development mode is set to “theme”.
  • On the flipside, if you are directly contributing to WordPress core (i.e. setting your development mode to “core”), your site should behave as close to the actual behavior as possible, so even though you are in a development environment as well, having the theme.json data cache bypassed would not represent the actual behavior intended for a regular WordPress site.
  • That is why that specific caching functionality is only bypassed during theme development, but not during core development.

Difference between development mode, environment type, and debug mode

WordPress already contains two seemingly related concepts, which are the environment type (WP_ENVIRONMENT_TYPE constant) and debug mode (WP_DEBUG constant). Here is how they differ:

  • WP_DEBUG (boolean) toggles general debugging mode, which results in additional notices being displayed or logged.
  • WP_ENVIRONMENT_TYPE (string) defines whether the site is a local, development, staging, or production environment. This value can be used to set defaults for other configuration parameters or toggle certain features on the site.
  • WP_DEVELOPMENT_MODE (string) defines a specific scope of development that applies to the current site, which results in certain low-level WordPress behavior to change. This is different from WP_DEBUG which does not affect actual behavior. Additionally, WP_DEBUG typically applies to any development environment, while WP_DEVELOPMENT_MODE is more specific, as explained in the aforementioned example.

It is likely that you will only use the WP_DEVELOPMENT_MODE constant on a site where WP_DEBUG is enabled and WP_ENVIRONMENT_TYPE is either “development” or “local”, since it is not advised for development to occur directly against staging or production environments. That said, the constant is still decoupled, also because it defines the kind of development that is occurring more granularly than a simple on/off switch like WP_DEBUG.

Setting the development mode for a site

To set the development mode for a site, simply add a definition of the WP_DEVELOPMENT_MODE constant to your wp-config.php file. For example, if your site is a development environment for your plugin:

define( 'WP_DEVELOPMENT_MODE', 'plugin' );

Most likely, in this case you also want to make sure you have WP_DEBUG enabled and WP_ENVIRONMENT_TYPE set to “development” or “local”.

Checking the development mode for a site

A new function wp_is_development_mode( $mode ) is the recommended way to check whether a given development mode is enabled for the WordPress site. The function expects you to pass a $mode parameter that you would like to check for (e.g. “core”, “plugin”, or “theme”) and returns a boolean for whether said mode is enabled.

Per the aforementioned list of possible values, if a site has WP_DEVELOPMENT_MODE set to “all”, the function will return true for any $mode passed.

Here is an example:

if ( wp_is_development_mode( 'theme' ) ) {
	/*
	 * This could contain some logic that only applies when developing a theme
	 * on the site.
	 */
}

Additionally to wp_is_development_mode( $mode ), another lower-level function wp_get_development_mode() has also been added in WordPress 6.3, which returns the value of the WP_DEVELOPMENT_MODE constant directly. However, accessing the constant value directly is discouraged. Due to special values such as “all” that can encompass multiple other development modes, it is advised to always use wp_is_development_mode( $mode ) instead.

If you are logged into the WP Adminadmin (and super admin) interface, you can access the current value of the WP_DEVELOPMENT_MODE constant under Tools > Site Health > Info, in the WordPress Constants section.

See #57487 for additional context on this change.

Props @peterwilsoncc for technical review, @stevenlinx for proofreading.

Update July 17, 2023: The function wp_in_development_mode() was renamed to wp_is_development_mode() after initial publication of this article (see [56249]). All references have been updated.

#6-3, #dev-notes, #dev-notes6-3