public function ModuleInstaller::install

Installs a given list of modules.

Order of events:

• Gather and add module dependencies to $module_list (if applicable).
• For each module that is being installed:
  • Invoke hook_module_preinstall().
  • Install module schema and update system registries and caches.
  • Invoke hook_install() and add it to the list of installed modules.
• Invoke hook_modules_installed().

To install test modules add

$settings['extension_discovery_scan_tests'] = TRUE;

to your settings.php.

Parameters

string[] $module_list: An array of module names.

bool $enable_dependencies: (optional) If TRUE, dependencies will automatically be installed in the correct order. This incurs a significant performance cost, so use FALSE if you know $module_list is already complete.

Return value

bool TRUE if the modules were successfully installed.

Throws

\Drupal\Core\Extension\MissingDependencyException Thrown when a requested module, or a dependency of one, can not be found.

\Drupal\Core\Extension\ExtensionNameLengthException Thrown when the extension's name is longer than DRUPAL_EXTENSION_NAME_MAX_LENGTH.

Overrides ModuleInstallerInterface::install

See also

hook_module_preinstall()

hook_install()

hook_modules_installed()

File

core/lib/Drupal/Core/Extension/ModuleInstaller.php, line 114

Class

ModuleInstaller

Default implementation of the module installer.

Namespace

Code

public function install(array $module_list, $enable_dependencies = TRUE) {
  $extension_config = \Drupal::configFactory()
    ->getEditable('core.extension');

  // Get all module data so we can find dependencies and sort and find the
  // core requirements. The module list needs to be reset so that it can
  // re-scan and include any new modules that may have been added directly
  // into the filesystem.
  $module_data = \Drupal::service('extension.list.module')
    ->reset()
    ->getList();
  foreach ($module_list as $module) {
    if (!empty($module_data[$module]->info['core_incompatible'])) {
      throw new MissingDependencyException("Unable to install modules: module '{$module}' is incompatible with this version of Drupal core.");
    }
    if ($module_data[$module]->info[ExtensionLifecycle::LIFECYCLE_IDENTIFIER] === ExtensionLifecycle::OBSOLETE) {
      throw new ObsoleteExtensionException("Unable to install modules: module '{$module}' is obsolete.");
    }
    if ($module_data[$module]->info[ExtensionLifecycle::LIFECYCLE_IDENTIFIER] === ExtensionLifecycle::DEPRECATED) {
      @trigger_error("The module '{$module}' is deprecated. See " . $module_data[$module]->info['lifecycle_link'], E_USER_DEPRECATED);
    }
  }
  if ($enable_dependencies) {
    $module_list = $module_list ? array_combine($module_list, $module_list) : [];
    if ($missing_modules = array_diff_key($module_list, $module_data)) {

      // One or more of the given modules doesn't exist.
      throw new MissingDependencyException(sprintf('Unable to install modules %s due to missing modules %s.', implode(', ', $module_list), implode(', ', $missing_modules)));
    }

    // Only process currently uninstalled modules.
    $installed_modules = $extension_config
      ->get('module') ?: [];
    if (!($module_list = array_diff_key($module_list, $installed_modules))) {

      // Nothing to do. All modules already installed.
      return TRUE;
    }

    // Add dependencies to the list. The new modules will be processed as
    // the foreach loop continues.
    foreach ($module_list as $module => $value) {
      foreach (array_keys($module_data[$module]->requires) as $dependency) {
        if (!isset($module_data[$dependency])) {

          // The dependency does not exist.
          throw new MissingDependencyException("Unable to install modules: module '{$module}' is missing its dependency module {$dependency}.");
        }

        // Skip already installed modules.
        if (!isset($module_list[$dependency]) && !isset($installed_modules[$dependency])) {
          if ($module_data[$dependency]->info['core_incompatible']) {
            throw new MissingDependencyException("Unable to install modules: module '{$module}'. Its dependency module '{$dependency}' is incompatible with this version of Drupal core.");
          }
          $module_list[$dependency] = $dependency;
        }
      }
    }

    // Set the actual module weights.
    $module_list = array_map(function ($module) use ($module_data) {
      return $module_data[$module]->sort;
    }, $module_list);

    // Sort the module list by their weights (reverse).
    arsort($module_list);
    $module_list = array_keys($module_list);
  }

  // Required for module installation checks.
  include_once $this->root . '/core/includes/install.inc';

  /** @var \Drupal\Core\Config\ConfigInstaller $config_installer */
  $config_installer = \Drupal::service('config.installer');
  $sync_status = $config_installer
    ->isSyncing();
  if ($sync_status) {
    $source_storage = $config_installer
      ->getSourceStorage();
  }
  $modules_installed = [];
  foreach ($module_list as $module) {
    $enabled = $extension_config
      ->get("module.{$module}") !== NULL;
    if (!$enabled) {

      // Throw an exception if the module name is too long.
      if (strlen($module) > DRUPAL_EXTENSION_NAME_MAX_LENGTH) {
        throw new ExtensionNameLengthException("Module name '{$module}' is over the maximum allowed length of " . DRUPAL_EXTENSION_NAME_MAX_LENGTH . ' characters');
      }

      // Load a new config object for each iteration, otherwise changes made
      // in hook_install() are not reflected in $extension_config.
      $extension_config = \Drupal::configFactory()
        ->getEditable('core.extension');

      // Check the validity of the default configuration. This will throw
      // exceptions if the configuration is not valid.
      $config_installer
        ->checkConfigurationToInstall('module', $module);

      // Save this data without checking schema. This is a performance
      // improvement for module installation.
      $extension_config
        ->set("module.{$module}", 0)
        ->set('module', module_config_sort($extension_config
        ->get('module')))
        ->save(TRUE);

      // Prepare the new module list, sorted by weight, including filenames.
      // This list is used for both the ModuleHandler and DrupalKernel. It
      // needs to be kept in sync between both. A DrupalKernel reboot or
      // rebuild will automatically re-instantiate a new ModuleHandler that
      // uses the new module list of the kernel. However, DrupalKernel does
      // not cause any modules to be loaded.
      // Furthermore, the currently active (fixed) module list can be
      // different from the configured list of enabled modules. For all active
      // modules not contained in the configured enabled modules, we assume a
      // weight of 0.
      $current_module_filenames = $this->moduleHandler
        ->getModuleList();
      $current_modules = array_fill_keys(array_keys($current_module_filenames), 0);
      $current_modules = module_config_sort(array_merge($current_modules, $extension_config
        ->get('module')));
      $module_filenames = [];
      foreach ($current_modules as $name => $weight) {
        if (isset($current_module_filenames[$name])) {
          $module_filenames[$name] = $current_module_filenames[$name];
        }
        else {
          $module_path = \Drupal::service('extension.list.module')
            ->getPath($name);
          $pathname = "{$module_path}/{$name}.info.yml";
          $filename = file_exists($module_path . "/{$name}.module") ? "{$name}.module" : NULL;
          $module_filenames[$name] = new Extension($this->root, 'module', $pathname, $filename);
        }
      }

      // Update the module handler in order to have the correct module list
      // for the kernel update.
      $this->moduleHandler
        ->setModuleList($module_filenames);

      // Clear the static cache of the "extension.list.module" service to pick
      // up the new module, since it merges the installation status of modules
      // into its statically cached list.
      \Drupal::service('extension.list.module')
        ->reset();

      // Update the kernel to include it.
      $this
        ->updateKernel($module_filenames);

      // Load the module's .module and .install files.
      $this->moduleHandler
        ->load($module);
      $this->moduleHandler
        ->loadInclude($module, 'install');
      if (!InstallerKernel::installationAttempted()) {

        // Replace the route provider service with a version that will rebuild
        // if routes used during installation. This ensures that a module's
        // routes are available during installation. This has to occur before
        // any services that depend on it are instantiated otherwise those
        // services will have the old route provider injected. Note that, since
        // the container is rebuilt by updating the kernel, the route provider
        // service is the regular one even though we are in a loop and might
        // have replaced it before.
        \Drupal::getContainer()
          ->set('router.route_provider.old', \Drupal::service('router.route_provider'));
        \Drupal::getContainer()
          ->set('router.route_provider', \Drupal::service('router.route_provider.lazy_builder'));
      }

      // Allow modules to react prior to the installation of a module.
      $this->moduleHandler
        ->invokeAll('module_preinstall', [
        $module,
      ]);

      // Now install the module's schema if necessary.
      $this
        ->installSchema($module);

      // Clear plugin manager caches.
      \Drupal::getContainer()
        ->get('plugin.cache_clearer')
        ->clearCachedDefinitions();

      // Set the schema version to the number of the last update provided by
      // the module, or the minimum core schema version.
      $version = \Drupal::CORE_MINIMUM_SCHEMA_VERSION;
      $versions = $this->updateRegistry
        ->getAvailableUpdates($module);
      if ($versions) {
        $version = max(max($versions), $version);
      }

      // Notify interested components that this module's entity types and
      // field storage definitions are new. For example, a SQL-based storage
      // handler can use this as an opportunity to create the necessary
      // database tables.
      // @todo Clean this up in https://www.drupal.org/node/2350111.
      $entity_type_manager = \Drupal::entityTypeManager();
      $update_manager = \Drupal::entityDefinitionUpdateManager();

      /** @var \Drupal\Core\Entity\EntityFieldManagerInterface $entity_field_manager */
      $entity_field_manager = \Drupal::service('entity_field.manager');
      foreach ($entity_type_manager
        ->getDefinitions() as $entity_type) {
        $is_fieldable_entity_type = $entity_type
          ->entityClassImplements(FieldableEntityInterface::class);
        if ($entity_type
          ->getProvider() == $module) {
          if ($is_fieldable_entity_type) {
            $update_manager
              ->installFieldableEntityType($entity_type, $entity_field_manager
              ->getFieldStorageDefinitions($entity_type
              ->id()));
          }
          else {
            $update_manager
              ->installEntityType($entity_type);
          }
        }
        elseif ($is_fieldable_entity_type) {

          // The module being installed may be adding new fields to existing
          // entity types. Field definitions for any entity type defined by
          // the module are handled in the if branch.
          foreach ($entity_field_manager
            ->getFieldStorageDefinitions($entity_type
            ->id()) as $storage_definition) {
            if ($storage_definition
              ->getProvider() == $module) {

              // If the module being installed is also defining a storage key
              // for the entity type, the entity schema may not exist yet. It
              // will be created later in that case.
              try {
                $update_manager
                  ->installFieldStorageDefinition($storage_definition
                  ->getName(), $entity_type
                  ->id(), $module, $storage_definition);
              } catch (EntityStorageException $e) {
                watchdog_exception('system', $e, 'An error occurred while notifying the creation of the @name field storage definition: "@message" in %function (line %line of %file).', [
                  '@name' => $storage_definition
                    ->getName(),
                  '@message' => $e
                    ->getMessage(),
                ]);
              }
            }
          }
        }
      }

      // Install default configuration of the module.
      $config_installer = \Drupal::service('config.installer');
      if ($sync_status) {
        $config_installer
          ->setSyncing(TRUE)
          ->setSourceStorage($source_storage);
      }
      \Drupal::service('config.installer')
        ->installDefaultConfig('module', $module);

      // If the module has no current updates, but has some that were
      // previously removed, set the version to the value of
      // hook_update_last_removed().
      if ($last_removed = $this->moduleHandler
        ->invoke($module, 'update_last_removed')) {
        $version = max($version, $last_removed);
      }
      $this->updateRegistry
        ->setInstalledVersion($module, $version);

      // Record the fact that it was installed.
      $modules_installed[] = $module;

      // Drupal's stream wrappers needs to be re-registered in case a
      // module-provided stream wrapper is used later in the same request. In
      // particular, this happens when installing Drupal via Drush, as the
      // 'translations' stream wrapper is provided by Interface Translation
      // module and is later used to import translations.
      \Drupal::service('stream_wrapper_manager')
        ->register();

      // Update the theme registry to include it.
      drupal_theme_rebuild();

      // Modules can alter theme info, so refresh theme data.
      // @todo ThemeHandler cannot be injected into ModuleHandler, since that
      //   causes a circular service dependency.
      // @see https://www.drupal.org/node/2208429
      \Drupal::service('theme_handler')
        ->refreshInfo();

      // Allow the module to perform install tasks.
      $this->moduleHandler
        ->invoke($module, 'install', [
        $sync_status,
      ]);

      // Record the fact that it was installed.
      \Drupal::logger('system')
        ->info('%module module installed.', [
        '%module' => $module,
      ]);
    }
  }

  // If any modules were newly installed, invoke hook_modules_installed().
  if (!empty($modules_installed)) {
    if (!InstallerKernel::installationAttempted()) {

      // If the container was rebuilt during hook_install() it might not have
      // the 'router.route_provider.old' service.
      if (\Drupal::hasService('router.route_provider.old')) {
        \Drupal::getContainer()
          ->set('router.route_provider', \Drupal::service('router.route_provider.old'));
      }
      if (!\Drupal::service('router.route_provider.lazy_builder')
        ->hasRebuilt()) {

        // Rebuild routes after installing module. This is done here on top of
        // \Drupal\Core\Routing\RouteBuilder::destruct to not run into errors on
        // fastCGI which executes ::destruct() after the module installation
        // page was sent already.
        \Drupal::service('router.builder')
          ->rebuild();
      }
    }
    $this->moduleHandler
      ->invokeAll('modules_installed', [
      $modules_installed,
      $sync_status,
    ]);
  }
  return TRUE;
}