MDL-71144 completion: Deprecate get_completion_state callbacks

* *_get_completion_state() callback functions have been deprecated and
should no  longer be used. Plugins that define custom completion rules
must implement the mod_[modname]\completion\custom_completion class that
extends the \core_completion\activity_custom_completion base class.

completion/upgrade.txt

@@ -19,6 +19,9 @@ information provided here is intended especially for developers.
     - Given the manual completion button of "<Activity name>" overridden by "<User>" is displayed as "<Status>"
   - overridden_activity_completion_condition_displayed_as
     - Given the "<Completion condition>" completion condition of "<Activity name>" overridden by "<User>" is displayed as "<Status>"
+* *_get_completion_state() callback functions have been deprecated and should no longer be used. Plugins that define custom
+  completion rules must implement the mod_[modname]\completion\custom_completion class that extends the
+  \core_completion\activity_custom_completion base class.
 
 === 3.7 ===
  * External function core_completion_external::get_activities_completion_status new returns the following additional field:

lib/completionlib.php

@@ -562,10 +562,10 @@ public function user_can_override_completion($user) {
      * if a forum provides options for marking itself 'completed' once a user makes
      * N posts, this function should be called every time a user makes a new post.
      * [After the post has been saved to the database]. When calling, you do not
-     * need to pass in the new completion state. Instead this function carries out
-     * completion calculation by checking grades and viewed state itself, and
-     * calling the involved module via modulename_get_completion_state() to check
-     * module-specific conditions.
+     * need to pass in the new completion state. Instead this function carries out completion
+     * calculation by checking grades and viewed state itself, and calling the involved module
+     * via mod_{modulename}\\completion\\custom_completion::get_overall_completion_state() to
+     * check module-specific conditions.
      *
      * @param stdClass|cm_info $cm Course-module
      * @param int $possibleresult Expected completion result. If the event that
@@ -701,12 +701,16 @@ public function internal_get_state($cm, $userid, $current) {
                 }
             } else {
                 // Fallback to the get_completion_state callback.
+                $cmcompletionclass = "mod_{$cminfo->modname}\\completion\\custom_completion";
                 $function = $cminfo->modname . '_get_completion_state';
                 if (!function_exists($function)) {
-                    $this->internal_systemerror("Module {$cminfo->modname} claims to support
-                    FEATURE_COMPLETION_HAS_RULES but does not have required
-                    {$cminfo->modname}_get_completion_state function");
+                    $this->internal_systemerror("Module {$cminfo->modname} claims to support FEATURE_COMPLETION_HAS_RULES " .
+                        "but does not implement the custom completion class $cmcompletionclass which extends " .
+                        "\core_completion\activity_custom_completion.");
                 }
+                debugging("*_get_completion_state() callback functions such as $function have been deprecated and should no " .
+                    "longer be used. Please implement the custom completion class $cmcompletionclass which extends " .
+                    "\core_completion\activity_custom_completion.", DEBUG_DEVELOPER);
                 if (!$function($this->course, $cminfo, $userid, COMPLETION_AND)) {
                     return COMPLETION_INCOMPLETE;
                 }