ENHANCEMENT: Add Deprecation class to handle throwing deprecation notices nicely on methods that are still in use in framework or cms

_config.php

@@ -77,5 +77,7 @@ if (!is_dir($aggregatecachedir)) mkdir($aggregatecachedir);
 SS_Cache::add_backend('aggregatestore', 'File', array('cache_dir' => $aggregatecachedir));
 SS_Cache::pick_backend('aggregatestore', 'aggregate', 1000);
 
+Deprecation::notification_version('3.0.0-dev');
+
 // TODO Remove once new ManifestBuilder with submodule support is in place
 require_once('admin/_config.php');

dev/Deprecation.php

@@ -0,0 +1,161 @@
+<?php
+
+/**
+ * Handles raising an notice when accessing a deprecated method
+ *
+ * A pattern used in SilverStripe when deprecating a method is to add something like
+ *   user_error('This method is deprecated', E_USER_NOTICE);
+ * to the method
+ *
+ * However sometimes we want to mark that a method will be deprecated in some future version and shouldn't be used in
+ * new code, but not forbid in the current version - for instance when that method is still heavily used in framework
+ * or cms.
+ *
+ * This class abstracts the above pattern and adds a way to do that.
+ *
+ * Each call to notice passes a version that the notice will be valid from. Additionally this class has a notion of the
+ * version it should use when deciding whether to raise the notice. If that version is equal to or greater than the
+ * notices version (and SilverStripe is in dev mode) a deprecation message will be raised.
+ *
+ * Normally the checking version will be the release version of SilverStripe, but a developer can choose to set it to a
+ * future version, to see how their code will behave in future versions.
+ *
+ * Modules can also set the version for calls they make - either setting it to a future version in order to ensure
+ * forwards compatibility or setting it backwards if a module has not yet removed references to deprecated methods.
+ *
+ * When set per-module, only direct calls to deprecated methods from those modules are considered - if the module
+ * calls a non-module method which then calls a deprecated method, that call will use the global check version, not
+ * the module specific check version.
+ */
+class Deprecation {
+
+	protected static $version;
+
+	protected static $module_version_overrides = array();
+
+	/**
+	 * @var int - the notice level to raise on a deprecation notice. Defaults to E_USER_DEPRECATED if that exists,
+	 * E_USER_NOTICE if not
+	 */
+	public static $notice_level = null;
+
+	/**
+	 * Set the version that is used to check against the version passed to notice. If the ::notice version is
+	 * greater than or equal to this version, a message will be raised
+	 *
+	 * @static
+	 * @param $ver string -
+	 *     A php standard version string, see http://php.net/manual/en/function.version-compare.php for details.
+	 * @param null $forModule string -
+	 *    The name of a module. The passed version will be used as the check value for
+	 *    calls directly from this module rather than the global value
+	 * @return void
+	 */
+	public static function notification_version($ver, $forModule = null) {
+		if ($forModule) {
+			self::$module_version_overrides[$forModule] = $ver;
+		}
+		else {
+			self::$version = $ver;
+		}
+	}
+
+	/**
+	 * Given a backtrace, get the module name from the caller two removed (the caller of the method that called #notice)
+	 *
+	 * @static
+	 * @param $backtrace array - a backtrace as returned from debug_backtrace
+	 * @return string - the name of the module the call came from, or null if we can't determine
+	 */
+	protected static function get_calling_module_from_trace($backtrace) {
+		if (!isset($backtrace[1]['file'])) return;
+
+		$callingfile = $backtrace[1]['file'];
+
+		global $manifest;
+		foreach ($manifest->getModules() as $name => $path) {
+			if (strpos($callingfile, $path) === 0) {
+				return $name;
+			}
+		}
+	}
+
+	/**
+	 * Given a backtrace, get the method name from the immediate parent caller (the caller of #notice)
+	 *
+	 * @static
+	 * @param $backtrace array - a backtrace as returned from debug_backtrace
+	 * @return string - the name of the method
+	 */
+	protected static function get_called_method_from_trace($backtrace) {
+		$called = $backtrace[1];
+		
+		if (isset($called['class'])) {
+			return $called['class'] . $called['type'] . $called['function'];
+		}
+		else {
+			return $called['function'];
+		}
+	}
+
+	/**
+	 * 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
+	 * @return void
+	 */
+	public static function notice($atVersion, $string = '') {
+		if(!Director::isDev()) return;
+
+		$checkVersion = self::$version;
+		// Getting a backtrace is slow, so we only do it if we need it
+		$backtrace = null;
+
+		if(self::$module_version_overrides) {
+			$module = self::get_calling_module_from_trace($backtrace = debug_backtrace(0));
+			if(isset(self::$module_version_overrides[$module])) $checkVersion = self::$module_version_overrides[$module];
+		}
+
+		// Check the version against the notice version
+		if ($checkVersion && version_compare($checkVersion, $atVersion, '>=')) {
+			// Get the calling method
+			if (!$backtrace) $backtrace = debug_backtrace(0);
+			$caller = self::get_called_method_from_trace($backtrace);
+
+			// Get the level to raise the notice as
+			$level = self::$notice_level;
+			if (!$level) $level = defined(E_USER_DEPRECATED) ? E_USER_DEPRECATED : E_USER_NOTICE;
+
+			// Then raise the notice
+			user_error($caller.' is deprecated.'.($string ? ' '.$string : ''), $level);
+		}
+	}
+
+	/**
+	 * 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
+	 */
+	public static function dump_settings() {
+		return array(
+			'level' => self::$notice_level,
+			'version' => self::$version,
+			'moduleVersions' => self::$module_version_overrides
+		);
+	}
+
+	/**
+	 * 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
+	 */
+	public static function restore_settings($settings) {
+		self::$notice_level = $settings['level'];
+		self::$version = $settings['version'];
+		self::$module_version_overrides = $settings['moduleVersions'];
+	}
+
+}

tests/dev/DeprecationTest.php

@@ -0,0 +1,71 @@
+<?php
+
+class DeprecationTest_Deprecation extends Deprecation {
+	public static function get_module() {
+		return self::get_calling_module_from_trace(debug_backtrace(0));
+	}
+
+	public static function get_method() {
+		return self::get_called_method_from_trace(debug_backtrace(0));
+	}
+}
+
+class DeprecationTest extends SapphireTest {
+
+	static $originalVersionInfo;
+
+	function setUp() {
+		self::$originalVersionInfo = Deprecation::dump_settings();
+		Deprecation::$notice_level = E_USER_NOTICE;
+	}
+
+	function tearDown() {
+		Deprecation::restore_settings(self::$originalVersionInfo);
+	}
+
+	function testLesserVersionTriggersNoNotice() {
+		Deprecation::notification_version('1.0.0');
+		Deprecation::notice('2.0.0', 'Deprecation test failed');
+	}
+
+	/**
+    * @expectedException PHPUnit_Framework_Error_Notice
+	 */
+	function testEqualVersionTriggersNotice() {
+		Deprecation::notification_version('2.0.0');
+		Deprecation::notice('2.0.0', 'Deprecation test passed');
+	}
+
+	/**
+    * @expectedException PHPUnit_Framework_Error_Notice
+	 */
+	function testGreaterVersionTriggersNotice() {
+		Deprecation::notification_version('3.0.0');
+		Deprecation::notice('2.0.0', 'Deprecation test passed');
+	}
+
+	function testNonMatchingModuleNotifcationVersionDoesntAffectNotice() {
+		Deprecation::notification_version('1.0.0');
+		Deprecation::notification_version('3.0.0', 'mysite');
+		$this->callThatOriginatesFromSapphire();
+	}
+
+	/**
+    * @expectedException PHPUnit_Framework_Error_Notice
+	 */
+	function testMatchingModuleNotifcationVersionAffectsNotice() {
+		Deprecation::notification_version('1.0.0');
+		Deprecation::notification_version('3.0.0', 'sapphire');
+		$this->callThatOriginatesFromSapphire();
+	}
+
+	protected function callThatOriginatesFromSapphire() {
+		$this->assertEquals(DeprecationTest_Deprecation::get_module(), 'sapphire');
+		Deprecation::notice('2.0.0', 'Deprecation test passed');
+	}
+
+	function testMethodNameCalculation() {
+		$this->assertEquals(DeprecationTest_Deprecation::get_method(), 'DeprecationTest->testMethodNameCalculation');
+	}
+
+}