ENH Standardise deprecation messages

src/Control/Director.php

@@ -386,7 +386,7 @@ class Director implements TemplateGlobalProvider
      *
      * @return bool
      *
-     * @deprecated 5.0 Kernel::isFlushed to be used instead
+     * @deprecated 5.0 Use Kernel::isFlushed instead
      */
     public static function isManifestFlushed()
     {

src/Control/HTTP.php

@@ -560,7 +560,7 @@ class HTTP
      * is always in GMT: the number of seconds since January 1 1970 00:00:00 GMT)
      *
      * @param int $timestamp
-     * @deprecated 4.2.0:5.0.0 Inline if you need this
+     * @deprecated 4.2.0:5.0.0 Use native php function gmdate() instead
      * @return string
      */
     public static function gmt_date($timestamp)

src/Control/HTTPRequest.php

@@ -910,7 +910,7 @@ class HTTPRequest implements ArrayAccess
      * @param string $origMethod Original HTTP method from the browser request
      * @param array $postVars
      * @return string HTTP method (all uppercase)
-     * @deprecated 4.4.7
+     * @deprecated 4.4.7 Will be removed without equivalent functionality
      */
     public static function detect_method($origMethod, $postVars)
     {

src/Control/SimpleResourceURLGenerator.php

@@ -159,7 +159,7 @@ class SimpleResourceURLGenerator implements ResourceURLGenerator
     /**
      * Resolve resource in the absence of a public/ folder
      *
-     * @deprecated 4.1.0:5.0.0 Will be removed in 5.0 when public/ folder becomes mandatory
+     * @deprecated 4.1.0:5.0.0 Will be removed without equivalent functionality when public/ folder becomes mandatory
      * @param string $relativePath
      * @return array List of [$exists, $absolutePath, $relativePath]
      */

src/Core/BaseKernel.php

@@ -260,7 +260,7 @@ abstract class BaseKernel implements Kernel
      *
      * @return string
      *
-     * @deprecated 5.0 use Director::get_environment_type() instead. Since 5.0 it should return only if kernel overrides. No checking SESSION or Environment.
+     * @deprecated 5.0 use Director::get_environment_type() instead
      */
     public function getEnvironment()
     {

src/Core/Manifest/Module.php

@@ -206,7 +206,7 @@ class Module implements Serializable
      * The __serialize() magic method will be automatically used instead of this
      *
      * @return string
-     * @deprecated will be removed in 5.0
+     * @deprecated Use __serialize() instead
      */
     public function serialize()
     {
@@ -219,7 +219,7 @@ class Module implements Serializable
      * and the PHP version used in less than PHP 9.0
      *
      * @param string $serialized
-     * @deprecated will be removed in 5.0
+     * @deprecated Use __unserialize() instead
      */
     public function unserialize($serialized)
     {
@@ -288,7 +288,7 @@ class Module implements Serializable
     }
 
     /**
-     * @deprecated 4.0.0:5.0.0 Use ->getResource($path)->getPath() instead
+     * @deprecated 4.0.0:5.0.0 Use getResource($path)->getPath() instead
      * @param string $path
      * @return string
      */
@@ -301,7 +301,7 @@ class Module implements Serializable
     }
 
     /**
-     * @deprecated 4.0.0:5.0.0 Use ->getResource($path)->getURL() instead
+     * @deprecated 4.0.0:5.0.0 Use getResource($path)->getURL() instead
      * @param string $path
      * @return string
      */
@@ -314,7 +314,7 @@ class Module implements Serializable
     }
 
     /**
-     * @deprecated 4.0.0:5.0.0 Use ->getResource($path)->exists() instead
+     * @deprecated 4.0.0:5.0.0 Use getResource($path)->exists() instead
      * @param string $path
      * @return string
      */
@@ -331,7 +331,7 @@ class Module implements Serializable
      * that is observed is `PHP`
      * @return array List of configuration aspects e.g.: `['PHP' => 'CI_PHPUNIT_NINE']`
      * @internal
-     * @deprecated 5.0.0
+     * @deprecated 5.0.0 Will be removed without equivalent functionality
      */
     public function getCIConfig(): array
     {

src/Core/Startup/AbstractConfirmationToken.php

@@ -15,7 +15,7 @@ use SilverStripe\Security\RandomGenerator;
  *
  * @internal This class is designed specifically for use pre-startup and may change without warning
  *
- * @deprecated 5.0 To be removed in SilverStripe 5.0
+ * @deprecated 5.0 Will be removed without equivalent functionality
  */
 abstract class AbstractConfirmationToken
 {

src/Core/Startup/ConfirmationTokenChain.php

@@ -13,7 +13,7 @@ use SilverStripe\Core\Convert;
  *
  * @internal This class is designed specifically for use pre-startup and may change without warning
  *
- * @deprecated 5.0 To be removed in SilverStripe 5.0
+ * @deprecated 5.0 Will be removed without equivalent functionality
  */
 class ConfirmationTokenChain
 {

src/Core/Startup/ErrorControlChainMiddleware.php

@@ -16,7 +16,7 @@ use SilverStripe\Security\Security;
  *
  * @internal This class is designed specifically for use pre-startup and may change without warning
  *
- * @deprecated 5.0 To be removed in SilverStripe 5.0
+ * @deprecated 5.0 Will be removed without equivalent functionality
  */
 class ErrorControlChainMiddleware implements HTTPMiddleware
 {

src/Core/Startup/ParameterConfirmationToken.php

@@ -16,7 +16,7 @@ use SilverStripe\Security\RandomGenerator;
  *
  * @internal This class is designed specifically for use pre-startup and may change without warning
  *
- * @deprecated 5.0 To be removed in SilverStripe 5.0
+ * @deprecated 5.0 Will be removed without equivalent functionality
  */
 class ParameterConfirmationToken extends AbstractConfirmationToken
 {

src/Core/Startup/URLConfirmationToken.php

@@ -12,7 +12,7 @@ use SilverStripe\Control\HTTPRequest;
  *
  * @internal This class is designed specifically for use pre-startup and may change without warning
  *
- * @deprecated 5.0 To be removed in SilverStripe 5.0
+ * @deprecated 5.0 Will be removed without equivalent functionality
  */
 class URLConfirmationToken extends AbstractConfirmationToken
 {

src/Dev/FunctionalTest.php

@@ -425,7 +425,7 @@ if (class_exists(IsEqualCanonicalizing::class)) {
          * This is helpful if you're not testing publication functionality and don't want "stage management" cluttering
          * your test.
          *
-         * @deprecated 4.2.0 Use ?stage=Stage querystring arguments instead of useDraftSite
+         * @deprecated 4.2.0 Use ?stage=Stage in your request's querystring instead
          * @param bool $enabled toggle the use of the draft site
          */
         public function useDraftSite($enabled = true)
@@ -449,7 +449,7 @@ if (class_exists(IsEqualCanonicalizing::class)) {
         }
 
         /**
-         * @deprecated 4.2.0 Use ?stage=Stage in your querystring arguments instead
+         * @deprecated 4.2.0 Use ?stage=Stage in your request's querystring instead
          * @return bool
          */
         public static function get_use_draft_site()
@@ -509,7 +509,7 @@ class FunctionalTest extends SapphireTest implements TestOnly
     /**
      * Set this to true on your sub-class to use the draft site by default for every test in this class.
      *
-     * @deprecated 4.2.0 Use ?stage=Stage in your ->get() querystring requests instead
+     * @deprecated 4.2.0 Use ?stage=Stage in your request's querystring instead
      * @var bool
      */
     protected static $use_draft_site = false;
@@ -870,7 +870,7 @@ class FunctionalTest extends SapphireTest implements TestOnly
      * This is helpful if you're not testing publication functionality and don't want "stage management" cluttering
      * your test.
      *
-     * @deprecated 4.2.0 Use ?stage=Stage querystring arguments instead of useDraftSite
+     * @deprecated 4.2.0 Use ?stage=Stage in your request's querystring instead
      * @param bool $enabled toggle the use of the draft site
      */
     public function useDraftSite($enabled = true)
@@ -894,7 +894,7 @@ class FunctionalTest extends SapphireTest implements TestOnly
     }
 
     /**
-     * @deprecated 4.2.0 Use ?stage=Stage in your querystring arguments instead
+     * @deprecated 4.2.0 Use ?stage=Stage in your request's querystring instead
      * @return bool
      */
     public static function get_use_draft_site()

src/Dev/InstallerTest.php

@@ -6,7 +6,7 @@ use SilverStripe\Control\Controller;
 
 /**
  * Simple controller that the installer uses to test that URL rewriting is working.
- * @deprecated 4.4.7 This class will be removed in Silverstripe Framework 5.
+ * @deprecated 4.4.7 Will be removed without equivalent functionality
  */
 class InstallerTest extends Controller
 {

src/Dev/SapphireInfo.php

@@ -9,7 +9,7 @@ use SilverStripe\Security\Security;
 
 /**
  * Returns information about the current site instance.
- * @deprecated 4.4.7 This class will be removed in Silverstripe Framework 5.
+ * @deprecated 4.4.7 Will be removed without equivalent functionality
  */
 class SapphireInfo extends Controller
 {

src/Dev/SapphireTest.php

@@ -472,7 +472,7 @@ if (class_exists(IsEqualCanonicalizing::class)) {
 
         /**
          * @return FixtureFactory|false
-         * @deprecated 4.0.0
+         * @deprecated 4.0.0 Use FixtureTestState instead
          */
         public function getFixtureFactory()
         {
@@ -486,7 +486,7 @@ if (class_exists(IsEqualCanonicalizing::class)) {
          * Sets a new fixture factory
          * @param FixtureFactory $factory
          * @return $this
-         * @deprecated 4.0.0
+         * @deprecated 4.0.0 Use FixtureTestState instead
          */
         public function setFixtureFactory(FixtureFactory $factory)
         {
@@ -1793,7 +1793,7 @@ class SapphireTest extends PHPUnit_Framework_TestCase implements TestOnly
 
     /**
      * @return FixtureFactory|false
-     * @deprecated 4.0.0
+     * @deprecated 4.0.0 Use FixtureTestState instead
      */
     public function getFixtureFactory()
     {
@@ -1807,7 +1807,7 @@ class SapphireTest extends PHPUnit_Framework_TestCase implements TestOnly
      * Sets a new fixture factory
      * @param FixtureFactory $factory
      * @return $this
-     * @deprecated 4.0.0
+     * @deprecated 4.0.0 Use FixtureTestState instead
      */
     public function setFixtureFactory(FixtureFactory $factory)
     {

src/Dev/TestKernel.php

@@ -53,7 +53,7 @@ class TestKernel extends CoreKernel
      */
     public function setIgnoredCIConfigs(array $ciConfigs): self
     {
-        Deprecation::notice('5.0.0', 'This method will be removed in CMS 5');
+        Deprecation::notice('5.0.0', 'Will be removed without equivalent functionality');
 
         $this->ciConfigs = $ciConfigs;
         return $this;
@@ -61,7 +61,7 @@ class TestKernel extends CoreKernel
 
     protected function getIgnoredCIConfigs(): array
     {
-        Deprecation::notice('5.0.0', 'This method will be removed in CMS 5');
+        Deprecation::notice('5.0.0', 'Will be removed without equivalent functionality');
 
         return $this->ciConfigs;
     }

src/Forms/FieldList.php

@@ -180,7 +180,7 @@ class FieldList extends ArrayList
     }
 
     /**
-     * @deprecated 4.1.0:5.0.0 Please use dataFields or saveableFields
+     * @deprecated 4.1.0:5.0.0 Please use dataFields or saveableFields instead
      * @param $list
      * @param bool $saveableOnly
      */

src/Forms/GridField/GridFieldVersionedState.php

@@ -11,7 +11,7 @@ if (!class_exists(VersionedGridFieldState::class)) {
 
 
 /**
- * @deprecated 4.1.0:5.0.0
+ * @deprecated 4.1.0:5.0.0 Use VersionedGridFieldState instead
  */
 class GridFieldVersionedState extends VersionedGridFieldState
 {

src/Forms/HTMLEditor/TinyMCEConfig.php

@@ -875,7 +875,7 @@ class TinyMCEConfig extends HTMLEditorConfig implements i18nEntityProvider
     }
 
     /**
-     * @deprecated 4.0.0:5.0.0
+     * @deprecated 4.0.0:5.0.0 Use getTinyMCEResourcePath() instead
      */
     public function getTinyMCEPath()
     {

src/Forms/HTMLEditor/TinyMCEGZIPGenerator.php

@@ -11,7 +11,7 @@ use TinyMCE_Compressor;
 /**
  * Uses the default tiny_mc_gzip.php handler
  *
- * @deprecated 4.0.0:5.0.0
+ * @deprecated 4.0.0:5.0.0 Will be removed without equivalent functionality
  */
 class TinyMCEGZIPGenerator implements TinyMCEScriptGenerator
 {

src/Forms/TreeDropdownField.php

@@ -621,7 +621,7 @@ class TreeDropdownField extends FormField
     /**
      * HTML-encoded label for this node, including css classes and other markup.
      *
-     * @deprecated 4.0.0:5.0.0 Use setTitleField()
+     * @deprecated 4.0.0:5.0.0 Use setTitleField() instead
      * @param string $field
      * @return $this
      */
@@ -634,7 +634,7 @@ class TreeDropdownField extends FormField
     /**
      * HTML-encoded label for this node, including css classes and other markup.
      *
-     * @deprecated 4.0.0:5.0.0 Use getTitleField()
+     * @deprecated 4.0.0:5.0.0 Use getTitleField() instead
      * @return string
      */
     public function getLabelField()

src/ORM/Connect/DBSchemaManager.php

@@ -60,7 +60,7 @@ abstract class DBSchemaManager
      * @param string $table
      * @param string $class
      *
-     * @deprecated 4.0.0:5.0.0
+     * @deprecated 4.0.0:5.0.0 Will be removed without equivalent functionality
      */
     public static function showTableNameWarning($table, $class)
     {

src/ORM/Connect/PDOConnector.php

@@ -142,8 +142,7 @@ class PDOConnector extends DBConnector implements TransactionManager
 
     public function connect($parameters, $selectDB = false)
     {
-        Deprecation::notice('4.5', 'Use native database drivers in favour of PDO. '
+        Deprecation::notice('4.5', 'Use native database drivers instead');
-            . 'https://github.com/silverstripe/silverstripe-framework/issues/8598');
 
         $this->flushStatements();
 

src/ORM/DataExtension.php

@@ -19,7 +19,7 @@ abstract class DataExtension extends Extension
 {
 
     /**
-     * @deprecated 4.7.0 No longer used by internal code
+     * @deprecated 4.7.0 Will be removed without equivalent functionality
      */
     public static function unload_extra_statics($class, $extension)
     {

src/ORM/ValidationResult.php

@@ -232,7 +232,7 @@ class ValidationResult implements Serializable
      * The __serialize() magic method will be automatically used instead of this
      *
      * @return string
-     * @deprecated will be removed in 5.0
+     * @deprecated Use __serialize() instead
      */
     public function serialize()
     {
@@ -245,7 +245,7 @@ class ValidationResult implements Serializable
      * and the PHP version used in less than PHP 9.0
      *
      * @param string $serialized
-     * @deprecated will be removed in 5.0
+     * @deprecated Use __unserialize() instead
      */
     public function unserialize($serialized)
     {

src/Security/Group.php

@@ -721,7 +721,7 @@ class Group extends DataObject
      * Code needs to be unique as it is used to identify a specific group. Ensure no duplicate
      * codes are created.
      *
-     * @deprecated 5.0 Remove deduping in favour of throwing a validation error for duplicates.
+     * @deprecated 5.0 Replaced with a validation error when a duplicate is found.
      */
     private function dedupeCode(): void
     {

src/Security/Member.php

@@ -529,8 +529,9 @@ class Member extends DataObject
     }
 
     /**
-     * @deprecated Use Security::setCurrentUser(null) or an IdentityStore
      * Logs this member out.
+     *
+     * @deprecated Use Security::setCurrentUser(null) or an IdentityStore instead
      */
     public function logOut()
     {

src/Security/PasswordValidator.php

@@ -76,11 +76,11 @@ class PasswordValidator
     protected $historicalPasswordCount = null;
 
     /**
-     * @deprecated 4.5.0
      * Minimum password length
      *
      * @param int $minLength
      * @return $this
+     * @deprecated 4.5.0 Use setMinLength() instead
      */
     public function minLength($minLength)
     {
@@ -89,7 +89,6 @@ class PasswordValidator
     }
 
     /**
-     * @deprecated 4.5.0
      * Check the character strength of the password.
      *
      * Eg: $this->characterStrength(3, array("lowercase", "uppercase", "digits", "punctuation"))
@@ -97,6 +96,7 @@ class PasswordValidator
      * @param int $minScore The minimum number of character tests that must pass
      * @param string[] $testNames The names of the tests to perform
      * @return $this
+     * @deprecated 4.5.0 Use setMinTestScore($score) and setTestNames($names) instead
      */
     public function characterStrength($minScore, $testNames = null)
     {
@@ -112,11 +112,11 @@ class PasswordValidator
     }
 
     /**
-     * @deprecated 4.5.0
      * Check a number of previous passwords that the user has used, and don't let them change to that.
      *
      * @param int $count
      * @return $this
+     * @deprecated 4.5.0 Use setHistoricCount($value) instead
      */
     public function checkHistoricalPasswords($count)
     {

src/Security/Permission.php

@@ -660,7 +660,7 @@ class Permission extends DataObject implements TemplateGlobalProvider, Resettabl
      * Get a linear list of the permissions in the system.
      *
      * @return array Linear list of declared permissions in the system.
-     * @deprecated 4.4.0
+     * @deprecated 4.4.0 Will be removed without equivalent functionality
      */
     public static function get_declared_permissions_list()
     {
@@ -684,7 +684,7 @@ class Permission extends DataObject implements TemplateGlobalProvider, Resettabl
      *
      * @param string $perm Permission code
      * @return string Label for the given permission, or the permission itself if the label doesn't exist
-     * @deprecated 4.4.0
+     * @deprecated 4.4.0 Will be removed without equivalent functionality
      */
     public static function get_label_for_permission($perm)
     {
@@ -702,7 +702,7 @@ class Permission extends DataObject implements TemplateGlobalProvider, Resettabl
      * @param array $declared Nested structure of permissions.
      * @param array $list List of permissions in the structure. The result will be
      *              written to this array.
-     * @deprecated 4.4.0
+     * @deprecated 4.4.0 Will be removed without equivalent functionality
      */
     protected static function traverse_declared_permissions($declared, &$list)
     {

src/Security/Security.php

@@ -1150,7 +1150,7 @@ class Security extends Controller implements TemplateGlobalProvider
     /**
      * Get default admin username
      *
-     * @deprecated 4.0.0:5.0.0 Use DefaultAdminService::getDefaultAdminUsername()
+     * @deprecated 4.0.0:5.0.0 Use DefaultAdminService::getDefaultAdminUsername() instead
      * @return string
      */
     public static function default_admin_username()
@@ -1163,7 +1163,7 @@ class Security extends Controller implements TemplateGlobalProvider
     /**
      * Get default admin password
      *
-     * @deprecated 4.0.0:5.0.0 Use DefaultAdminService::getDefaultAdminPassword()
+     * @deprecated 4.0.0:5.0.0 Use DefaultAdminService::getDefaultAdminPassword() instead
      * @return string
      */
     public static function default_admin_password()

src/View/Requirements_Backend.php

@@ -238,8 +238,8 @@ class Requirements_Backend
     /**
      * Gets the minification service for this backend
      *
-     * @deprecated 4.0.0:5.0.0
      * @return Requirements_Minifier
+     * @deprecated 4.0.0:5.0.0 Will be removed without equivalent functionality
      */
     public function getMinifier()
     {

src/View/SSViewer.php

@@ -296,8 +296,8 @@ class SSViewer implements Flushable
     }
 
     /**
-     * @deprecated 4.0.0:5.0.0 Use the "SSViewer#set_themes" instead
      * @param string $theme The "base theme" name (without underscores).
+     * @deprecated 4.0.0:5.0.0 Use SSViewer::set_themes() instead
      */
     public static function set_theme($theme)
     {

src/View/Shortcodes/EmbedShortcodeProvider.php

@@ -160,7 +160,7 @@ class EmbedShortcodeProvider implements ShortcodeHandler
      * @param Adapter $embed
      * @param array $arguments Additional shortcode params
      * @return string
-     * @deprecated 4.11..5.0 Use embeddableToHtml instead
+     * @deprecated 4.11..5.0 Use embeddableToHtml() instead
      */
     public static function embedForTemplate($embed, $arguments)
     {

src/View/ViewableData.php

@@ -619,7 +619,7 @@ class ViewableData implements IteratorAggregate
      * project directory.
      *
      * @return string URL to the current theme
-     * @deprecated 4.0.0:5.0.0 Use $resourcePath or $resourceURL template helpers instead
+     * @deprecated 4.0.0:5.0.0 Use ModuleResourceLoader::resourcePath() or ModuleResourceLoader::resourceURL() instead
      */
     public function ThemeDir()
     {

src/i18n/Messages/Symfony/FlushInvalidatedResource.php

@@ -54,7 +54,7 @@ class FlushInvalidatedResource implements SelfCheckingResourceInterface, \Serial
      * The __serialize() magic method will be automatically used instead of this
      *
      * @return string
-     * @deprecated will be removed in 5.0
+     * @deprecated Use __serialize() instead
      */
     public function serialize()
     {
@@ -67,7 +67,7 @@ class FlushInvalidatedResource implements SelfCheckingResourceInterface, \Serial
      * and the PHP version used in less than PHP 9.0
      *
      * @param string $serialized
-     * @deprecated will be removed in 5.0
+     * @deprecated Use __unserialize() instead
      */
     public function unserialize($serialized)
     {