Setup: Deprecate StartProfiler, move default to DefaultSettings

$wgProfiler was introduced in 3ea576aa25 (r15605; 2006; MW 1.8).
The global was used from the Profiler.php class file, which
would be manually from StartProfiler.php, which then (if enabled)
assigned the global an actual instance of the Profiler class.

We needed it that way because we actually instantiated and used
the Profiler object (via wfProfileIn) very early on in WebStart.
Specifically, before any settings and classes load.

This first changed in 5a6d1ee2d3 (r86228; 2011; MW 1.17).
That commit deprecated use of $wgProfiler as an object in favour
of assigning it an array that MediaWiki would use to construct
the class. Profiling methods were also changed to lazy-instantiate
the class, which would first happen via a wfProfileIn() call two
lines before loading DefaultSettings and LocalSettings.

Some more relevant clean up happened in a0123d0549 (r89206; 2011).

Now, in 2018, we don't actually lazy-instantiate the Profiler
until after DefaultSetting and LocalSettings load. As such, I
think we can finally get rid of its out-of-bound load strategy.

Instead, we can simply set the default in DefaultSettings, and
recommend admins to set their value in LocalSettings.

Bug: T189966
Change-Id: I4e8dd9558132a5e38c22b26fed9c4b54cd324da7

StartProfiler.sample

@@ -1,38 +0,0 @@
-<?php
-
-/**
- * To use a profiler, copy this file to StartProfiler.php and add:
- *  $wgProfiler['class'] = 'ProfilerXhprof';
- *
- * For output, set the 'output' key to an array of class names, one for each
- * output type you want the profiler to generate. For example:
- *  $wgProfiler['output'] = array( 'ProfilerOutputText' );
- *
- * The output classes available to you by default are ProfilerOutputDb,
- * ProfilerOutputDump, ProfilerOutputStats, ProfilerOutputText, and
- * ProfilerOutputUdp.
- *
- * ProfilerOutputStats outputs profiling data as StatsD metrics. It expects
- * that you have set the $wgStatsdServer configuration variable to the host (or
- * host:port) of your statsd server.
- *
- * ProfilerOutputText will output profiling data in the page body as a comment.
- * You can make the profiling data in HTML render as part of the page content
- * by setting the 'visible' configuration flag:
- *  $wgProfiler['visible'] = true;
- *
- * 'ProfilerOutputDb' expects a database table that can be created by applying
- * maintenance/archives/patch-profiling.sql to your database.
- *
- * 'ProfilerOutputDump' expects a $wgProfiler['outputDir'] telling it where to
- * write dump files. The files produced are compatible with the XHProf gui.
- * For a rudimentary sampling profiler:
- *   $wgProfiler['class'] = 'ProfilerXhprof';
- *   $wgProfiler['output'] = array( 'ProfilerOutputDb' );
- *   $wgProfiler['sampling'] = 50; // one every 50 requests
- * This will use ProfilerStub for non-sampled cases.
- *
- * For performance, the profiler is always disabled for CLI scripts as they
- * could be long running and the data would accumulate. Use the '--profiler'
- * parameter of maintenance scripts to override this.
- */

includes/DefaultSettings.php

@@ -6066,7 +6066,7 @@ $wgUseTeX = false;
 /************************************************************************//**
  * @name   Profiling, testing and debugging
  *
- * To enable profiling, edit StartProfiler.php
+ * See $wgProfiler for how to enable profiling.
  *
  * @{
  */
@@ -6311,6 +6311,66 @@ $wgDevelopmentWarnings = false;
  */
 $wgDeprecationReleaseLimit = false;
 
+/**
+ * Profiler configuration.
+ *
+ * To use a profiler, set $wgProfiler in LocalSetings.php.
+ * For backwards-compatibility, it is also allowed to set the variable from
+ * a separate file called StartProfiler.php, which MediaWiki will include.
+ *
+ * Example:
+ *
+ * @code
+ *  $wgProfiler['class'] = ProfilerXhprof::class;
+ * @endcode
+ *
+ * For output, set the 'output' key to an array of class names, one for each
+ * output type you want the profiler to generate. For example:
+ *
+ * @code
+ *  $wgProfiler['output'] = [ ProfilerOutputText::class ];
+ * @endcode
+ *
+ * The output classes available to you by default are ProfilerOutputDb,
+ * ProfilerOutputDump, ProfilerOutputStats, ProfilerOutputText, and
+ * ProfilerOutputUdp.
+ *
+ * ProfilerOutputStats outputs profiling data as StatsD metrics. It expects
+ * that you have set the $wgStatsdServer configuration variable to the host (or
+ * host:port) of your statsd server.
+ *
+ * ProfilerOutputText will output profiling data in the page body as a comment.
+ * You can make the profiling data in HTML render as part of the page content
+ * by setting the 'visible' configuration flag:
+ *
+ * @code
+ *  $wgProfiler['visible'] = true;
+ * @endcode
+ *
+ * 'ProfilerOutputDb' expects a database table that can be created by applying
+ * maintenance/archives/patch-profiling.sql to your database.
+ *
+ * 'ProfilerOutputDump' expects a $wgProfiler['outputDir'] telling it where to
+ * write dump files. The files produced are compatible with the XHProf gui.
+ * For a rudimentary sampling profiler:
+ *
+ * @code
+ *   $wgProfiler['class'] = 'ProfilerXhprof';
+ *   $wgProfiler['output'] = array( 'ProfilerOutputDb' );
+ *   $wgProfiler['sampling'] = 50; // one every 50 requests
+ * @endcode
+ *
+ * When using the built-in `sampling` option, the `class` will changed to
+ * ProfilerStub for non-sampled cases.
+ *
+ * For performance, the profiler is always disabled for CLI scripts as they
+ * could be long running and the data would accumulate. Use the '--profiler'
+ * parameter of maintenance scripts to override this.
+ *
+ * @since 1.17.0
+ */
+$wgProfiler = [];
+
 /**
  * Only record profiling info for pages that took longer than this
  * @deprecated since 1.25: set $wgProfiler['threshold'] instead.

includes/Setup.php

@@ -37,12 +37,6 @@ if ( !defined( 'MEDIAWIKI' ) ) {
  * Pre-config setup: Before loading LocalSettings.php
  */
 
-// Get profiler configuraton
-$wgProfiler = [];
-if ( file_exists( "$IP/StartProfiler.php" ) ) {
-	require "$IP/StartProfiler.php";
-}
-
 // Start the autoloader, so that extensions can derive classes from core files
 require_once "$IP/includes/AutoLoader.php";
 
@@ -85,6 +79,11 @@ MediaWiki\HeaderCallback::register();
  * Load LocalSettings.php
  */
 
+if ( is_readable( "$IP/StartProfiler.php" ) ) {
+	// @deprecated since 1.31: Use LocalSettings.php instead.
+	require "$IP/StartProfiler.php";
+}
+
 if ( defined( 'MW_CONFIG_CALLBACK' ) ) {
 	call_user_func( MW_CONFIG_CALLBACK );
 } else {

tests/phpunit/autoload.ide.php

@@ -37,12 +37,6 @@ $maintenance->setup();
 // We used to call this variable $self, but it was moved
 // to $maintenance->mSelf. Keep that here for b/c
 $self = $maintenance->getName();
-global $IP;
-# Get profiler configuraton
-$wgProfiler = [];
-if ( file_exists( "$IP/StartProfiler.php" ) ) {
-	require "$IP/StartProfiler.php";
-}
 # Start the autoloader, so that extensions can derive classes from core files
 require_once "$IP/includes/AutoLoader.php";