MDL-74548 backup: Refactor course copies

This patch modifies the way copy data is shared in order to mitigate potential race conditions
and ensure that the serialised controller stored in the DB is always in a valid state.

The restore controller is now considered the "source of truth" for all information about the
copy operation. Backup controllers can no longer contain information about course copies.

As copy creation is not atomic, it is still possible for copy controllers to become orphaned or
exist in an invalid state. To mitigate this the backup cleanup task has been modified to call
a new helper method copy_helper::cleanup_orphaned_copy_controllers.

Summary of changes in this patch:

    - Copy data must now be passed through the restore controller's constructor
    - base_controller::get_copy has been deprecated in favour of restore_controller::get_copy
    - base_controller::set_copy has been deprecated without replacement
    - core_backup\copy\copy has been deprecated, use copy_helper.class.php's copy_helper instead
    - backup_cleanup_task will now clean up orphaned controllers from copy operations that went awry

Thanks to Peter Burnett for assiting with testing this patch.

backup/controller/restore_controller.class.php

@@ -65,6 +65,13 @@ class restore_controller extends base_controller {
     /** @var int Number of restore_controllers that are currently executing */
     protected static $executing = 0;
 
+    /**
+     * Holds the relevant destination information for course copy operations.
+     *
+     * @var \stdClass.
+     */
+    protected $copy;
+
     /**
      * Constructor.
      *
@@ -79,10 +86,17 @@ class restore_controller extends base_controller {
      * @param int $userid
      * @param int $target backup::TARGET_[ NEW_COURSE | CURRENT_ADDING | CURRENT_DELETING | EXISTING_ADDING | EXISTING_DELETING ]
      * @param \core\progress\base $progress Optional progress monitor
+     * @param \stdClass $copydata Course copy data, required when in MODE_COPY
      * @param bool $releasesession Should release the session? backup::RELEASESESSION_YES or backup::RELEASESESSION_NO
      */
     public function __construct($tempdir, $courseid, $interactive, $mode, $userid, $target,
-            \core\progress\base $progress = null, $releasesession = backup::RELEASESESSION_NO) {
+            \core\progress\base $progress = null, $releasesession = backup::RELEASESESSION_NO, ?\stdClass $copydata = null) {
+
+        if ($mode == backup::MODE_COPY && is_null($copydata)) {
+            throw new restore_controller_exception('cannot_instantiate_missing_copydata');
+        }
+
+        $this->copy = $copydata;
         $this->tempdir = $tempdir;
         $this->courseid = $courseid;
         $this->interactive = $interactive;
@@ -563,6 +577,19 @@ class restore_controller extends base_controller {
         $this->progress->end_progress();
     }
 
+    /**
+     * Get the course copy data.
+     *
+     * @return \stdClass
+     */
+    public function get_copy(): \stdClass {
+        if ($this->mode != backup::MODE_COPY) {
+            throw new restore_controller_exception('cannot_get_copy_wrong_mode');
+        }
+
+        return $this->copy;
+    }
+
 // Protected API starts here
 
     protected function calculate_restoreid() {