/**
* Standard Debugging Function
*
* Returns true if the current site debugging settings are equal or above specified level.
* If passed a parameter it will emit a debugging notice similar to trigger_error(). The
* routing of notices is controlled by $CFG->debugdisplay
* eg use like this:
*
* 1) debugging('a normal debug notice');
* 2) debugging('something really picky', DEBUG_ALL);
* 3) debugging('annoying debug message only for developers', DEBUG_DEVELOPER);
* 4) if (debugging()) { perform extra debugging operations (do not use print or echo) }
*
* In code blocks controlled by debugging() (such as example 4)
* any output should be routed via debugging() itself, or the lower-level
* trigger_error() or error_log(). Using echo or print will break XHTML
* JS and HTTP headers.
*
* It is also possible to define NO_DEBUG_DISPLAY which redirects the message to error_log.
*
* @param string $message a message to print
* @param int $level the level at which this debugging statement should show
* @param array $backtrace use different backtrace
* @return bool
*/
function debugging($message = '', $level = DEBUG_NORMAL, $backtrace = null)
{
global $CFG, $USER;
$forcedebug = false;
if (!empty($CFG->debugusers) && $USER) {
$debugusers = explode(',', $CFG->debugusers);
$forcedebug = in_array($USER->id, $debugusers);
}
if (!$forcedebug and empty($CFG->debug) || ($CFG->debug != -1 and $CFG->debug < $level)) {
return false;
}
if (!isset($CFG->debugdisplay)) {
$CFG->debugdisplay = ini_get_bool('display_errors');
}
if ($message) {
if (!$backtrace) {
$backtrace = debug_backtrace();
}
$from = format_backtrace($backtrace, CLI_SCRIPT || NO_DEBUG_DISPLAY);
if (PHPUNIT_TEST) {
if (phpunit_util::debugging_triggered($message, $level, $from)) {
// We are inside test, the debug message was logged.
return true;
}
}
if (NO_DEBUG_DISPLAY) {
// Script does not want any errors or debugging in output,
// we send the info to error log instead.
error_log('Debugging: ' . $message . ' in ' . PHP_EOL . $from);
} else {
if ($forcedebug or $CFG->debugdisplay) {
if (!defined('DEBUGGING_PRINTED')) {
define('DEBUGGING_PRINTED', 1);
// Indicates we have printed something.
}
if (CLI_SCRIPT) {
echo "++ {$message} ++\n{$from}";
} else {
echo '<div class="notifytiny debuggingmessage" data-rel="debugging">', $message, $from, '</div>';
}
} else {
trigger_error($message . $from, E_USER_NOTICE);
}
}
}
return true;
}
