class Deprecation (View source)

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.

Constants

SCOPE_METHOD

SCOPE_CLASS

SCOPE_GLOBAL

Properties

protected static string $version
protected static bool|null $enabled

Override whether deprecation is enabled. If null, then fallback to SS_DEPRECATION_ENABLED, and then true if not defined.

protected static array $module_version_overrides
public static int $notice_level

Methods

public static 
void
notification_version($ver, null $forModule = 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

protected static 
string
get_calling_module_from_trace($backtrace)

Given a backtrace, get the module name from the caller two removed (the caller of the method that called

notice)

protected static 
string
get_called_method_from_trace($backtrace, $level = 1)

Given a backtrace, get the method name from the immediate parent caller (the caller of #notice)

public static 
bool
get_enabled()

Determine if deprecation notices should be displayed

public static 
set_enabled(bool $enabled)

Toggle on or off deprecation notices. Will be ignored in live.

public static 
notice(string $atVersion, string $string = '', bool $scope = Deprecation::SCOPE_METHOD)

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

public static 
array
dump_settings()

Method for when testing. Dump all the current version settings to a variable for later passing to restore

public static 
restore_settings($settings)

Method for when testing. Restore all the current version settings from a variable

Details

static void notification_version($ver, null $forModule = 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

Parameters

$ver

string - A php standard version string, see http://php.net/manual/en/function.version-compare.php for details.

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 Value

void

static protected string get_calling_module_from_trace($backtrace)

Given a backtrace, get the module name from the caller two removed (the caller of the method that called

notice)

Parameters

$backtrace

array - a backtrace as returned from debug_backtrace

Return Value

string
  • the name of the module the call came from, or null if we can't determine

static protected string get_called_method_from_trace($backtrace, $level = 1)

Given a backtrace, get the method name from the immediate parent caller (the caller of #notice)

Parameters

$backtrace

array - a backtrace as returned from debug_backtrace

$level
  • 1 (default) will return immediate caller, 2 will return caller's caller, etc.

Return Value

string
  • the name of the method

static bool get_enabled()

Determine if deprecation notices should be displayed

Return Value

bool

static set_enabled(bool $enabled)

Toggle on or off deprecation notices. Will be ignored in live.

Parameters

bool $enabled

static notice(string $atVersion, string $string = '', bool $scope = Deprecation::SCOPE_METHOD)

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

Parameters

string $atVersion

The version at which this notice should start being raised

string $string

The notice to raise

bool $scope

Notice relates to the method or class context its called in.

static array dump_settings()

Method for when testing. Dump all the current version settings to a variable for later passing to restore

Return Value

array

Opaque array that should only be used to pass to {\Deprecation::restore_settings()}

static restore_settings($settings)

Method for when testing. Restore all the current version settings from a variable

Parameters

$settings

array An array as returned by {\Deprecation::dump_settings()}