WordPress.org

Make WordPress Core

Opened 3 weeks ago

Last modified 3 weeks ago

#48720 new enhancement

Define all debugging constants for developers in wp-config.php

Reported by: davidnash Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 5.3
Component: Bootstrap/Load Keywords:
Focuses: Cc:
PR Number:

Description

In wp-config.php, in the "For developers" section, we have:

    define( 'WP_DEBUG', false );

I suggest we also add:

define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );

This would mean that changing the value of WP_DEBUG to true would enable the log file but not the display, while making it easy to enable the display.

I've been a WordPress developer for many years. This is the first ticket I've created. I'm a proponent of good defaults. I occasionally change the value of WP_DEBUG, but then need to disable it so that I can use the WordPress dashboard without scrolling through a list of errors and warning from third party themes and plugins.

And to be honest, I never opened the @link to https://codex.wordpress.org/Debugging_in_WordPress

Thanks for considering this enhancement!

Attachments (2)

wp-config-sample.diff (727 bytes) - added by psykro 3 weeks ago.
Minor update to section on debugging mode, includes updated link and some debugging constant examples.
48720.diff (527 bytes) - added by wpgurudev 3 weeks ago.
Enable logging and script debugging if debug is enabled

Download all attachments as: .zip

Change History (13)

#1 @psykro
3 weeks ago

@davidnash interesting suggestion. As a developer myself I understand the reasoning behind wanting to add this, however I also realise that enabling the debug log on regular users sites might not be ideal.

My suggestion would be to leave it as is, but to perhaps add a link in the comments for developers, letting them know about the other available options.

EDIT I just realised that on a normal install this link is included, so perhaps merely an update to the comment, showing some of the possible examples would be useful.

Last edited 3 weeks ago by psykro (previous) (diff)

#2 @psykro
3 weeks ago

Suggested update to comment in wp-config.php

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the Codex.
 *
 * @link https://wordpress.org/support/article/debugging-in-wordpress/
 *
 * Some examples of the debug settings you can enable
 *
 * define( 'WP_DEBUG_LOG', true ) - save all errors to a debug.log file
 * define( 'WP_DEBUG_DISPLAY', false ); - prevent the errors from showing in the HTML of pages
 */

#3 follow-ups: @SergeyBiryukov
3 weeks ago

  • Component changed from General to Bootstrap/Load

Hi there, welcome to WordPress Trac! Thanks for the ticket.

Just noting that there was a previous discussion on this in #28551.

Per nacin's comment in comment:30:ticket:28551:

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.

The link was added in [32479] and changed to HelpHub in [46740].

Last edited 3 weeks ago by SergeyBiryukov (previous) (diff)

@psykro
3 weeks ago

Minor update to section on debugging mode, includes updated link and some debugging constant examples.

#4 in reply to: ↑ 3 ; follow-up: @psykro
3 weeks ago

Replying to SergeyBiryukov:

Hi there, welcome to WordPress Trac! Thanks for the ticket.

Just noting that there was a previous discussion on this in #28551.

Per nacin's comment in comment:30:ticket:28551:

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.

The link was added in [32479] and changed to HelpHub in [32479].

I tend to agree with that, my only suggested addition would be a) updating the document link and b) including one or two examples, which would (hopefully) lead developers to read the document.

@wpgurudev
3 weeks ago

Enable logging and script debugging if debug is enabled

#5 in reply to: ↑ 3 @wpgurudev
3 weeks ago

Replying to SergeyBiryukov:

Hi there, welcome to WordPress Trac! Thanks for the ticket.

Just noting that there was a previous discussion on this in #28551.

Per nacin's comment in comment:30:ticket:28551:

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.

The link was added in [32479] and changed to HelpHub in [32479].

I partially agree with this comment, but as a developer many times we are in following situations:

  1. We want to debug something and check debug log for it, we open wp-config.php file and enable debug and debug log over there.
  1. As a developer, we can investigate through debug log file and does not necessarily need debug information to be displayed. Also it can break ajax calls, so we generally keep it disabled.
  1. Many times we may also need to debug the scripts while performing some other debugging. So, SCRIPT_DEBUG is also useful when WP_DEBBUG is enabled.

We can conditionally make WP_DEBUG_LOG and SCRIPT_DEBUG enabled if WP_DEBUG is on. Since this is generally useful.

Also, SAVEQUERIES is not required always, so we can keep it up to developers to add as we already have documentation link present in docblock.

Adding the patch for suggestion.

#6 in reply to: ↑ 4 ; follow-up: @SergeyBiryukov
3 weeks ago

Replying to psykro:

I tend to agree with that, my only suggested addition would be a) updating the document link and b) including one or two examples, which would (hopefully) lead developers to read the document.

The link was already updated to https://wordpress.org/support/article/debugging-in-wordpress/ in [46740].

WP_DEBUG_LOG creates a public log file, which would be a privacy concern. As mentioned in comment:33:ticket:28551, it could also overflow a user's available disk space if accidentally left enabled.

At a glance, it doesn't look like there are any "safe" examples that won't inadvertently slow down the site or introduce other negative effects if enabled without fully understanding the consequences, so I tend to think a link to the documentation should be enough for now.

Last edited 3 weeks ago by SergeyBiryukov (previous) (diff)

#7 in reply to: ↑ 6 ; follow-ups: @psykro
3 weeks ago

Replying to SergeyBiryukov:

Replying to psykro:

I tend to agree with that, my only suggested addition would be a) updating the document link and b) including one or two examples, which would (hopefully) lead developers to read the document.

The link was already updated to https://wordpress.org/support/article/debugging-in-wordpress/ in [46740].

WP_DEBUG_LOG creates a public log file, which would be a privacy concern. As mentioned in comment:33:ticket:28551, it could also overflow a user's available disk space if accidentally left enabled.

At a glance, it doesn't look like there are any "safe" examples that won't inadvertently slow down the site or introduce other negative effects if enabled without fully understanding the consequences, so I tend to think a link to the documentation should be enough for now.

I just wanted to make sure you saw that my examples were added in the comment block, not actually turning those constants on in the code. I agree that simply turning them on would be a bad thing, hence adding them to the comment block.

However if you did, but your concern is that adding them there would cause folks to inadvertently turn these things on without understanding the consequences, I'll keep my mouth shut :-)

#8 in reply to: ↑ 7 @davidnash
3 weeks ago

I'd like to thank everyone for looking into this. There are some subtler points I wasn't aware of (eg the disk filling up if file logging is left on!).

@wpgurudev I'd like to vote for your patch :-)

But @psykro's simple addition of define( 'WP_DEBUG_DISPLAY', false ); in the comments would be enough.

And at the risk of over-stating this, during my own theme/plugin development I've set WP_DEBUG to true but turned it off again because of all the output generated by other plugins. Which means I've probably contributed to the problem myself.

I think a small change like this could really help improve the quality of WordPress themes and plugins.

#9 in reply to: ↑ 7 @SergeyBiryukov
3 weeks ago

Replying to psykro:

I just wanted to make sure you saw that my examples were added in the comment block, not actually turning those constants on in the code. I agree that simply turning them on would be a bad thing, hence adding them to the comment block.

However if you did, but your concern is that adding them there would cause folks to inadvertently turn these things on without understanding the consequences, I'll keep my mouth shut :-)

Yes, that's exactly my concern, users trying out these settings without a proper consideration.

That's just my opinion though, happy to discuss this and explore more ideas :) Just wanted to note that these settings can sometimes be more nuanced than might seem at a glance.

For example, depending on PHP configuration, PHP warnings can be displayed regardless of the WP_DEBUG value. Seeing a comment like this:

// define( 'WP_DEBUG_DISPLAY', false ); - prevent the errors from showing in the HTML of pages

a user might want to try setting this to get rid of the warnings, without realizing it doesn't have any effect if WP_DEBUG is disabled, and would then be confused as to why it doesn't work as expected.

We could add some more comments to clarify this, but at that point, just linking to the documentation would probably make more sense.

#10 @psykro
3 weeks ago

Good point.

I think the "confusion" for developers comes in due to this line in the comment

It is strongly recommended that plugin and theme developers use WP_DEBUG in their development environments.

This would lead someone to assume that this is the only way to enable debugging. I agree that adding the link should suffice, but often folks don't get that far (which is an entirely different "problem" and in no way WordPress' one to solve.)

Therefore it might be useful to update the comment to make certain things clearer.

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * While it is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments, it is also important to understand how WP_DEBUG
 * works.
 *
 * Therefore, before just turning it on, please ensure to visit the documentation below
 * for information on other constants that can be used for debugging, in conjunction with 
 * WP_DEBUG.
 *
 * @link https://wordpress.org/support/article/debugging-in-wordpress/
 */
Last edited 3 weeks ago by psykro (previous) (diff)

#11 @afragen
3 weeks ago

Just an FYI, the WP Debugging plugin will do this for you.

Note: See TracTickets for help on using tickets.