Deprecation

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.