Enhance the destination control parameter of wfDebug() and wfDebugLog()

- The parameter is now a string, making is more understandable than
  boolean values
- It takes the same values in both wfDebug() and wfDebugLog() (except
  for 'private' which is only used in the latter)
- This adds a new possibility to wfDebugLog() to log the message either
  on the specific log or the general one, but not to the debug toolbar
- Old boolean values are still recognised for backward compatibility
- Also send the messages passed to wfDebugLog() to the debug toolbar
  when they are written to a specific log and not restricted to logs
- Updated the calls of and wfDebug() and wfDebugLog() with the last
  parameter to change it into a string
- Renamed MWDebug::sendWarning() to MWDebug::sendMessage() and added
  $group parameter to it; will not break anything since that method
  is marked as private
- Changed the call to wfDebug() from MWDebug::sendMessage() to use
  wfDebugLog() with 'log' as thrid parameter, so that those messages
  can be logged separately from the main log and they don't show up
  a second time on the "debug log" tab of the debug toolbar

Change-Id: I1be09d4c1d3408ed5b26a5db02691c17c0ec0926

includes/AjaxResponse.php

@@ -220,7 +220,7 @@ class AjaxResponse {
 		}
 
 		if ( !$wgCachePages ) {
-			wfDebug( "$fname: CACHE DISABLED\n", false );
+			wfDebug( "$fname: CACHE DISABLED\n", 'log' );
 			return false;
 		}
 
@@ -234,8 +234,8 @@ class AjaxResponse {
 			$modsince = preg_replace( '/;.*$/', '', $_SERVER["HTTP_IF_MODIFIED_SINCE"] );
 			$modsinceTime = strtotime( $modsince );
 			$ismodsince = wfTimestamp( TS_MW, $modsinceTime ? $modsinceTime : 1 );
-			wfDebug( "$fname: -- client send If-Modified-Since: " . $modsince . "\n", false );
-			wfDebug( "$fname: --  we might send Last-Modified : $lastmod\n", false );
+			wfDebug( "$fname: -- client send If-Modified-Since: " . $modsince . "\n", 'log' );
+			wfDebug( "$fname: --  we might send Last-Modified : $lastmod\n", 'log' );
 
 			if ( ( $ismodsince >= $timestamp ) && $wgUser->validateCache( $ismodsince ) && $ismodsince >= $wgCacheEpoch ) {
 				ini_set( 'zlib.output_compression', 0 );
@@ -243,15 +243,15 @@ class AjaxResponse {
 				$this->disable();
 				$this->mLastModified = $lastmod;
 
-				wfDebug( "$fname: CACHED client: $ismodsince ; user: {$wgUser->getTouched()} ; page: $timestamp ; site $wgCacheEpoch\n", false );
+				wfDebug( "$fname: CACHED client: $ismodsince ; user: {$wgUser->getTouched()} ; page: $timestamp ; site $wgCacheEpoch\n", 'log' );
 
 				return true;
 			} else {
-				wfDebug( "$fname: READY  client: $ismodsince ; user: {$wgUser->getTouched()} ; page: $timestamp ; site $wgCacheEpoch\n", false );
+				wfDebug( "$fname: READY  client: $ismodsince ; user: {$wgUser->getTouched()} ; page: $timestamp ; site $wgCacheEpoch\n", 'log' );
 				$this->mLastModified = $lastmod;
 			}
 		} else {
-			wfDebug( "$fname: client did not send If-Modified-Since header\n", false );
+			wfDebug( "$fname: client did not send If-Modified-Since header\n", 'log' );
 			$this->mLastModified = $lastmod;
 		}
 		return false;

includes/Exception.php

@@ -908,7 +908,7 @@ class MWExceptionHandler {
 
 			$json = self::jsonSerializeException( $e, false, FormatJson::ALL_OK );
 			if ( $json !== false ) {
-				wfDebugLog( 'exception-json', $json, false );
+				wfDebugLog( 'exception-json', $json, 'private' );
 			}
 		}
 

includes/GlobalFunctions.php

@@ -924,21 +924,33 @@ function wfMatchesDomainList( $url, $domains ) {
  * $wgDebugComments - if on, some debug items may appear in comments in the HTML output.
  *
  * @param $text String
- * @param bool $logonly set true to avoid appearing in HTML when $wgDebugComments is set
+ * @param string|bool $dest Destination of the message:
+ *     - 'all': both to the log and HTML (debug toolbar or HTML comments)
+ *     - 'log': only to the log and not in HTML
+ *   For backward compatibility, it can also take a boolean:
+ *     - true: same as 'all'
+ *     - false: same as 'log'
  */
-function wfDebug( $text, $logonly = false ) {
+function wfDebug( $text, $dest = 'all' ) {
 	global $wgDebugLogFile, $wgProfileOnly, $wgDebugRawPage, $wgDebugLogPrefix;
 
 	if ( !$wgDebugRawPage && wfIsDebugRawPage() ) {
 		return;
 	}
 
+	// Turn $dest into a string if it's a boolean (for b/c)
+	if ( $dest === true ) {
+		$dest = 'all';
+	} elseif ( $dest === false ) {
+		$dest = 'log';
+	}
+
 	$timer = wfDebugTimer();
 	if ( $timer !== '' ) {
 		$text = preg_replace( '/[^\n]/', $timer . '\0', $text, 1 );
 	}
 
-	if ( !$logonly ) {
+	if ( $dest === 'all' ) {
 		MWDebug::debugMsg( $text );
 	}
 
@@ -1019,18 +1031,38 @@ function wfDebugMem( $exact = false ) {
  * @param $text String
  * @param bool $public whether to log the event in the public log if no private
  *                     log file is specified, (default true)
+ * @param string|bool $dest Destination of the message:
+ *     - 'all': both to the log and HTML (debug toolbar or HTML comments)
+ *     - 'log': only to the log and not in HTML
+ *     - 'private': only to the specifc log if set in $wgDebugLogGroups and
+ *       discarded otherwise
+ *   For backward compatibility, it can also take a boolean:
+ *     - true: same as 'all'
+ *     - false: same as 'private'
  */
-function wfDebugLog( $logGroup, $text, $public = true ) {
+function wfDebugLog( $logGroup, $text, $dest = 'all' ) {
 	global $wgDebugLogGroups;
+
 	$text = trim( $text ) . "\n";
 
+	// Turn $dest into a string if it's a boolean (for b/c)
+	if ( $dest === true ) {
+		$dest = 'all';
+	} elseif ( $dest === false ) {
+		$dest = 'private';
+	}
+
 	if ( !isset( $wgDebugLogGroups[$logGroup] ) ) {
-		if ( $public === true ) {
-			wfDebug( "[$logGroup] $text", false );
+		if ( $dest !== 'private' ) {
+			wfDebug( "[$logGroup] $text", $dest );
 		}
 		return;
 	}
 
+	if ( $dest === 'all' ) {
+		MWDebug::debugMsg( "[$logGroup] $text" );
+	}
+
 	$logConfig = $wgDebugLogGroups[$logGroup];
 	if ( is_array( $logConfig ) ) {
 		if ( isset( $logConfig['sample'] ) && mt_rand( 1, $logConfig['sample'] ) !== 1 ) {

includes/OutputPage.php

@@ -685,7 +685,7 @@ class OutputPage extends ContextSource {
 			return false;
 		}
 		if ( !$wgCachePages ) {
-			wfDebug( __METHOD__ . ": CACHE DISABLED\n", false );
+			wfDebug( __METHOD__ . ": CACHE DISABLED\n", 'log' );
 			return false;
 		}
 
@@ -706,7 +706,7 @@ class OutputPage extends ContextSource {
 
 		$clientHeader = $this->getRequest()->getHeader( 'If-Modified-Since' );
 		if ( $clientHeader === false ) {
-			wfDebug( __METHOD__ . ": client did not send If-Modified-Since header\n", false );
+			wfDebug( __METHOD__ . ": client did not send If-Modified-Since header\n", 'log' );
 			return false;
 		}
 
@@ -734,17 +734,17 @@ class OutputPage extends ContextSource {
 		}
 
 		wfDebug( __METHOD__ . ": client sent If-Modified-Since: " .
-			wfTimestamp( TS_ISO_8601, $clientHeaderTime ) . "\n", false );
+			wfTimestamp( TS_ISO_8601, $clientHeaderTime ) . "\n", 'log' );
 		wfDebug( __METHOD__ . ": effective Last-Modified: " .
-			wfTimestamp( TS_ISO_8601, $maxModified ) . "\n", false );
+			wfTimestamp( TS_ISO_8601, $maxModified ) . "\n", 'log' );
 		if ( $clientHeaderTime < $maxModified ) {
-			wfDebug( __METHOD__ . ": STALE, $info\n", false );
+			wfDebug( __METHOD__ . ": STALE, $info\n", 'log' );
 			return false;
 		}
 
 		# Not modified
 		# Give a 304 response code and disable body output
-		wfDebug( __METHOD__ . ": NOT MODIFIED, $info\n", false );
+		wfDebug( __METHOD__ . ": NOT MODIFIED, $info\n", 'log' );
 		ini_set( 'zlib.output_compression', 0 );
 		$this->getRequest()->response()->header( "HTTP/1.1 304 Not Modified" );
 		$this->sendCacheControl();
@@ -1919,7 +1919,7 @@ class OutputPage extends ContextSource {
 					# We'll purge the proxy cache explicitly, but require end user agents
 					# to revalidate against the proxy on each visit.
 					# Surrogate-Control controls our Squid, Cache-Control downstream caches
-					wfDebug( __METHOD__ . ": proxy caching with ESI; {$this->mLastModified} **\n", false );
+					wfDebug( __METHOD__ . ": proxy caching with ESI; {$this->mLastModified} **\n", 'log' );
 					# start with a shorter timeout for initial testing
 					# header( 'Surrogate-Control: max-age=2678400+2678400, content="ESI/1.0"');
 					$response->header( 'Surrogate-Control: max-age=' . $wgSquidMaxage . '+' . $this->mSquidMaxage . ', content="ESI/1.0"' );
@@ -1929,7 +1929,7 @@ class OutputPage extends ContextSource {
 					# to revalidate against the proxy on each visit.
 					# IMPORTANT! The Squid needs to replace the Cache-Control header with
 					# Cache-Control: s-maxage=0, must-revalidate, max-age=0
-					wfDebug( __METHOD__ . ": local proxy caching; {$this->mLastModified} **\n", false );
+					wfDebug( __METHOD__ . ": local proxy caching; {$this->mLastModified} **\n", 'log' );
 					# start with a shorter timeout for initial testing
 					# header( "Cache-Control: s-maxage=2678400, must-revalidate, max-age=0" );
 					$response->header( 'Cache-Control: s-maxage=' . $this->mSquidMaxage . ', must-revalidate, max-age=0' );
@@ -1937,7 +1937,7 @@ class OutputPage extends ContextSource {
 			} else {
 				# We do want clients to cache if they can, but they *must* check for updates
 				# on revisiting the page.
-				wfDebug( __METHOD__ . ": private caching; {$this->mLastModified} **\n", false );
+				wfDebug( __METHOD__ . ": private caching; {$this->mLastModified} **\n", 'log' );
 				$response->header( 'Expires: ' . gmdate( 'D, d M Y H:i:s', 0 ) . ' GMT' );
 				$response->header( "Cache-Control: private, must-revalidate, max-age=0" );
 			}
@@ -1945,7 +1945,7 @@ class OutputPage extends ContextSource {
 				$response->header( "Last-Modified: {$this->mLastModified}" );
 			}
 		} else {
-			wfDebug( __METHOD__ . ": no caching **\n", false );
+			wfDebug( __METHOD__ . ": no caching **\n", 'log' );
 
 			# In general, the absence of a last modified header should be enough to prevent
 			# the client from using its cache. We send a few other things just to make sure.

includes/api/ApiMain.php

@@ -899,7 +899,7 @@ class ApiMain extends ApiBase {
 			}
 		}
 		$s .= "\n";
-		wfDebugLog( 'api', $s, false );
+		wfDebugLog( 'api', $s, 'private' );
 	}
 
 	/**

includes/cache/HTMLFileCache.php

@@ -166,7 +166,7 @@ class HTMLFileCache extends FileCacheBase {
 			return $text;
 		}
 
-		wfDebug( __METHOD__ . "()\n", false );
+		wfDebug( __METHOD__ . "()\n", 'log' );
 
 		$now = wfTimestampNow();
 		if ( $this->useGzip() ) {

includes/debug/Debug.php

@@ -134,7 +134,7 @@ class MWDebug {
 	 * @since 1.19
 	 * @param $msg string
 	 * @param $callerOffset int
-	 * @param $level int A PHP error level. See sendWarning()
+	 * @param $level int A PHP error level. See sendMessage()
 	 * @param $log string: 'production' will always trigger a php error, 'auto'
 	 *        will trigger an error if $wgDevelopmentWarnings is true, and 'debug'
 	 *        will only write to the debug log(s).
@@ -154,7 +154,7 @@ class MWDebug {
 
 		$callerDescription = self::getCallerDescription( $callerOffset );
 
-		self::sendWarning( $msg, $callerDescription, $level );
+		self::sendMessage( $msg, $callerDescription, 'warning', $level );
 
 		if ( self::$enabled ) {
 			self::$log[] = array(
@@ -228,9 +228,10 @@ class MWDebug {
 
 		if ( $sendToLog ) {
 			global $wgDevelopmentWarnings; // we could have a more specific $wgDeprecationWarnings setting.
-			self::sendWarning(
+			self::sendMessage(
 				$msg,
 				$callerDescription,
+				'deprecated',
 				$wgDevelopmentWarnings ? E_USER_DEPRECATED : false
 			);
 		}
@@ -287,21 +288,22 @@ class MWDebug {
 	}
 
 	/**
-	 * Send a warning to the debug log and optionally also trigger a PHP
+	 * Send a message to the debug log and optionally also trigger a PHP
 	 * error, depending on the $level argument.
 	 *
 	 * @param $msg string Message to send
 	 * @param $caller array caller description get from getCallerDescription()
+	 * @param $group string log group on which to send the message
 	 * @param $level int|bool error level to use; set to false to not trigger an error
 	 */
-	private static function sendWarning( $msg, $caller, $level ) {
+	private static function sendMessage( $msg, $caller, $group, $level ) {
 		$msg .= ' [Called from ' . $caller['func'] . ' in ' . $caller['file'] . ']';
 
 		if ( $level !== false ) {
 			trigger_error( $msg, $level );
 		}
 
-		wfDebug( "$msg\n" );
+		wfDebugLog( $group, $msg, 'log' );
 	}
 
 	/**

includes/specials/SpecialSearch.php

@@ -199,7 +199,7 @@ class SpecialSearch extends SpecialPage {
 		if ( !is_null( $t ) ) {
 			global $wgGoToEdit;
 			wfRunHooks( 'SpecialSearchNogomatch', array( &$t ) );
-			wfDebugLog( 'nogomatch', $t->getText(), false );
+			wfDebugLog( 'nogomatch', $t->getText(), 'private' );
 
 			# If the feature is enabled, go straight to the edit page
 			if ( $wgGoToEdit ) {