wp-debugging / vendor / wp-cli / wp-config-transformer / README.md

README.md in WP Debugging 2.12.6, at vendor/wp-cli/wp-config-transformer/README.md

232 lines 6.8 KB

Raw Download Zip

1	# WP Config Transformer
2
3	Programmatically edit a `wp-config.php` file.
4
5	[](https://github.com/wp-cli/wp-config-transformer/actions/workflows/testing.yml![Testing](https://github.com/wp-cli/wp-config-transformer/actions/workflows/testing.yml/badge.svg)](https://github.com/wp-cli/wp-config-transformer/actions/workflows/testing.yml](https://github.com/wp-cli/wp-config-transformer/actions/workflows/testing.yml)
6
7	Quick links: [](#usingUsing](#using](#using) \| [](#optionsOptions](#options](#options) \| [](#how-it-worksHow it works](#how-it-works](#how-it-works) \| [](#testingTesting](#testing](#testing)
8
9	## Using
10
11	### Instantiate
12
13	```php
14	$config_transformer = new WPConfigTransformer( '/path/to/wp-config.php' );
15	```
16
17	### Edit constants
18
19	```php
20	$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true ) );
21	$config_transformer->add( 'constant', 'MY_SPECIAL_CONFIG', 'foo' );
22	$config_transformer->remove( 'constant', 'MY_SPECIAL_CONFIG' );
23	```
24
25	### Edit variables
26
27	```php
28	$config_transformer->update( 'variable', 'table_prefix', 'wp_custom_' );
29	$config_transformer->add( 'variable', 'my_special_global', 'foo' );
30	$config_transformer->remove( 'variable', 'my_special_global' );
31	```
32
33	### Check for existence
34
35	```php
36	if ( $config_transformer->exists( 'constant', 'MY_SPECIAL_CONFIG' ) ) {
37	// do stuff
38	}
39
40	if ( $config_transformer->exists( 'variable', 'my_special_global' ) ) {
41	// do stuff
42	}
43	```
44
45	## Options
46
47	Special behaviors when adding or updating configs are available using the options array.
48
49	### Normalization
50
51	In contrast to the "edit in place" strategy above, there is the option to normalize the output during a config update and effectively replace the existing syntax with output that adheres to WP Coding Standards.
52
53	Let's reconsider a poorly-formatted example:
54
55	```php
56	define ( 'WP_DEBUG' ,
57	false, false )
58	;
59	```
60
61	This time running:
62
63	```php
64	$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true, 'normalize' => true ) );
65	```
66
67	Now we will get an output of:
68
69	```php
70	define( 'WP_DEBUG', true );
71	```
72
73	Nice!
74
75	### Raw format
76
77	Suppose you want to change your `ABSPATH` config _(gasp!)_. To do that, we can run:
78
79	```php
80	$config_transformer->update( 'constant', 'ABSPATH', "dirname( __FILE__ ) . '/somewhere/else/'", array( 'raw' => true ) );
81	```
82
83	The `raw` option means that instead of placing the value inside the config as a string `"dirname( __FILE__ ) . '/somewhere/else/'"` it will become unquoted (and executable) syntax `dirname( __FILE__ ) . '/somewhere/else/'`.
84
85	### Anchor string
86
87	The anchor string is the piece of text that additions will be anchored to.
88
89	```php
90	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'anchor' => '/** Absolute path to the WordPress directory' ) ); // Default
91	```
92
93	### Anchor placement
94
95	By default, new configs will be placed before the anchor string.
96
97	```php
98	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'placement' => 'before' ) ); // Default
99	$config_transformer->update( 'constant', 'BAZ', 'qux', array( 'placement' => 'after' ) );
100	```
101
102	### Anchor separator
103
104	By default, the separator between a new config and its anchor string is an EOL ("\n" on *nix and "\r\n" on Windows).
105
106	```php
107	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'separator' => PHP_EOL . PHP_EOL ) ); // Default
108	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'separator' => PHP_EOL ) );
109	```
110
111	### Add if missing
112
113	By default, when attempting to update a config that doesn't exist, one will be added. This behavior can be overridden by specifying the `add` option and setting it to `false`.
114
115	```php
116	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => true ) ); // Default
117	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => false ) );
118	```
119
120	If the constant `FOO` exists, it will be updated in-place. And if not, the update will return `false`:
121
122	```php
123	$config_transformer->exists( 'constant', 'FOO' ); // Returns false
124	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'add' => false ) ); // Returns false
125	```
126
127	## How it works
128
129	### Parsing configs
130
131	Constants: https://regex101.com/r/6AeNGP/4
132
133	Variables: https://regex101.com/r/cSLZZz/4
134
135	### Editing in place
136
137	Due to the unsemantic nature of the `wp-config.php` file, and PHP's loose syntax in general, the WP Config Transformer takes an "edit in place" strategy in order to preserve the original formatting and whatever other obscurities may be taking place in the block. After all, we only care about transforming values, not constant or variable names.
138
139	To achieve this, the following steps are performed:
140
141	1. A PHP block containing a config is split into distinct parts.
142	2. Only the part containing the config value is targeted for replacement.
143	3. The parts are reassembled with the new value in place.
144	4. The old PHP block is replaced with the new PHP block.
145
146	Consider the following horrifically-valid PHP block, that also happens to be using the optional (and rare) 3rd argument for constant case-sensitivity:
147
148	```php
149	define ( 'WP_DEBUG' ,
150	false, false )
151	;
152	```
153
154	The "edit in place" strategy means that running:
155
156	```php
157	$config_transformer->update( 'constant', 'WP_DEBUG', 'true', array( 'raw' => true ) );
158	```
159
160	Will give us a result that safely changes _only_ the value, leaving the formatting and additional argument(s) unscathed:
161
162	```php
163	define ( 'WP_DEBUG' ,
164	true, false )
165	;
166	```
167
168	### Option forwarding
169
170	Any option supported by the `add()` method can also be passed through the `update()` method and forwarded along when the config does not exist.
171
172	For example, you want to update the `FOO` constant in-place if it exists, otherwise it should be added to a special location:
173
174	```php
175	$config_transformer->update( 'constant', 'FOO', 'bar', array( 'anchor' => '/** My special location' ) );
176	```
177
178	Which has the same effect as the long-form logic:
179
180	```php
181	if ( $config_transformer->exists( 'constant', 'FOO' ) ) {
182	$config_transformer->update( 'constant', 'FOO', 'bar' );
183	} else {
184	$config_transformer->add( 'constant', 'FOO', 'bar', array( 'anchor' => '/** My special area' ) );
185	}
186	```
187
188	Of course the exception to this is if you are using the `add => false` option, in which case the update will return `false` and no config will be added.
189
190	### Known issues
191
192	1. Regex will only match one config definition per line.
193
194	CORRECT
195	```php
196	define( 'WP_DEBUG', true );
197	define( 'WP_SCRIPT_DEBUG', true );
198	$table_prefix = 'wp_';
199	$my_var = 'foo';
200	```
201
202	INCORRECT
203	```php
204	define( 'WP_DEBUG', true ); define( 'WP_SCRIPT_DEBUG', true );
205	$table_prefix = 'wp_'; $my_var = 'foo';
206	```
207
208	2. If the third argument in `define()` is used, it _must_ be a boolean.
209
210	CORRECT
211	```php
212	define( 'WP_DEBUG', true, false );
213	define( 'WP_DEBUG', true, FALSE );
214	define( 'foo', true, true );
215	define( 'foo', true, TRUE );
216	```
217
218	INCORRECT
219	```php
220	define( 'WP_DEBUG', true, 0 );
221	define( 'WP_DEBUG', true, 'yes' );
222	define( 'WP_DEBUG', true, 'this comma, will break everything' );
223	```
224
225	## Testing
226
227	```bash
228	$ composer global require phpunit/phpunit
229	$ composer install
230	$ phpunit
231	```
232