General: Introduce `WP_DEVELOPMENT_MODE` constant to signify context-specific development mode.

In recent releases, WordPress core added several instances of cache usage around specific files. While those caches are safe to use in a production context, in development certain nuances apply for whether or not those caches make sense to use. Initially, `WP_DEBUG` was used as a temporary workaround, but it was clear that a more granular method to signify a specific development mode was required: For example, caches around `theme.json` should be disabled when working on a theme as otherwise it would disrupt the theme developer's workflow, but when working on a plugin or WordPress core, this consideration does not apply.

This changeset introduces a `WP_DEVELOPMENT_MODE` constant which, for now, can be set to either "core", "plugin", "theme", or an empty string, the latter of which means no development mode, which is also the default. A new function `wp_get_development_mode()` is the recommended way to retrieve that configuration value.

With the new function available, this changeset replaces all existing instances of the aforementioned `WP_DEBUG` workaround to use `wp_get_development_mode()` with a more specific check.

Props azaozz, sergeybiryukov, peterwilsoncc, spacedmonkey.
Fixes #57487.

Built from https://develop.svn.wordpress.org/trunk@56042


git-svn-id: http://core.svn.wordpress.org/trunk@55554 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/default-constants.php

@@ -77,9 +77,18 @@ function wp_initial_constants() {
 		define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' ); // No trailing slash, full paths only - WP_CONTENT_URL is defined further down.
 	}
 
+	/*
+	 * Add define( 'WP_DEVELOPMENT_MODE', 'core' ) or define( 'WP_DEVELOPMENT_MODE', 'plugin' ) or
+	 * define( 'WP_DEVELOPMENT_MODE', 'theme' ) to wp-config.php to signify development mode for WordPress core, a
+	 * plugin, or a theme respectively.
+	 */
+	if ( ! defined( 'WP_DEVELOPMENT_MODE' ) ) {
+		define( 'WP_DEVELOPMENT_MODE', '' );
+	}
+
 	// Add define( 'WP_DEBUG', true ); to wp-config.php to enable display of notices during development.
 	if ( ! defined( 'WP_DEBUG' ) ) {
-		if ( 'development' === wp_get_environment_type() ) {
+		if ( wp_get_development_mode() || 'development' === wp_get_environment_type() ) {
 			define( 'WP_DEBUG', true );
 		} else {
 			define( 'WP_DEBUG', false );

wp-includes/global-styles-and-settings.php

@@ -66,12 +66,10 @@ function wp_get_global_settings( $path = array(), $context = array() ) {
 	$cache_key   = 'wp_get_global_settings_' . $origin;
 
 	/*
-	 * Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
+	 * Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
 	 * developer's workflow.
-	 *
-	 * @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
 	 */
-	$can_use_cached = ! WP_DEBUG;
+	$can_use_cached = wp_get_development_mode() !== 'theme';
 
 	$settings = false;
 	if ( $can_use_cached ) {
@@ -151,12 +149,10 @@ function wp_get_global_styles( $path = array(), $context = array() ) {
  */
 function wp_get_global_stylesheet( $types = array() ) {
 	/*
-	 * Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
+	 * Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
 	 * developer's workflow.
-	 *
-	 * @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
 	 */
-	$can_use_cached = empty( $types ) && ! WP_DEBUG;
+	$can_use_cached = empty( $types ) && wp_get_development_mode() !== 'theme';
 
 	/*
 	 * By using the 'theme_json' group, this data is marked to be non-persistent across requests.
@@ -252,12 +248,10 @@ function wp_get_global_styles_custom_css() {
 		return '';
 	}
 	/*
-	 * Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
+	 * Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
 	 * developer's workflow.
-	 *
-	 * @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
 	 */
-	$can_use_cached = ! WP_DEBUG;
+	$can_use_cached = wp_get_development_mode() !== 'theme';
 
 	/*
 	 * By using the 'theme_json' group, this data is marked to be non-persistent across requests.
@@ -303,12 +297,10 @@ function wp_get_global_styles_custom_css() {
  */
 function wp_get_global_styles_svg_filters() {
 	/*
-	 * Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
+	 * Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
 	 * developer's workflow.
-	 *
-	 * @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
 	 */
-	$can_use_cached = ! WP_DEBUG;
+	$can_use_cached = wp_get_development_mode() !== 'theme';
 	$cache_group    = 'theme_json';
 	$cache_key      = 'wp_get_global_styles_svg_filters';
 	if ( $can_use_cached ) {
@@ -402,12 +394,10 @@ function wp_theme_has_theme_json() {
 	if (
 		null !== $theme_has_support &&
 		/*
-		 * Ignore static cache when `WP_DEBUG` is enabled. Why? To avoid interfering with
+		 * Ignore static cache when the development mode is set to 'theme', to avoid interfering with
 		 * the theme developer's workflow.
-		 *
-		 * @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
 		 */
-		! WP_DEBUG &&
+		wp_get_development_mode() !== 'theme' &&
 		/*
 		 * Ignore cache when automated test suites are running. Why? To ensure
 		 * the static cache is reset between each test.

wp-includes/load.php

@@ -261,6 +261,50 @@ function wp_get_environment_type() {
 	return $current_env;
 }
 
+/**
+ * Retrieves the current development mode.
+ *
+ * The development mode affects how certain parts of the WordPress application behave, which is relevant when
+ * developing for WordPress.
+ *
+ * Valid developer modes are 'core', 'plugin', 'theme', or an empty string to disable developer mode.
+ *
+ * Developer mode is considered separately from `WP_DEBUG` and {@see wp_get_environment_type()}. It does not affect
+ * debugging output, but rather functional nuances in WordPress.
+ *
+ * @since 6.3.0
+ *
+ * @return string The current development mode.
+ */
+function wp_get_development_mode() {
+	static $current_mode = null;
+
+	if ( ! defined( 'WP_RUN_CORE_TESTS' ) && null !== $current_mode ) {
+		return $current_mode;
+	}
+
+	$development_mode = WP_DEVELOPMENT_MODE;
+
+	// Exclusively for core tests, rely on a global `$_wp_tests_development_mode`.
+	if ( defined( 'WP_RUN_CORE_TESTS' ) && isset( $GLOBALS['_wp_tests_development_mode'] ) ) {
+		$development_mode = $GLOBALS['_wp_tests_development_mode'];
+	}
+
+	$valid_modes = array(
+		'core',
+		'plugin',
+		'theme',
+		'',
+	);
+	if ( ! in_array( $development_mode, $valid_modes, true ) ) {
+		$development_mode = '';
+	}
+
+	$current_mode = $development_mode;
+
+	return $current_mode;
+}
+
 /**
  * Don't load all of WordPress when handling a favicon.ico request.
  *

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.3-alpha-56041';
+$wp_version = '6.3-alpha-56042';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.