[#3505633] Implement various deprecation methods

Closes #3505633

ai_eca.install

+<?php
+
+/**
+ * @file
+ * Install, update and uninstall functions for the ai_eca module.
+ */
+
+/**
+ * Checks to ensure a smooth migration from AI submodule to external module.
+ */
+function ai_eca_update_11001() {
+  $submodule = 'ai_eca';
+  $external_module = 'ai_integration_eca';
+
+  // phpcs:disable
+  // Scenarios are:
+  // 1. Old submodule is not enabled -> we have nothing to do.
+  // 2. Old submodule is enabled:
+  //   1. New module exists but is not yet installed -> install it.
+  //   2. New module does not exist and is therefor not installed -> Tell
+  //      the user to composer require it and retry the update hook.
+  //   3. New module exists and is installed (yet the old is still enabled,
+  //      see (1)) -> Since the new module should uninstall the old, this
+  //      should never happen. Throw an error.
+  // phpcs:enable
+
+  // If the new module is already enabled, it should have uninstalled the
+  // old module. The 'moduleExists' method checks if the module is actually
+  // enabled too.
+  /** @var \Drupal\Core\Extension\ModuleHandlerInterface $handler */
+  $handler = \Drupal::service('module_handler');
+  if (!$handler->moduleExists($submodule)) {
+    return t('@submodule has already been uninstalled.', [
+      '@submodule' => $submodule,
+    ]);
+  }
+
+  // If the new module exists but is not yet installed, enable it. The 'list'
+  // service exists method only checks that the module is in the file system,
+  // but does not care if its enabled or not.
+  /** @var \Drupal\Core\Extension\ModuleExtensionList $list */
+  $list = \Drupal::service('extension.list.module');
+  if ($list->exists($external_module) && !$handler->moduleExists($external_module)) {
+    /** @var \Drupal\Core\Extension\ModuleInstallerInterface $installer */
+    $installer = \Drupal::service('module_installer');
+    // No try-catch, we want a failure to throw an error.
+    $installer->install([$external_module]);
+
+    return t('@external_module has already been installed.', [
+      '@external_module' => $external_module,
+    ]);
+  }
+
+  // If the new module does not exist but the old submodule is enabled,
+  // we need to tell the user to composer require it. We will then fail this
+  // update hook so that we can try it again later after they have carried out
+  // the composer install.
+  if (!$list->exists($external_module)) {
+    $message = t('@submodule has moved from the AI Core to a separate module. Please run `composer require drupal/@external_module` then run this update hook again.', [
+      '@submodule' => $submodule,
+      '@external_module' => $external_module,
+    ]);
+    die((string) $message);
+  }
+
+  // New module is installed but so does is the old submodule (since we
+  // already checked that above), but as noted.
+  if ($handler->moduleExists($external_module)) {
+    $message = t("Only '@external_module' should be installed, not '@submodule'.", [
+      '@external_module' => $external_module,
+      '@submodule' => $submodule,
+    ]);
+    die((string) $message);
+  }
+
+  return t('@submodule-module moving to contributed @external_module-module has been completed.', [
+    '@submodule' => $submodule,
+    '@external_module' => $external_module,
+  ]);
+}