...
We have deprecation guidelines because even if we clean up all uses of something we often cannot just remove it, as we're an open source project and we market ourselves as such to those who use our software. It's important to assume that someone out there is using every single function, class, method, file, and resource in their own plugins and customisationsWe have different controls in place for different aspects of our software, read further to understand when and how we apply our deprecation guidelines.
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
| Code Block |
|---|
This file describes API changes in Totara Connect Server, information provided here is intended for developers. === 1119.1 === * create_something() the first argument is no longer used. Functionality has not changed. * some_class::some_method() has been deprecated, please call some_class::some_other_method() instead. === 1019.0 === * create_function() added second argument $bar * some_class has been renamed to \totara\core\some_class, please update all uses. |
...
| Code Block |
|---|
/** * A one line summary * * A full description of the function or method and any details you want to share. * * @param string $foo a summary of this variable. * @param string $bar summary of optional second argument. * Details about the argument. * Since Totara 1018.5 */ function create_something($foo, $bar = null) { // ... } |
...
The original function:
| Code Block | ||
|---|---|---|
| ||
/**
* A one line summary
*
* A full description of the function or method and any details you want to share.
*
* @param string $foo a summary of this argument.
* @param string $bar a summary of this argument.
*/
function create_something($foo, $bar) {
// ...
} |
With the removed argument:
| Code Block | ||
|---|---|---|
| ||
/**
* A one line summary
*
* A full description of the function or method and any details you want to share.
*
* @param string $unused This argument is no longer used as of Totara 10.
* @param string $bar a summary of this argument.
*/
function create_something($unused = null, $bar) {
if ($unused !== null) {
debugging('The create_something() second argument is no longer used, please review your code', DEBUG_DEVELOPER);
}
// ...
} |
...
The debugging call should only be present if functionality has changed. As functionality should be changed only in rare situations this debugging notice should be equally rare.
The purpose of a function should never change. If the purpose of the function is changing then you should deprecate the old function and create a new one.
Make the old function call the new one if that is possiblechange. If the purpose of the function is changing then you should deprecate the old function and create a new one.
Make the old function call the new one if that is possible.
Changing an argument to be nullable
Where an argument is currently non-nullable, arguments may be changed to be nullable.
The original function
| Code Block | ||
|---|---|---|
| ||
/**
* A one line summary
*
* A full description of the function or method and any details you want to share.
*
* @param string $foo a summary of this argument.
* @param string $bar a summary of this argument.
*/
function create_something(string $foo, string $bar) {
// ...
} |
With the nullable argument:
| Code Block | ||
|---|---|---|
| ||
/**
* A one line summary
*
* A full description of the function or method and any details you want to share.
*
* @param string|null $foo a summary of this argument.
* @param string|null $bar a summary of this argument.
*/
function create_something(?string $foo, ?string $bar = null) {
// ...
} |
In upgrade.txt:
| Code Block |
|---|
* create_something() the $foo and $bar arguments are now nullable. Functionality has not changed. |
Changing scope; public, protected, private
...
| Code Block |
|---|
class foo {
private $bar;
public function __get($property) {
if ($property === 'bar') {
// This was deprecated in Totara 1018 and public access to this property will be revoked in the future.
// Please call xxx instead.
debugging('foo::$bar is now a private property, please call xxx instead.', DEBUG_DEVELOPER);
return $this->{$bar};
}
throw new coding_exception('Request for an undefined property', $property);
}
public function __set($property, $value) {
if ($property === 'bar') {
// This was deprecated in Totara 1018 and public access to this property will be revoked in the future.
// Please call xxx instead.
debugging('foo::$bar is now a private property please do not directly set $bar any more', DEBUG_DEVELOPER);
return $this->{$bar} = $value;
}
throw new coding_exception('Call to an undefined property', [$property, $value]);
}
} |
...
| Code Block | ||
|---|---|---|
| ||
/** ... * @deprecated since Totara 19.01 See mod_perform_webapi_resolver_mutation_update_activity_basic_settings instead. */ class mod_perform_webapi_resolver_mutation_update_activity_test extends testcase { ... // Update each test_...() method with static::assertDebuggingCalled(...) ... public function test_update_success(): void { [, $args] = $this->create_activity(); /** @var activity $activity */ ['activity' => $activity] = $this->resolve_graphql_mutation(self::MUTATION, $args); static::assertDebuggingCalled( "The mutation 'mod_perform_update_activity' had been deprecated, please use mod_perform_update_activity_basic_settings instead", DEBUG_DEVELOPER ); // Return values should be updated $this->assert_base_update_result($args, $activity); } ... } |
...
| Code Block |
|---|
/** * This function has been deprecated please call core_totara_my_func() instead. * @deprecated since Totara 1018.0 */ function my_func($foo, $bar = 'default') { debugging('my_func() has been renamed to core_totara_my_func()', DEBUG_DEVELOPER); return core_totara_my_func($foo, $bar); } /** * Renamed from my_func() * @since Totara 1018.0 */ function core_totara_my_func($foo, $bar = 'default') { global $DB; $obj = $DB->get_record('table', ['foo' => $foo, 'bar' => $bar], '*', MUST_EXIST); return $obj; } |
...
| Code Block |
|---|
class table {
/**
* This function has been deprecated please call core_totara_my_func() instead.
* @deprecated since Totara 1019.0
*/
public function has_cheers() {
debugging('table::has_cheers() has been renamed to table::has_chairs()', DEBUG_DEVELOPER);
return $this->has_chairs();
}
/**
* Renamed from has_cheers()
* @since Totara 1019.0
*/
public function has_chairs() {
global $DB;
return $DB->count_records('table', ['id' => $this->id]);
}
} |
...