Add Better Debugging Documentation Into wp-config.php

[philiparthurmoore]

WordPress has a number of fantastic constants available to it to assist with debugging, specifically WP_DEBUG, WP_DEBUG_DISPLAY, WP_DEBUG_LOG, and SCRIPT_DEBUG. There are more, to be sure, but these alone go a long way to making sure that publicly released themes and plugins are relatively sound.

I suggest that WP_DEBUG_DISPLAY, WP_DEBUG_LOG, and SCRIPT_DEBUG are added into wp-config.php in the same manner that WP_DEBUG has been added into wp-config.php, with well-documented usage notes. As it stands now, it seems like the barrier to entry into debugging WordPress correctly is too high (seems, at least), leading new developers to release buggy plugins and themes.

I do ​something like this. I'm sure there's a better way to do this, and a better way to word things, but the sentiment is that it'd be very useful to put something like this inside of WordPress' config file.

[DrewAPicture]

I can get on board with improving inline docs here.

I think we need to be careful in leaning too far one way or the other on the developer:user spectrum, however. wp-config is a bit of a unique case in that users interact with it as much as, or more often than developers in some cases, so any vernacular we use needs to be friendly to both groups and anything in between.

We already have some inline-docs standards in place for ​documenting constants that could be applied here too.

[georgestephanis]

I think we can probably base a decent amount of our implementation off how PHP handles their config file's inline documentation.

​https://github.com/php/php-src/blob/master/php.ini-production

A lot of the optional constants they leave there, just commented out, and have plain english explanations of what stuff means.

[Kopepasah]

I definitely think it is a good idea to add more debug options and documentation to the wp-config.php file. When I first started developing for WordPress, documentation was sparse at best. Now, documentation is much better (both inline and online), but I think adding the debug documentation to wp-config.php will give users willing to dig into the code a place to start and learn.

[siobhan]

I've taken a pass at this here: ​https://gist.github.com/smckeown/74cce2d31297646fe8f7

I'd appreciate technical feedback and also any feedback re:documentation standards.

Just a few points:

• I've left the uncommented constants as Philip put them in, but should they be set to the defaults?
• Although the information about Jetpack is extremely useful for developers, I'm not sure if we should include documentation for third-party plugins in WordPress core.

[helen]

Replying to siobhan:

I would use single-line comments (// instead of /* */) for the line with the constant, otherwise it's very tedious to uncomment and use the constant.

[rmccue]

Replying to helen:

Replying to siobhan:

I would use single-line comments (// instead of /* */) for the line with the constant, otherwise it's very tedious to uncomment and use the constant.

Agreed. Personally, I actually like using hash comments (#) for lines of code that can be commented/uncommented, as it makes it clear what's a comment and what's a disabled line of code. Whether we want to actually use that pattern, I don't know. :)

I'm also thinking there's probably not much point repeating the constant name itself, since it's on the line straight afterwards.

Thinking something like this:

/**
 * Turn on/off debugging mode.
 * Default: false.
 */
# define('WP_DEBUG', true);

[philiparthurmoore]

Replying to rmccue:

Replying to helen:

Replying to siobhan:

I would use single-line comments (// instead of /* */) for the line with the constant, otherwise it's very tedious to uncomment and use the constant.

Agreed. Personally, I actually like using hash comments (#) for lines of code that can be commented/uncommented, as it makes it clear what's a comment and what's a disabled line of code. Whether we want to actually use that pattern, I don't know. :)

This is a really good point.

@siobhan, completely agree about Jetpack - I should have made it clear that I didn't mean for that to be considered.

[F J Kaiser]

First: +1 - I'm 100% in on that.

Replying to georgestephanis:

(...) base a decent amount of our implementation off how PHP handles their config file's inline documentation.

About the coding standard, I have to agree with rmccue:

(...) using hash comments (#) for lines of code that can be commented/uncommented, as it makes it clear what's a comment and what's a disabled line of code.

That's what I use myself for the sole reason of making different comments distinguishable.

One suggestion I have is to shorten the intro docBlock and split up. Something like this:

// NOTE: Remove the # on the start of a line to activate it

/**
 * Turns on debugging mode. 
 * Default: false.
 */
# define( 'WP_DEBUG', true );

People really hate reading. Instead they try and fail and forget what they have tried and panic. So I would stick one very brief docBlock to each single constants.

---

As I like the idea of maturing the wp-config.php to something like the php.ini, here's for a more complete example the wp-config.php for my nightly.dev trac setup. I use similar config files for all my installs (but this messy one was the one I had at hand): ​https://gist.github.com/franz-josef-kaiser/f09a93d8fc6e1254f034

Imo we could add an even more complete config file to the core package as a lot of possiblities aren't even known to seasoned devs. Maybe split up with a "below it's your fault" comment/separator.

[mordauk]

A big +1 here.

[grantpalin]

Agree with the idea of using the hash symbol to distinguish lines that can be uncommented, rather than using the double slash. It would be a good way to improve the readability of the file and reduce or eliminate potential ambiguity. And it's one character instead of two. The in-file documentation of the constants could really use some help.

[Rarst]

Replying to siobhan:

I've taken a pass at this here: ​https://gist.github.com/smckeown/74cce2d31297646fe8f7

I'd appreciate technical feedback and also any feedback re:documentation standards.

As other suggested the constant definition should immediately follow their description and be easy t comment/uncomment. That is pretty established in config files which allow comments. Values in commented code/examples should be same as defaults, not opposite so simply uncommenting doesn't change behavior.

"Turn on/off" wording is clunky. It's unclear if it refers to commenting/uncommenting or setting to true/false. For example "Turn on for production sites" for WP_DEBUG_DISPLAY, while you actually want it to be false.

Just a few points:

• I've left the uncommented constants as Philip put them in, but should they be set to the defaults?

I think anything but WP_DEBUG (which is set in current config) should be set to defaults and commented. Since core handles defaults for all of these, there is no reason to overload user with handling them.

[TJNowell]

I don't think the constants should be commented at all, they should be declared uncommented with their default values, this way we sidestep the // vs # issue entirely, the declarations are syntax highlighted by default, and the end user can comment them out using whichever commenting method they wish. It may also aid in automated documentation

[siobhan]

Thanks for all of the feedback everyone. I've updated according to your suggestions, and incorporated with the rest of wp-config.php and tidied up the rest of the file: ​https://gist.github.com/smckeown/74cce2d31297646fe8f7

Other than WP_DEBUG, I commented out the constants with them set to their defaults. WP_DEBUG is set to its default and uncommented (as has been the convention).

[Rarst]

On latest version * Default: false lines can be just omitted I think, since code itself has defaults.

Still don't like "turn on/off" and "to increase..." wording. Standardize at "set to [value] for" ?

[siobhan]

Replying to Rarst:

On latest version * Default: false lines can be just omitted I think, since code itself has defaults.

I think it's worth including what the default is. There's nothing else to indicate what it is except for the fact that it's in the code.

Still don't like "turn on/off" and "to increase..." wording. Standardize at "set to [value] for"

Updated with turn off/on removed. Also got rid of "to increase"

[georgestephanis]

Since we're retooling it, can we please bring it up to core coding standards, with spaces and braces and all the fun bits?

[georgestephanis]

Forked with whitespace changes here:

​https://gist.github.com/georgestephanis/2e04dbf5feb28b1e5106
​https://gist.github.com/georgestephanis/2e04dbf5feb28b1e5106/revisions

[SergeyBiryukov]

Replying to georgestephanis:

can we please bring it up to core coding standards, with spaces and braces and all the fun bits?

Previously: #19870

[nacin]

I'm not sure I'd advocate for any changes here.

[Rarst]

By the @link is deprecated in PSR-5 ( ​https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#810-link-deprecated ), update to @see maybe.

[F J Kaiser]

Replying to Rarst:

By the ​@link is deprecated in PSR-5, update to ​@see maybe.

By now PSR-5 is a draft. But - as usual - we can expect it to go in. +1 on that.

Could we please drop the surrounding brackets? {@link https://example.com description} just knocks out automated parsers in IDEs and is even against ​the current standard of phpDocumentor.

Also I'd drop the explanation of the memory limit. It constantly leads people believing that WordPress can do more than their host allows. Or just add a line that tells that they should consult their host for the max. memory allocated for their box. Something along the lines of

To allow WordPress to use the full memory that is allocated for your hosting service, please contact your hosting company.

Preferably something more eloquent than above example.

[siobhan]

better wp-config

[siobhan]

This ticket seems to have stalled. I've created a patch. Maybe this is the way to go?

[DrewAPicture]

After talking to nacin about this last week I agree that we shouldn't introduce substantial changes to this file. That said, I think there are a couple of things we can do to satisfy the need for more in-depth debugging information:

1. Minor inline documentation updates to wp-config.php to make it more clear what the purpose of the file and the existing constants' definitions are.

2. Introduce a more in-depth explanation of debugging constants in the Plugin Developer Handbook. We can probably even use much of the information in 28551.patch​ -- minus the Nacin ascii art of course.

[kirasong]

Another Approach

[kirasong]

This direction​ better emphasizes the breadth of configuration that is possible in wp-config.php.

It also includes direction suggested in #13237.

See Also: #20000

[siobhan]

ultimate wp config

[siobhan]

Thanks for your feedback. I've amended my patch to incorporate DH-Shredder's changes and to take into account Drew's comments.

I've got a really good feeling about this one.

[rclilly]

Replying to georgestephanis:

I think we can probably base a decent amount of our implementation off how PHP handles their config file's inline documentation.

​https://github.com/php/php-src/blob/master/php.ini-production

A lot of the optional constants they leave there, just commented out, and have plain english explanations of what stuff means.

+1

Most of the time I can configure pho.ini for a specific use case just by reading the comments. It's rare that I have to dig deeper into the documentation. I would absolutely love it if wp-config.php was that complete and that self-documenting.

[georgestephanis]

Replying to rclilly:

Most of the time I can configure pho.ini for a specific use case just by reading the comments.

I, for one, fully support the concept of a phở.ini -- it would specify lots of sriracha and some squeezed lime and basil by default, for me anyways.

[Sidney Harrell]

+1 for this. It would be really nice on a fresh install to be able to go in and uncomment a couple of lines to turn on logging to a file when I'm in there turning on WP_DEBUG and setting DB creds. It's a break in workflow to have to go grab those lines from the codex. Precious seconds lost!

[nacin]

My only other comment here still stands: I'm still not sure I'd advocate for any changes here.

I'd like to make sure we are adequately weighing two competing things:

1. Giving more things users can either be confused about or possibly do damage with. (For example, WP_DEBUG_LOG produces what would be a public log file, SCRIPT_DEBUG can slow down their dashboard, and SAVEQUERIES can slow down their site.)
2. A developer saving a few precious seconds.

At most, I'd suggest we add a link to ​http://codex.wordpress.org/Debugging_in_WordPress and close this out.

[Sidney Harrell]

I see your point. A link would work nicely. It's more hunting down the lines, since it's done so infrequently.

[grantpalin]

Much has been said already about the generous documentation within the PHP configuration file. I haven't seen this mentioned yet, so I'll point out that PHP is shipped with two configuration files:

php.ini-development
php.ini-production

With default settings customized for the respective use scenarios. Why not do something similar for WordPress' configuration, e.g.

wp-config.php-development
wp-config.php-production

We could then have the appropriate default configuration in each, and instruct the user, as PHP does, to rename the appropriate file to wp-config.php. New deployments can just copy the production-configured file, while developers on their local setups can use the development version. Can still have in-file documentation for the settings.

[F J Kaiser]

Replying to nacin:

I'd like to make sure we are adequately weighing two competing things:

Reasonable.

1. Giving more things users can either be confused about or possibly do damage with. (For example, WP_DEBUG_LOG produces what would be a public log file, SCRIPT_DEBUG can slow down their dashboard, and SAVEQUERIES can slow down their site.)

Not only that. With big log files on tiny shared hosts, some Marketplace theme & plugins and some "responsive", 10-sizes-per-image uploads, you can quickly produce incredibly heavy log files that could overflow a users available disk space.

2. A developer saving a few precious seconds.

Imo it's not only that. It's also making devs aware of what is possible.

Replying to grantpalin:

(...) so I'll point out that PHP is shipped with two configuration files
(...) Why not do something similar for WordPress' configuration, e.g.

I see your point and it's valid. My 2 cents: By now we already got an example file where the user has to fill the blanks. I'd really not like to see three different config files shipped in the root dir. This is error prone (renaming the wrong file).

[danielpataki]

#29878 was marked as a duplicate.

[kitchin]

The name wp-config-debug.php would not cause confusion.

Replying to F J Kaiser:

I see your point and it's valid. My 2 cents: By now we already got an example file where the user has to fill the blanks. I'd really not like to see three different config files shipped in the root dir. This is error prone (renaming the wrong file).

[grantpalin]

I agree. If someone is already downloading WordPress and has to open the config file to make edits, the same person can handle renaming one file.

Replying to kitchin:

The name wp-config-debug.php would not cause confusion.

Replying to F J Kaiser:

I see your point and it's valid. My 2 cents: By now we already got an example file where the user has to fill the blanks. I'd really not like to see three different config files shipped in the root dir. This is error prone (renaming the wrong file).

[F J Kaiser]

Replying to grantpalin:

I agree. (...) renaming one file.

Replying to kitchin:

The name wp-config-debug.php would not cause confusion.

To both of: Please read my note again. You are addressing (a) a single config file and (b) the name of this single file. I addressed completely different things: Having multiple config files all named similar.

[jorbin]

I tend to agree with Nacin here. Some comments around the WP_DEBUG declaration that this isn't the only constant you can use and a link to our documentation seems like the best idea here.

[DrewAPicture]

In 32479:

Lightly clean up and improve inline documentation in wp-config-sample.php.

• Fixes some grammatical and wrapping issues in the file header, and breaks the contents list up into, well, a list.
• Adds a note and Codex link to the DocBlock for the WP_DEBUG constant definition on where to find more information about constants used for debugging.

Fixes #28551.