From 5209adff6cf13a002843347d5e3942aeb5c255ce Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Sun, 18 Mar 2018 18:21:02 -0700
Subject: [PATCH] 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           | 38 ---------------------
 includes/DefaultSettings.php   | 62 +++++++++++++++++++++++++++++++++-
 includes/Setup.php             | 11 +++---
 tests/phpunit/autoload.ide.php |  6 ----
 4 files changed, 66 insertions(+), 51 deletions(-)
 delete mode 100644 StartProfiler.sample

diff --git a/StartProfiler.sample b/StartProfiler.sample
deleted file mode 100644
index bdf21396e2..0000000000
--- a/StartProfiler.sample
+++ /dev/null
@@ -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.
- */
diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index 81d3c35d29..4599105578 100644
--- a/includes/DefaultSettings.php
+++ b/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.
diff --git a/includes/Setup.php b/includes/Setup.php
index cc6915a74b..ac47b6f87b 100644
--- a/includes/Setup.php
+++ b/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 {
diff --git a/tests/phpunit/autoload.ide.php b/tests/phpunit/autoload.ide.php
index 4b0b1873ab..f8a745ee48 100644
--- a/tests/phpunit/autoload.ide.php
+++ b/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";
 
-- 
2.20.1