Skip to content

Commit 4a16702

Browse files
felixarntzfelixarntz
committed
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. git-svn-id: https://develop.svn.wordpress.org/trunk@56042 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 88de9a9 commit 4a16702

8 files changed

Lines changed: 160 additions & 21 deletions

File tree

‎.env‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ LOCAL_WP_DEBUG_LOG=true
5959
LOCAL_WP_DEBUG_DISPLAY=true
6060
LOCAL_SCRIPT_DEBUG=true
6161
LOCAL_WP_ENVIRONMENT_TYPE=local
62+
LOCAL_WP_DEVELOPMENT_MODE=core
6263

6364
# The URL to use when running e2e tests.
6465
WP_BASE_URL=http://localhost:${LOCAL_PORT}

‎src/wp-includes/default-constants.php‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,18 @@ function wp_initial_constants() {
7777
define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' ); // No trailing slash, full paths only - WP_CONTENT_URL is defined further down.
7878
}
7979

80+
/*
81+
* Add define( 'WP_DEVELOPMENT_MODE', 'core' ) or define( 'WP_DEVELOPMENT_MODE', 'plugin' ) or
82+
* define( 'WP_DEVELOPMENT_MODE', 'theme' ) to wp-config.php to signify development mode for WordPress core, a
83+
* plugin, or a theme respectively.
84+
*/
85+
if ( ! defined( 'WP_DEVELOPMENT_MODE' ) ) {
86+
define( 'WP_DEVELOPMENT_MODE', '' );
87+
}
88+
8089
// Add define( 'WP_DEBUG', true ); to wp-config.php to enable display of notices during development.
8190
if ( ! defined( 'WP_DEBUG' ) ) {
82-
if ( 'development' === wp_get_environment_type() ) {
91+
if ( wp_get_development_mode() || 'development' === wp_get_environment_type() ) {
8392
define( 'WP_DEBUG', true );
8493
} else {
8594
define( 'WP_DEBUG', false );

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

Lines changed: 10 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -66,12 +66,10 @@ function wp_get_global_settings( $path = array(), $context = array() ) {
6666
$cache_key = 'wp_get_global_settings_' . $origin;
6767

6868
/*
69-
* Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
69+
* Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
7070
* developer's workflow.
71-
*
72-
* @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
7371
*/
74-
$can_use_cached = ! WP_DEBUG;
72+
$can_use_cached = wp_get_development_mode() !== 'theme';
7573

7674
$settings = false;
7775
if ( $can_use_cached ) {
@@ -151,12 +149,10 @@ function wp_get_global_styles( $path = array(), $context = array() ) {
151149
*/
152150
function wp_get_global_stylesheet( $types = array() ) {
153151
/*
154-
* Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
152+
* Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
155153
* developer's workflow.
156-
*
157-
* @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
158154
*/
159-
$can_use_cached = empty( $types ) && ! WP_DEBUG;
155+
$can_use_cached = empty( $types ) && wp_get_development_mode() !== 'theme';
160156

161157
/*
162158
* 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() {
252248
return '';
253249
}
254250
/*
255-
* Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
251+
* Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
256252
* developer's workflow.
257-
*
258-
* @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
259253
*/
260-
$can_use_cached = ! WP_DEBUG;
254+
$can_use_cached = wp_get_development_mode() !== 'theme';
261255

262256
/*
263257
* 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() {
303297
*/
304298
function wp_get_global_styles_svg_filters() {
305299
/*
306-
* Ignore cache when `WP_DEBUG` is enabled, so it doesn't interfere with the theme
300+
* Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
307301
* developer's workflow.
308-
*
309-
* @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
310302
*/
311-
$can_use_cached = ! WP_DEBUG;
303+
$can_use_cached = wp_get_development_mode() !== 'theme';
312304
$cache_group = 'theme_json';
313305
$cache_key = 'wp_get_global_styles_svg_filters';
314306
if ( $can_use_cached ) {
@@ -402,12 +394,10 @@ function wp_theme_has_theme_json() {
402394
if (
403395
null !== $theme_has_support &&
404396
/*
405-
* Ignore static cache when `WP_DEBUG` is enabled. Why? To avoid interfering with
397+
* Ignore static cache when the development mode is set to 'theme', to avoid interfering with
406398
* the theme developer's workflow.
407-
*
408-
* @todo Replace `WP_DEBUG` once an "in development mode" check is available in Core.
409399
*/
410-
! WP_DEBUG &&
400+
wp_get_development_mode() !== 'theme' &&
411401
/*
412402
* Ignore cache when automated test suites are running. Why? To ensure
413403
* the static cache is reset between each test.

‎src/wp-includes/load.php‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,50 @@ function wp_get_environment_type() {
261261
return $current_env;
262262
}
263263

264+
/**
265+
* Retrieves the current development mode.
266+
*
267+
* The development mode affects how certain parts of the WordPress application behave, which is relevant when
268+
* developing for WordPress.
269+
*
270+
* Valid developer modes are 'core', 'plugin', 'theme', or an empty string to disable developer mode.
271+
*
272+
* Developer mode is considered separately from `WP_DEBUG` and {@see wp_get_environment_type()}. It does not affect
273+
* debugging output, but rather functional nuances in WordPress.
274+
*
275+
* @since 6.3.0
276+
*
277+
* @return string The current development mode.
278+
*/
279+
function wp_get_development_mode() {
280+
static $current_mode = null;
281+
282+
if ( ! defined( 'WP_RUN_CORE_TESTS' ) && null !== $current_mode ) {
283+
return $current_mode;
284+
}
285+
286+
$development_mode = WP_DEVELOPMENT_MODE;
287+
288+
// Exclusively for core tests, rely on a global `$_wp_tests_development_mode`.
289+
if ( defined( 'WP_RUN_CORE_TESTS' ) && isset( $GLOBALS['_wp_tests_development_mode'] ) ) {
290+
$development_mode = $GLOBALS['_wp_tests_development_mode'];
291+
}
292+
293+
$valid_modes = array(
294+
'core',
295+
'plugin',
296+
'theme',
297+
'',
298+
);
299+
if ( ! in_array( $development_mode, $valid_modes, true ) ) {
300+
$development_mode = '';
301+
}
302+
303+
$current_mode = $development_mode;
304+
305+
return $current_mode;
306+
}
307+
264308
/**
265309
* Don't load all of WordPress when handling a favicon.ico request.
266310
*

‎tests/phpunit/tests/load/wpGetDevelopmentMode.php‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<?php
2+
/**
3+
* Unit tests for `wp_get_development_mode()`.
4+
*
5+
* @package WordPress
6+
* @subpackage UnitTests
7+
* @since 6.3.0
8+
*
9+
* @group load.php
10+
* @covers ::wp_get_development_mode
11+
*/
12+
class Test_WP_Get_Development_Mode extends WP_UnitTestCase {
13+
14+
/**
15+
* Tests that `wp_get_development_mode()` returns the value of the `WP_DEVELOPMENT_MODE` constant.
16+
*
17+
* @ticket 57487
18+
*/
19+
public function test_wp_get_development_mode_constant() {
20+
$this->assertSame( WP_DEVELOPMENT_MODE, wp_get_development_mode() );
21+
}
22+
23+
/**
24+
* Tests that `wp_get_development_mode()` allows test overrides.
25+
*
26+
* @ticket 57487
27+
*/
28+
public function test_wp_get_development_mode_test_overrides() {
29+
global $_wp_tests_development_mode;
30+
31+
$_wp_tests_development_mode = 'plugin';
32+
$this->assertSame( 'plugin', wp_get_development_mode() );
33+
}
34+
35+
/**
36+
* Tests that `wp_get_development_mode()` ignores invalid filter values.
37+
*
38+
* @ticket 57487
39+
*/
40+
public function test_wp_get_development_mode_filter_invalid_value() {
41+
global $_wp_tests_development_mode;
42+
43+
$_wp_tests_development_mode = 'invalid';
44+
$this->assertSame( '', wp_get_development_mode() );
45+
}
46+
}

‎tests/phpunit/tests/theme/wpGetGlobalStylesSvgFilters.php‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,29 @@ public function test_switching_themes_should_recalculate_svg() {
3434
$this->assertStringContainsString( '<svg', $svg_for_default_theme, 'Block theme should contain SVG' );
3535
$this->assertNotSame( $svg_for_default_theme, $svg_for_block_theme, 'Cache value should have changed' );
3636
}
37+
38+
/**
39+
* Tests that the function relies on the development mode for whether to use caching.
40+
*
41+
* @ticket 57487
42+
*
43+
* @covers ::wp_get_global_styles_svg_filters
44+
*/
45+
public function test_caching_is_used_when_developing_theme() {
46+
global $_wp_tests_development_mode;
47+
48+
switch_theme( 'block-theme' );
49+
50+
// Store SVG in cache.
51+
$svg = '<svg></svg>';
52+
wp_cache_set( 'wp_get_global_styles_svg_filters', $svg, 'theme_json' );
53+
54+
// By default, caching should be used, so the above value will be returned.
55+
$_wp_tests_development_mode = '';
56+
$this->assertSame( $svg, wp_get_global_styles_svg_filters(), 'Caching was not used despite development mode disabled' );
57+
58+
// When the development mode is set to 'theme', caching should not be used.
59+
$_wp_tests_development_mode = 'theme';
60+
$this->assertNotSame( $svg, wp_get_global_styles_svg_filters(), 'Caching was used despite theme development mode' );
61+
}
3762
}

‎tests/phpunit/tests/theme/wpGetGlobalStylesheet.php‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,29 @@ public function test_switching_themes_should_recalculate_stylesheet() {
220220
$this->assertStringContainsString( $expected, $stylesheet_for_block_theme, 'Custom font size (100px) should be present for block theme' );
221221
}
222222

223+
/**
224+
* Tests that the function relies on the development mode for whether to use caching.
225+
*
226+
* @ticket 57487
227+
*/
228+
public function test_caching_is_used_when_developing_theme() {
229+
global $_wp_tests_development_mode;
230+
231+
$this->maybe_switch_theme( 'block-theme' );
232+
233+
// Store CSS in cache.
234+
$css = '.my-class { display: block; }';
235+
wp_cache_set( 'wp_get_global_stylesheet', $css, 'theme_json' );
236+
237+
// By default, caching should be used, so the above value will be returned.
238+
$_wp_tests_development_mode = '';
239+
$this->assertSame( $css, wp_get_global_stylesheet(), 'Caching was not used despite development mode disabled' );
240+
241+
// When the development mode is set to 'theme', caching should not be used.
242+
$_wp_tests_development_mode = 'theme';
243+
$this->assertNotSame( $css, wp_get_global_stylesheet(), 'Caching was used despite theme development mode' );
244+
}
245+
223246
/**
224247
* Adds the 'editor-font-sizes' theme support with custom font sizes.
225248
*

‎tools/local-env/scripts/install.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ wp_cli( `config set WP_DEBUG_LOG ${process.env.LOCAL_WP_DEBUG_LOG} --raw --type=
1616
wp_cli( `config set WP_DEBUG_DISPLAY ${process.env.LOCAL_WP_DEBUG_DISPLAY} --raw --type=constant` );
1717
wp_cli( `config set SCRIPT_DEBUG ${process.env.LOCAL_SCRIPT_DEBUG} --raw --type=constant` );
1818
wp_cli( `config set WP_ENVIRONMENT_TYPE ${process.env.LOCAL_WP_ENVIRONMENT_TYPE} --type=constant` );
19+
wp_cli( `config set WP_DEVELOPMENT_MODE ${process.env.LOCAL_WP_DEVELOPMENT_MODE} --type=constant` );
1920

2021
// Move wp-config.php to the base directory, so it doesn't get mixed up in the src or build directories.
2122
renameSync( 'src/wp-config.php', 'wp-config.php' );

0 commit comments

Comments
 (0)