API Disable deprecation notices by default

dev/Deprecation.php

@@ -42,6 +42,19 @@ class Deprecation {
 	 */
 	protected static $version;
 
+	/**
+	 * Override whether deprecation is enabled. If null, then fallback to 
+	 * SS_DEPRECATION_ENABLED, and then true if not defined.
+	 * 
+	 * Deprecation is only available on dev.
+	 * 
+	 * Must be configured outside of the config API, as deprecation API 
+	 * must be available before this to avoid infinite loops.
+	 *
+	 * @var boolean|null
+	 */
+	protected static $enabled = null;
+
 	/**
 	 *
 	 * @var array
@@ -116,20 +129,47 @@ class Deprecation {
 			return $called['function'];
 		}
 	}
+	
+	/**
+	 * Determine if deprecation notices should be displayed
+	 * 
+	 * @return bool
+	 */
+	public static function get_enabled() {
+		// Deprecation is only available on dev
+		if(!Director::isDev()) {
+			return false;
+		}
+		if(isset(self::$enabled)) {
+			return self::$enabled;
+		}
+		if(defined('SS_DEPRECATION_ENABLED')) {
+			return SS_DEPRECATION_ENABLED;
+		}
+		return true;
+	}
+
+	/**
+	 * Toggle on or off deprecation notices. Will be ignored in live.
+	 * 
+	 * @param bool $enabled
+	 */
+	public static function set_enabled($enabled) {
+		self::$enabled = $enabled;
+	}
 
 	/**
 	 * Raise a notice indicating the method is deprecated if the version passed as the second argument is greater
 	 * than or equal to the check version set via ::notification_version
 	 *
-	 * @static
-	 * @param $string - The notice to raise
-	 * @param $atVersion - The version at which this notice should start being raised
-	 * @param Boolean $scope - Notice relates to the method or class context its called in.
-	 * @return void
+	 * @param string $atVersion The version at which this notice should start being raised
+	 * @param string $string The notice to raise
+	 * @param bool $scope Notice relates to the method or class context its called in.
 	 */
 	public static function notice($atVersion, $string = '', $scope = Deprecation::SCOPE_METHOD) {
-		// Never raise deprecation notices in a live environment
-		if(Director::isLive(true)) return;
+		if(!static::get_enabled()) {
+			return;
+		}
 
 		$checkVersion = self::$version;
 		// Getting a backtrace is slow, so we only do it if we need it
@@ -179,25 +219,27 @@ class Deprecation {
 
 	/**
 	 * Method for when testing. Dump all the current version settings to a variable for later passing to restore
-	 * @return array - opaque array that should only be used to pass to ::restore_version_settings
+	 * 
+	 * @return array Opaque array that should only be used to pass to {@see Deprecation::restore_settings()}
 	 */
 	public static function dump_settings() {
 		return array(
 			'level' => self::$notice_level,
 			'version' => self::$version,
-			'moduleVersions' => self::$module_version_overrides
+			'moduleVersions' => self::$module_version_overrides,
+			'enabled' => self::$enabled,
 		);
 	}
 
 	/**
 	 * Method for when testing. Restore all the current version settings from a variable
-	 * @static
-	 * @param $settings array - An array as returned by ::dump_version_settings
-	 * @return void
+	 * 
+	 * @param $settings array An array as returned by {@see Deprecation::dump_settings()}
 	 */
 	public static function restore_settings($settings) {
 		self::$notice_level = $settings['level'];
 		self::$version = $settings['version'];
 		self::$module_version_overrides = $settings['moduleVersions'];
+		self::$enabled = $settings['enabled'];
 	}
 }

docs/en/00_Getting_Started/03_Environment_Management.md

@@ -116,6 +116,7 @@ This is my `_ss_environment.php` file. I have it placed in `/var`, as each of th
 | `SS_DATABASE_TIMEZONE`| Set the database timezone to something other than the system timezone.
 | `SS_DATABASE_NAME` | Set the database name. Assumes the `$database` global variable in your config is missing or empty. |
 | `SS_DATABASE_CHOOSE_NAME`| Boolean/Int.  If defined, then the system will choose a default database name for you if one isn't give in the $database variable.  The database name will be "SS_" followed by the name of the folder into which you have installed SilverStripe.  If this is enabled, it means that the phpinstaller will work out of the box without the installer needing to alter any files.  This helps prevent accidental changes to the environment. If `SS_DATABASE_CHOOSE_NAME` is an integer greater than one, then an ancestor folder will be used for the  database name.  This is handy for a site that's hosted from /sites/examplesite/www or /buildbot/allmodules-2.3/build. If it's 2, the parent folder will be chosen; if it's 3 the grandparent, and so on.|
+| `SS_DEPRECATION_ENABLED` | Enable deprecation notices for this environment.|
 | `SS_ENVIRONMENT_TYPE`| The environment type: dev, test or live.|
 | `SS_DEFAULT_ADMIN_USERNAME`| The username of the default admin. This is a user with administrative privileges.|
 | `SS_DEFAULT_ADMIN_PASSWORD`| The password of the default admin. This will not be stored in the database.|

docs/en/04_Changelogs/3.2.0.md

@@ -73,6 +73,8 @@
 * Security: The multiple authenticator login page should now be styled manually - i.e. without the default jQuery
   UI layout. A new template, Security_MultiAuthenticatorLogin.ss is available.
 * Security: This controller's templates can be customised by overriding the `getTemplatesFor` function.
+* `Deprecation::set_enabled()` or `SS_DEPRECATION_ENABLED` can now be used to
+  enable or disable deprecation notices. Deprecation notices are no longer displayed on test.
 * API: Form and FormField ID attributes rewritten.
 * `SearchForm::getSearchQuery` no longer pre-escapes search keywords and must
   be cast in your template

docs/en/05_Contributing/02_Release_Process.md

@@ -80,6 +80,25 @@ Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::i
 This change could be committed to a minor release like *3.2.0*, and stays deprecated in all following minor releases
 (e.g. *3.3.0*, *3.4.0*), until a new major release (e.g. *4.0.0*) where it gets removed from the codebase. 
 
+Deprecation notices are enabled by default on dev environment, but can be
+turned off via either _ss_environment.php or in your _config.php. Deprecation
+notices are always disabled on both live and test.
+
+
+`mysite/_config.php`
+
+
+    :::php
+    Deprecation::set_enabled(false);
+
+
+`_ss_environment.php`
+
+
+    :::php
+    define('SS_DEPRECATION_ENABLED', false);
+
+
 ## Security Releases
 
 ### Reporting an issue

tests/control/ControllerTest.php

@@ -11,6 +11,18 @@ class ControllerTest extends FunctionalTest {
 			'ControllerTest_AccessBaseControllerExtension'
 		)
 	);
+	
+	protected $depSettings = null;
+
+	public function setUp() {
+		parent::setUp();
+		$this->depSettings = Deprecation::dump_settings();
+	}
+
+	public function tearDown() {
+		Deprecation::restore_settings($this->depSettings);
+		parent::tearDown();
+	}
 
 	public function testDefaultAction() {
 		/* For a controller with a template, the default action will simple run that template. */
@@ -208,6 +220,7 @@ class ControllerTest extends FunctionalTest {
 	 * @expectedExceptionMessage Wildcards (*) are no longer valid
 	 */
 	public function testWildcardAllowedActions() {
+		Deprecation::set_enabled(true);
 		$this->get('ControllerTest_AccessWildcardSecuredController');
 	}
 

tests/core/ConfigTest.php

@@ -82,6 +82,19 @@ class ConfigTest_TestNest extends Object implements TestOnly {
 }
 
 class ConfigTest extends SapphireTest {
+	
+	protected $depSettings = null;
+	
+	public function setUp() {
+		parent::setUp();
+		$this->depSettings = Deprecation::dump_settings();
+		Deprecation::set_enabled(false);
+	}
+	
+	public function tearDown() {
+		Deprecation::restore_settings($this->depSettings);
+		parent::tearDown();
+	}
 
 	public function testNest() {
 
@@ -282,12 +295,6 @@ class ConfigTest extends SapphireTest {
 	}
 
 	public function testLRUDiscarding() {
-		$depSettings = Deprecation::dump_settings();
-		Deprecation::restore_settings(array(
-			'level' => false,
-			'version' => false,
-			'moduleVersions' => false,
-		));
 		$cache = new ConfigTest_Config_LRU();
 		for ($i = 0; $i < Config_LRU::SIZE*2; $i++) $cache->set($i, $i);
 		$this->assertEquals(
@@ -301,16 +308,9 @@ class ConfigTest extends SapphireTest {
 			Config_LRU::SIZE, count($cache->indexing),
 			'Heterogenous usage gives sufficient discarding'
 		);
-		Deprecation::restore_settings($depSettings);
 	}
 
 	public function testLRUCleaning() {
-		$depSettings = Deprecation::dump_settings();
-		Deprecation::restore_settings(array(
-			'level' => false,
-			'version' => false,
-			'moduleVersions' => false,
-		));
 		$cache = new ConfigTest_Config_LRU();
 		for ($i = 0; $i < Config_LRU::SIZE; $i++) $cache->set($i, $i);
 		$this->assertEquals(Config_LRU::SIZE, count($cache->indexing));
@@ -327,7 +327,6 @@ class ConfigTest extends SapphireTest {
 		$cache->clean('Bar');
 		$this->assertEquals(0, count($cache->indexing), 'Clean items with any single matching tag');
 		$this->assertFalse($cache->get(1), 'Clean items with any single matching tag');
-		Deprecation::restore_settings($depSettings);
 	}
 }
 

tests/dev/DeprecationTest.php

@@ -15,12 +15,16 @@ class DeprecationTest extends SapphireTest {
 	static $originalVersionInfo;
 
 	public function setUp() {
+		parent::setUp();
+		
 		self::$originalVersionInfo = Deprecation::dump_settings();
 		Deprecation::$notice_level = E_USER_NOTICE;
+		Deprecation::set_enabled(true);
 	}
 
 	public function tearDown() {
 		Deprecation::restore_settings(self::$originalVersionInfo);
+		parent::tearDown();
 	}
 
 	public function testLesserVersionTriggersNoNotice() {