ENH Do not output core code deprecation messages by default

composer.json

@@ -38,6 +38,7 @@
         "sebastian/diff": "^4.0",
         "silverstripe/config": "^2",
         "silverstripe/assets": "^2.3",
+        "silverstripe/supported-modules": "^1",
         "silverstripe/vendor-plugin": "^2",
         "sminnee/callbacklist": "^0.1.1",
         "symfony/cache": "^6.1",

src/Control/Controller.php

@@ -19,7 +19,6 @@
  */
 class Controller extends RequestHandler implements TemplateGlobalProvider
 {
-
     /**
      * An array of arguments extracted from the URL.
      *

src/Dev/Deprecation.php

@@ -3,11 +3,13 @@
 namespace SilverStripe\Dev;
 
 use BadMethodCallException;
+use RuntimeException;
 use SilverStripe\Control\Director;
 use SilverStripe\Core\Environment;
 use SilverStripe\Core\Injector\InjectionCreator;
 use SilverStripe\Core\Injector\InjectorLoader;
 use SilverStripe\Core\Manifest\Module;
+use SilverStripe\Core\Path;
 
 /**
  * Handles raising an notice when accessing a deprecated method, class, configuration, or behaviour.
@@ -77,6 +79,18 @@ class Deprecation
      */
     private static bool $showNoReplacementNotices = false;
 
+    /**
+     * @internal
+     */
+    private static bool $showNoticesCalledFromSupportedCode = false;
+
+    /**
+     * Cache of supported module directories, read from silverstripe/supported-modules repositories.json
+     *
+     * @internal
+     */
+    private static array $supportedModuleDirectories = [];
+
     /**
      * Enable throwing deprecation warnings. By default, this excludes warnings for
      * deprecated code which is called by core Silverstripe modules.
@@ -146,6 +160,12 @@ protected static function get_called_method_from_trace($backtrace, $level = 1)
         if (!$level) {
             $level = 1;
         }
+        $called = Deprecation::get_called_from_trace($backtrace, $level);
+        return ($called['class'] ?? '') . ($called['type'] ?? '') . ($called['function'] ?? '');
+    }
+
+    private static function get_called_from_trace(array $backtrace, int $level): array
+    {
         $newLevel = $level;
         // handle closures inside withSuppressedNotice()
         if (Deprecation::$insideNoticeSuppression
@@ -163,8 +183,59 @@ protected static function get_called_method_from_trace($backtrace, $level = 1)
         if ($level == 4 && ($backtrace[$newLevel]['class'] ?? '') === InjectionCreator::class) {
             $newLevel = $newLevel + 4;
         }
+        // handle noticeWithNoReplacment()
+        foreach ($backtrace as $trace) {
+            if (($trace['class'] ?? '') === Deprecation::class
+                && ($trace['function'] ?? '') === 'noticeWithNoReplacment'
+            ) {
+                $newLevel = $newLevel + 1;
+                break;
+            }
+        }
         $called = $backtrace[$newLevel] ?? [];
-        return ($called['class'] ?? '') . ($called['type'] ?? '') . ($called['function'] ?? '');
+        return $called;
+    }
+
+    private static function isCalledFromSupportedCode(array $backtrace): bool
+    {
+        $called = Deprecation::get_called_from_trace($backtrace, 1);
+        $file = $called['file'] ?? '';
+        if (!$file) {
+            return false;
+        }
+        return Deprecation::fileIsInSupportedModule($file);
+    }
+
+    /**
+     * Check whether a file (path to file) is in a supported module
+     */
+    public static function fileIsInSupportedModule(string $file): bool
+    {
+        // Cache the supported modules list
+        if (count(Deprecation::$supportedModuleDirectories) === 0) {
+            // Manually load the supported modules list rather than use MetaData::getAllRepositoryMetaData()
+            // because we do not want to make a network request which could slow down a website
+            // While there is a small risk of the list being out of date, there is minimal downside to this
+            $path = Path::join(BASE_PATH, 'vendor/silverstripe/supported-modules/repositories.json');
+            if (!file_exists($path)) {
+                throw new RuntimeException('Could not find supported modules list');
+            }
+            $json = json_decode(file_get_contents($path), true);
+            if (is_null($json)) {
+                throw new RuntimeException('Could not parse supported modules list');
+            }
+            $dirs = array_map(fn($module) => "/vendor/{$module['packagist']}/", $json['supportedModules']);
+            // This is a special case for silverstripe-framework when running in CI
+            // Needed because module is run in the root folder rather than in the vendor folder
+            $dirs[] = '/silverstripe-framework/';
+            Deprecation::$supportedModuleDirectories = $dirs;
+        }
+        foreach (Deprecation::$supportedModuleDirectories as $dir) {
+            if (str_contains($file, $dir)) {
+                return true;
+            }
+        }
+        return false;
     }
 
     public static function isEnabled(): bool
@@ -245,6 +316,22 @@ public static function shouldShowForCli(): bool
         return Deprecation::$shouldShowForCli;
     }
 
+    /**
+     * If true, deprecation warnings will be shown for deprecated code which is called by core Silverstripe modules.
+     */
+    public static function getShowNoticesCalledFromSupportedCode(): bool
+    {
+        return Deprecation::$showNoticesCalledFromSupportedCode;
+    }
+
+    /**
+     * Set whether deprecation warnings will be shown for deprecated code which is called by core Silverstripe modules.
+     */
+    public static function setShowNoticesCalledFromSupportedCode(bool $value): void
+    {
+        Deprecation::$showNoticesCalledFromSupportedCode = $value;
+    }
+
     public static function outputNotices(): void
     {
         if (!Deprecation::isEnabled()) {
@@ -258,9 +345,13 @@ public static function outputNotices(): void
             $arr = array_shift(Deprecation::$userErrorMessageBuffer);
             $message = $arr['message'];
             $calledWithNoticeSuppression = $arr['calledWithNoticeSuppression'];
+            $isCalledFromSupportedCode = $arr['isCalledFromSupportedCode'];
             if ($calledWithNoticeSuppression && !Deprecation::$showNoReplacementNotices) {
                 continue;
             }
+            if ($isCalledFromSupportedCode && !Deprecation::$showNoticesCalledFromSupportedCode) {
+                continue;
+            }
             Deprecation::$isTriggeringError = true;
             user_error($message, E_USER_DEPRECATED);
             Deprecation::$isTriggeringError = false;
@@ -294,6 +385,10 @@ public static function notice($atVersion, $string = '', $scope = Deprecation::SC
                 $data = [
                     'key' => sha1($string),
                     'message' => $string,
+                    // Setting to `false` as we don't have a backtrace at to check if it's supported code
+                    // The downside here is that if core developers have set deprecated config via yml then
+                    // project developers will not be able to do anything about it
+                    'isCalledFromSupportedCode' => false,
                     'calledWithNoticeSuppression' => Deprecation::$insideNoticeSuppression
                 ];
             } else {
@@ -322,13 +417,13 @@ public static function notice($atVersion, $string = '', $scope = Deprecation::SC
 
                 $level = Deprecation::$insideNoticeSuppression ? 4 : 2;
                 $string .= " Called from " . Deprecation::get_called_method_from_trace($backtrace, $level) . '.';
-
                 if ($caller) {
                     $string = $caller . ' is deprecated.' . ($string ? ' ' . $string : '');
                 }
                 $data = [
                     'key' => sha1($string),
                     'message' => $string,
+                    'isCalledFromSupportedCode' => Deprecation::isCalledFromSupportedCode($backtrace),
                     'calledWithNoticeSuppression' => Deprecation::$insideNoticeSuppression
                 ];
             }
@@ -360,6 +455,23 @@ public static function notice($atVersion, $string = '', $scope = Deprecation::SC
         }
     }
 
+    /**
+     * Shorthand method to create a suppressed notice for something with no immediate replacement.
+     * If $string is empty, then a standardised message will be used
+     */
+    public static function noticeWithNoReplacment(
+        string $atVersion,
+        string $string = '',
+        int $scope = Deprecation::SCOPE_METHOD
+    ): void {
+        if ($string === '') {
+            $string = 'Will be removed without equivalent functionality to replace it.';
+        }
+        Deprecation::withSuppressedNotice(
+            fn() => Deprecation::notice($atVersion, $string, $scope)
+        );
+    }
+
     private static function varAsBoolean($val): bool
     {
         if (is_string($val)) {