class Deprecation (View source)

Handles raising an notice when accessing a deprecated method, class, configuration, or behaviour.

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.

See https://docs.silverstripe.org/en/contributing/release_process/#deprecation

Constants

SCOPE_METHOD

SCOPE_CLASS

SCOPE_GLOBAL

SCOPE_CONFIG

Properties

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

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

protected static deprecated array $module_version_overrides
public static deprecated array $notice_level

Methods

public static 
void
enable(bool $showNoReplacementNotices = false)

Enable throwing deprecation warnings. By default, this excludes warnings for deprecated code which is called by core Silverstripe modules.

public static 
void
disable()

Disable throwing deprecation warnings.

public static 
mixed
withNoReplacement(callable $func)

Used to wrap deprecated methods and deprecated config get()/set() that will be removed in the next major version with no replacement. This is done to surpress deprecation notices by for calls from the vendor dir to deprecated code that projects have no ability to change

public static 
void
notification_version($ver, null $forModule = null) deprecated

This method is no longer used

protected static 
get_calling_module_from_trace(array $backtrace) deprecated

This method is no longer used

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() deprecated

This method is no longer used

public static 
bool
isEnabled()

No description

public static 
set_enabled(bool $enabled) deprecated

This method is no longer used

public static 
bool
isTriggeringError()

If true, any E_USER_DEPRECATED errors should be treated as coming directly from this class.

public static 
void
setShouldShowForHttp(bool $value)

Determine whether deprecation warnings should be included in HTTP responses.

public static 
void
setShouldShowForCli(bool $value)

Determine whether deprecation warnings should be included in CLI responses.

public static 
bool
shouldShowForHttp()

If true, deprecation warnings should be included in HTTP responses.

public static 
bool
shouldShowForCli()

If true, deprecation warnings should be included in CLI responses.

public static 
void
outputNotices()

No description

public static 
notice(string $atVersion, string $string = '', int $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() deprecated

This method is no longer used

public static 
restore_settings($settings) deprecated

This method is no longer used

Details

static void enable(bool $showNoReplacementNotices = false)

Enable throwing deprecation warnings. By default, this excludes warnings for deprecated code which is called by core Silverstripe modules.

This will be overriden by the SS_DEPRECATION_ENABLED environment variable if present.

Parameters

bool $showNoReplacementNotices

If true, deprecation warnings will also be thrown for deprecated code which is called by core Silverstripe modules.

Return Value

void

static void disable()

Disable throwing deprecation warnings.

This will be overriden by the SS_DEPRECATION_ENABLED environment variable if present.

Return Value

void

static mixed withNoReplacement(callable $func)

Used to wrap deprecated methods and deprecated config get()/set() that will be removed in the next major version with no replacement. This is done to surpress deprecation notices by for calls from the vendor dir to deprecated code that projects have no ability to change

Parameters

callable $func

Return Value

mixed

static void notification_version($ver, null $forModule = null) deprecated

deprecated 4.12.0 Use enable() instead

This method is no longer used

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 Module get_calling_module_from_trace(array $backtrace) deprecated

deprecated 4.12.0 Will be removed without equivalent functionality to replace it

This method is no longer used

Parameters

array $backtrace

A backtrace as returned from debug_backtrace

Return Value

Module

The module being called

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() deprecated

deprecated 4.12.0 Will be removed without equivalent functionality to replace it

This method is no longer used

Return Value

bool

static bool isEnabled()

No description

Return Value

bool

static set_enabled(bool $enabled) deprecated

deprecated 4.12.0 Use enable() instead

This method is no longer used

Parameters

bool $enabled

static bool isTriggeringError()

If true, any E_USER_DEPRECATED errors should be treated as coming directly from this class.

Return Value

bool

static void setShouldShowForHttp(bool $value)

Determine whether deprecation warnings should be included in HTTP responses.

Does not affect logging.

This will be overriden by the SS_DEPRECATION_SHOW_HTTP environment variable if present.

Parameters

bool $value

Return Value

void

static void setShouldShowForCli(bool $value)

Determine whether deprecation warnings should be included in CLI responses.

Does not affect logging.

This will be overriden by the SS_DEPRECATION_SHOW_CLI environment variable if present.

Parameters

bool $value

Return Value

void

static bool shouldShowForHttp()

If true, deprecation warnings should be included in HTTP responses.

Does not affect logging.

Return Value

bool

static bool shouldShowForCli()

If true, deprecation warnings should be included in CLI responses.

Does not affect logging.

Return Value

bool

static void outputNotices()

No description

Return Value

void

static notice(string $atVersion, string $string = '', int $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

int $scope

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

static array dump_settings() deprecated

deprecated 4.12.0 Will be removed without equivalent functionality to replace it

This method is no longer used

Return Value

array

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

static restore_settings($settings) deprecated

deprecated 4.12.0 Will be removed without equivalent functionality to replace it

This method is no longer used

Parameters

$settings

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