Blueprints: Rewrite wp-config.php to define constants in the defineWpConfigConsts step

[adamziel]

Summary

This PR enhances the defineWpConfigConsts step by allowing constants to be defined in two ways:

1. By rewriting wp-config.php (default behavior)
   • Existing define() calls are rewritten with new constant values
   • New define() calls are prepended
   • All calls wrapped in if(!defined()) to avoid conflicts
2. By calling define() before script execution (previous behavior)
   • Constants defined directly via PHP before script execution
   • Does not modify wp-config.php
   • May conflict with existing defines in wp-config.php (limitation)

Related to #901
Related to WordPress/playground-tools#135
Closes #900

wp-config.php rewriting details

The following wp-config.php:

<?php
define('WP_DEBUG', true);
// The third define() argument is also supported:
define('SAVEQUERIES', false, true);

// Expression are wrapped in `if(!defined())` guards
define(true ? 'WP_DEBUG_LOG' : 'WP_DEBUG_LOG', 123);

// Guarded expressions shouldn't be wrapped twice
if(!defined(1 ? 'A' : 'B')) {
    define(1 ? 'A' : 'B', 0);
}

// More advanced expression
define((function() use($x) {
    return [$x, 'a'];
})(), 123);

When rewritten like this:

rewrite_wp_config_to_define_constants($content, [
    'WP_DEBUG' => false,
    'WP_DEBUG_LOG' => true,
    'SAVEQUERIES' => true,
    'NEW_CONSTANT' => "new constant",
]);

Will become:

<?php
define('WP_DEBUG_LOG',true);
define('NEW_CONSTANT','new constant');
?><?php
define('WP_DEBUG',false);
// The third define() argument is also supported:
define('SAVEQUERIES',true, true);

// Expression are wrapped in `if(!defined())` guards
if(!defined($const ? 'WP_DEBUG_LOG' : 'WP_DEBUG_LOG')) {
     define($const ? 'WP_DEBUG_LOG' : 'WP_DEBUG_LOG', 123);
}

// Guarded expressions shouldn't be wrapped twice
if(!defined(1 ? 'A' : 'B')) {
    define(1 ? 'A' : 'B', 0);
}

// More advanced expression
if(!defined((function() use($x) {
   return [$x, 'a'];
})())) {
    define((function() use($x) {
        return [$x, 'a'];
    })(), 123);
}

Testing instructions

Go to the following URL without this PR applied and confirm there are warnings like Warning: Constant WP_DEBUG already defined:

http://localhost:5400/website-server/#{%22landingPage%22:%22/%22,%22phpExtensionBundles%22:[%22kitchen-sink%22],%22preferredVersions%22:{%22php%22:%228.0%22,%22wp%22:%225.9%22},%22steps%22:[{%22step%22:%22defineWpConfigConsts%22,%22consts%22:{%22WP_DEBUG%22:true}},{%22step%22:%22defineWpConfigConsts%22,%22consts%22:{%22WP_DEBUG_ONLY%22:%22a%22}}]}

Now go there with this PR applied and confirm the warnings are gone. The Blueprint encoded in the URL above calls the defineWpConfigConsts step twice just to make sure a duplicate and conflicting define() call won't be added.

cc @sejas

[adamziel]

Let's merge and keep a hand on the pulse.