WP Config Transformer

https://github.com/wp-cli/wp-config-transformer
Admin
WP Config Transformer is a PHP library that programmatically edits wp-config.php files, letting...
Tokens:8,854
Snippets:65
Trust Score:9.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install and run PHPUnit tests

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Commands to set up and run the test suite for the wp-config-transformer project. Requires Composer and PHPUnit installed globally.

```bash
$ composer global require phpunit/phpunit
$ composer install
$ phpunit
```

--------------------------------

### Poorly-formatted define example

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Example of a poorly formatted define statement that can be normalized using the 'normalize' option.

```php
                 define   (    'WP_DEBUG'   ,
    false, false     )
;
```

--------------------------------

### Normalized output example

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

The resulting output after normalizing the poorly-formatted define statement.

```php
define( 'WP_DEBUG', true );
```

--------------------------------

### Option forwarding with update() and anchor

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows how options supported by add() can be passed through update() and forwarded when the config does not exist. The example updates the FOO constant in-place if it exists, otherwise adds it to a special location.

```php
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'anchor' => '/** My special location' ) );
```

```php
if ( $config_transformer->exists( 'constant', 'FOO' ) ) {
    $config_transformer->update( 'constant', 'FOO', 'bar' );
} else {
    $config_transformer->add( 'constant', 'FOO', 'bar', array( 'anchor' => '/** My special area' ) );
}
```

--------------------------------

### Instantiate WPConfigTransformer

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Creates a new WPConfigTransformer instance for the specified wp-config.php file.

```php
$config_transformer = new WPConfigTransformer( '/path/to/wp-config.php' );
```

--------------------------------

### Set environment variables for compact test output

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/AGENTS.md

Set these environment variables before running Composer scripts so tools report problems compactly without progress bars or ANSI color.

```bash
export NO_COLOR=1
export WP_CLI_TEST_QUIET=1
```

--------------------------------

### Edit variables with update, add, remove

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows how to update, add, and remove variables in the config file.

```php
$config_transformer->update( 'variable', 'table_prefix', 'wp_custom_' );
$config_transformer->add( 'variable', 'my_special_global', 'foo' );
$config_transformer->remove( 'variable', 'my_special_global' );
```

--------------------------------

### Correct one config definition per line

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows the correct format where each config definition is on its own line. The regex will only match one config definition per line.

```php
define( 'WP_DEBUG', true );
define( 'WP_SCRIPT_DEBUG', true );
$table_prefix = 'wp_';
$my_var = 'foo';
```

--------------------------------

### Check existence and update with add false

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows that when 'add' is false and the constant does not exist, the update returns false.

```php
$config_transformer->exists( 'constant', 'FOO' ); // Returns false
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => false ) ); // Returns false
```

--------------------------------

### new WPConfigTransformer( string $wp_config_path )

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Instantiates the WPConfigTransformer class with the path to the wp-config.php file to be edited.

```APIDOC
## Constructor: WPConfigTransformer

### Description
Creates a new instance of the WPConfigTransformer to programmatically edit a wp-config.php file.

### Parameters
- **$wp_config_path** (string) - Required - The file path to the wp-config.php file.

### Example
```php
$config_transformer = new WPConfigTransformer( '/path/to/wp-config.php' );
```
```

--------------------------------

### Correct boolean third argument in define()

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows the correct usage where the third argument in define() is a boolean. The third argument must be a boolean, not a string or integer.

```php
define( 'WP_DEBUG', true, false );
define( 'WP_DEBUG', true, FALSE );
define( 'foo', true, true );
define( 'foo', true, TRUE );
```

--------------------------------

### Update with placement option

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates constants with the 'placement' option to control whether new configs are placed before or after the anchor string. The default is 'before'.

```php
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'placement' => 'before' ) ); // Default
$config_transformer->update( 'constant', 'BAZ', 'qux', array( 'placement' => 'after' ) );
```

--------------------------------

### Update with raw option

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates a constant with the 'raw' option to place the value as unquoted executable syntax instead of a string.

```php
$config_transformer->update( 'constant', 'ABSPATH', "dirname( __FILE__ ) . '/somewhere/else/'", array( 'raw' => true ) );
```

--------------------------------

### Check for existence of constants and variables

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Checks whether a constant or variable exists in the config file before performing actions.

```php
if ( $config_transformer->exists( 'constant', 'MY_SPECIAL_CONFIG' ) ) {
	// do stuff
}

if ( $config_transformer->exists( 'variable', 'my_special_global' ) ) {
	// do stuff
}
```

--------------------------------

### Edit constants with update, add, remove

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows how to update, add, and remove constants in the config file. The update call uses the 'raw' option to set the value as raw PHP code.

```php
$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true ) );
$config_transformer->add( 'constant', 'MY_SPECIAL_CONFIG', 'foo' );
$config_transformer->remove( 'constant', 'MY_SPECIAL_CONFIG' );
```

--------------------------------

### Incorrect multiple config definitions on one line

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows the incorrect format where multiple config definitions are on the same line. The regex will only match one config definition per line, so this will not work as expected.

```php
define( 'WP_DEBUG', true ); define( 'WP_SCRIPT_DEBUG', true );
$table_prefix = 'wp_'; $my_var = 'foo';
```

--------------------------------

### define() with third parameter false

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/tests/fixtures/block-data.txt

define() calls with a third parameter 'false' (case-insensitive). Includes various whitespace and formatting variations, including double quotes and uppercase 'DEFINE'.

```php
define( 'TEST_CONST_#', 'oldvalue', false );
```

```php
define(    'TEST_CONST_#'   ,    'oldvalue'  , false  );
```

```php
define(
    'TEST_CONST_#',
    'oldvalue',
    false
);
```

```php
define(
    'TEST_CONST_#'
    ,
    'oldvalue',
    false
    )
;
```

```php
            define    (
    'TEST_CONST_#'
,
                'oldvalue'
  ,
false
)
            ;
```

```php
define( "TEST_SYNTAX_#",'oldvalue'   ,false );
```

```php
define  (   "TEST_SYNTAX_#",'oldvalue',false );
```

```php
define('TEST_CONST_#','oldvalue',false);
```

```php
DEFINE('TEST_CONST_#', 'oldvalue', false);
```

```php
DEFINE  ('TEST_CONST_#'    ,'oldvalue'     ,false   );
```

--------------------------------

### define() with single quotes, no case sensitivity

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/tests/fixtures/block-data.txt

Various whitespace and formatting variations of define() with single-quoted constant name and value. Includes lowercase and uppercase 'define' keyword. The constant name uses a placeholder '#'.

```php
define( 'TEST_CONST_#', 'oldvalue' );
```

```php
define(    'TEST_CONST_#'   ,    'oldvalue'    );
```

```php
define(
    'TEST_CONST_#',
    'oldvalue'
);
```

```php
define(
    'TEST_CONST_#'
    ,
    'oldvalue'
    )
;
```

```php
            define    (
    'TEST_CONST_#'
,
                'oldvalue'
)
            ;
```

```php
define( "TEST_SYNTAX_#",'oldvalue'   );
```

```php
define  (   "TEST_SYNTAX_#",'oldvalue' );
```

```php
define('TEST_CONST_#','oldvalue');
```

```php
DEFINE( 'TEST_CONST_#', 'oldvalue' );
```

```php
DEFINE  ('TEST_CONST_#'    ,'oldvalue'   );
```

--------------------------------

### Update with add option

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates constants with the 'add' option to control whether a missing config is added. The default is true.

```php
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => true ) ); // Default
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => false ) );
```

--------------------------------

### exists( string $type, string $name )

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Checks whether a constant or variable exists in the wp-config.php file.

```APIDOC
## Method: exists

### Description
Checks whether a constant or variable exists in the wp-config.php file.

### Parameters
- **$type** (string) - Required - The type of config: 'constant' or 'variable'.
- **$name** (string) - Required - The name of the constant or variable to check.

### Return Value
- (bool) - True if the config exists, false otherwise.

### Examples
```php
if ( $config_transformer->exists( 'constant', 'MY_SPECIAL_CONFIG' ) ) {
    // do stuff
}

if ( $config_transformer->exists( 'variable', 'my_special_global' ) ) {
    // do stuff
}
```
```

--------------------------------

### define() with trailing comment

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/tests/fixtures/block-data.txt

define() call with a trailing comment on the same line. Also shows a preceding echo statement before the define() call.

```php
define( 'TEST_CONST_#', 'oldvalue' ); // Some comment
```

```php
echo null; // Some comment before
define( 'TEST_CONST_#', 'oldvalue' ); // Some comment
```

--------------------------------

### add( string $type, string $name, mixed $value, array $options = [] )

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Adds a new constant or variable to the wp-config.php file. The value is placed as a string unless the 'raw' option is set to true.

```APIDOC
## Method: add

### Description
Adds a new constant or variable to the wp-config.php file. The value is placed as a string unless the 'raw' option is set to true.

### Parameters
- **$type** (string) - Required - The type of config: 'constant' or 'variable'.
- **$name** (string) - Required - The name of the constant or variable.
- **$value** (mixed) - Required - The value to set.
- **$options** (array) - Optional - An associative array of options:
  - **raw** (bool) - Optional - If true, the value is inserted without quotes. Default false.
  - **anchor** (string) - Optional - The anchor string to place the config relative to. Default '/** Absolute path to the WordPress directory'.
  - **placement** (string) - Optional - 'before' or 'after' the anchor. Default 'before'.
  - **separator** (string) - Optional - The separator between the config and the anchor. Default PHP_EOL . PHP_EOL.

### Return Value
- (bool) - True on success, false on failure.

### Examples
```php
// Add a constant
$config_transformer->add( 'constant', 'MY_SPECIAL_CONFIG', 'foo' );

// Add a variable
$config_transformer->add( 'variable', 'my_special_global', 'foo' );
```
```

--------------------------------

### Incorrect non-boolean third argument in define()

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows the incorrect usage where the third argument in define() is not a boolean. The third argument must be a boolean, not a string or integer.

```php
define( 'WP_DEBUG', true, 0 );
define( 'WP_DEBUG', true, 'yes' );
define( 'WP_DEBUG', true, 'this comma, will break everything' );
```

--------------------------------

### Update with normalize option

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates a constant with the 'normalize' option to replace existing syntax with WP Coding Standards compliant output.

```php
$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true, 'normalize' => true ) );
```

--------------------------------

### Variable assignment with single quotes

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/tests/fixtures/block-data.txt

Variable assignment to $test_var_# with single-quoted value. Includes various whitespace and formatting variations, including multi-line assignments.

```php
$test_var_# = 'oldvalue';
```

```php
$test_var_#='oldvalue';
```

```php
   $test_var_#  =  'oldvalue'  ;
```

```php
   $test_var_#
   =
   'oldvalue'
   ;
```

```php
$test_var_#
=  'oldvalue';
```

```php
$test_var_#   ='oldvalue'    ;
```

```php
$test_var_#=
'oldvalue' ;
```

--------------------------------

### Variable assignment with trailing comment

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/tests/fixtures/block-data.txt

Variable assignment with a trailing comment on the same line. Also shows a preceding echo statement before the assignment.

```php
$test_var_# = 'oldvalue'; // Some comment
```

```php
echo null; // Some comment before
$test_var_# = 'oldvalue'; // Some comment
```

--------------------------------

### Variable assignment with double quotes

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/tests/fixtures/block-data.txt

Variable assignment to $test_var_# with double-quoted value. Includes variations in whitespace and line breaks.

```php
   $test_var_#  =  "oldvalue"  ;
```

```php
$test_var_#     ="oldvalue"
;
```

```php
    $test_var_#="oldvalue";
```

--------------------------------

### update( string $type, string $name, mixed $value, array $options = [] )

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates an existing constant or variable in the wp-config.php file, or adds it if it doesn't exist (unless the 'add' option is set to false). Supports options for normalization, raw values, anchor string, placement, separator, and add-if-missing behavior.

```APIDOC
## Method: update

### Description
Updates an existing constant or variable in the wp-config.php file, or adds it if it doesn't exist (unless the 'add' option is set to false). Supports options for normalization, raw values, anchor string, placement, separator, and add-if-missing behavior.

### Parameters
- **$type** (string) - Required - The type of config: 'constant' or 'variable'.
- **$name** (string) - Required - The name of the constant or variable.
- **$value** (mixed) - Required - The value to set.
- **$options** (array) - Optional - An associative array of options:
  - **raw** (bool) - Optional - If true, the value is inserted without quotes (e.g., for executable code). Default false.
  - **normalize** (bool) - Optional - If true, normalizes the output to WP Coding Standards. Default false.
  - **anchor** (string) - Optional - The anchor string to place the config relative to. Default '/** Absolute path to the WordPress directory'.
  - **placement** (string) - Optional - 'before' or 'after' the anchor. Default 'before'.
  - **separator** (string) - Optional - The separator between the config and the anchor. Default PHP_EOL . PHP_EOL.
  - **add** (bool) - Optional - If true, adds the config if it doesn't exist. If false, returns false when the config doesn't exist. Default true.

### Return Value
- (bool) - True on success, false on failure (e.g., when 'add' is false and the config doesn't exist).

### Examples
```php
// Update a constant with raw value
$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true ) );

// Update a variable
$config_transformer->update( 'variable', 'table_prefix', 'wp_custom_' );

// Update with normalization
$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true, 'normalize' => true ) );

// Update with custom anchor and placement
$config_transformer->update( 'constant', 'BAZ', 'qux', array( 'placement' => 'after' ) );

// Update without adding if missing
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => false ) );
```
```

--------------------------------

### Update with anchor option

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates a constant using the 'anchor' option to specify the text that additions will be anchored to. The default anchor is '/** Absolute path to the WordPress directory'.

```php
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'anchor' => '/** Absolute path to the WordPress directory' ) ); // Default
```

--------------------------------

### Edit-in-place update of WP_DEBUG constant

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Shows the horrifically-valid PHP block that the edit-in-place strategy preserves formatting for. The update call changes only the value, leaving the formatting and additional argument(s) unscathed.

```php
                 define   (    'WP_DEBUG'   ,
    false, false     )
;
```

```php
$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true ) );
```

```php
                 define   (    'WP_DEBUG'   ,
    true, false     )
;
```

--------------------------------

### remove( string $type, string $name )

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Removes an existing constant or variable from the wp-config.php file.

```APIDOC
## Method: remove

### Description
Removes an existing constant or variable from the wp-config.php file.

### Parameters
- **$type** (string) - Required - The type of config: 'constant' or 'variable'.
- **$name** (string) - Required - The name of the constant or variable to remove.

### Return Value
- (bool) - True on success, false on failure.

### Examples
```php
// Remove a constant
$config_transformer->remove( 'constant', 'MY_SPECIAL_CONFIG' );

// Remove a variable
$config_transformer->remove( 'variable', 'my_special_global' );
```
```

--------------------------------

### Update with separator option

Source: https://github.com/wp-cli/wp-config-transformer/blob/main/README.md

Updates constants with the 'separator' option to control the separator between a new config and its anchor string. The default is PHP_EOL . PHP_EOL.

```php
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'separator' => PHP_EOL . PHP_EOL ) ); // Default
$config_transformer->update( 'constant', 'FOO', 'bar', array( 'separator' => PHP_EOL ) );
```
Tokens:
Raw