ExtensionList.php

<?php

namespace Drupal\Core\Extension;

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Database\DatabaseExceptionWrapper;
use Drupal\Core\Extension\Exception\UnknownExtensionException;
use Drupal\Core\State\StateInterface;

/**
 * Provides available extensions.
 *
 * The extension list is per extension type, like module, theme and profile.
 *
 * @internal
 *   This class is not yet stable and therefore there are no guarantees that the
 *   internal implementations including constructor signature and protected
 *   properties / methods will not change over time. This will be reviewed after
 *   https://www.drupal.org/project/drupal/issues/2940481
 */
abstract class ExtensionList {

  /**
   * The type of the extension.
   *
   * Possible values: "module", "theme", "profile" or "database_driver".
   *
   * @var string
   */
  protected $type;

  /**
   * The app root.
   *
   * @var string
   */
  protected $root;

  /**
   * The cache.
   *
   * @var \Drupal\Core\Cache\CacheBackendInterface
   */
  protected $cache;

  /**
   * Default values to be merged into *.info.yml file arrays.
   *
   * @var mixed[]
   */
  protected $defaults = [];

  /**
   * The info parser.
   *
   * @var \Drupal\Core\Extension\InfoParserInterface
   */
  protected $infoParser;

  /**
   * The module handler.
   *
   * @var \Drupal\Core\Extension\ModuleHandlerInterface
   */
  protected $moduleHandler;

  /**
   * The cached extensions.
   *
   * @var \Drupal\Core\Extension\Extension[]|null
   */
  protected $extensions;

  /**
   * Static caching for extension info.
   *
   * Access this property's value through static::getAllInfo().
   *
   * @var array[]|null
   *   Keys are extension names, and values their info arrays (mixed[]).
   *
   * @see \Drupal\Core\Extension\ExtensionList::getAllAvailableInfo
   */
  protected $extensionInfo;

  /**
   * A list of extension folder names keyed by extension name.
   *
   * @var string[]|null
   */
  protected $pathNames;

  /**
   * A list of extension folder names directly added in code (not discovered).
   *
   * It is important to keep a separate list to ensure that it takes priority
   * over the discovered extension folders.
   *
   * @var string[]
   *
   * @internal
   */
  protected $addedPathNames = [];

  /**
   * The state store.
   *
   * @var \Drupal\Core\State\StateInterface
   */
  protected $state;

  /**
   * The install profile used by the site.
   *
   * @var string|false|null
   */
  protected $installProfile;

  /**
   * Constructs a new instance.
   *
   * @param string $root
   *   The app root.
   * @param string $type
   *   The extension type.
   * @param \Drupal\Core\Cache\CacheBackendInterface $cache
   *   The cache.
   * @param \Drupal\Core\Extension\InfoParserInterface $info_parser
   *   The info parser.
   * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
   *   The module handler.
   * @param \Drupal\Core\State\StateInterface $state
   *   The state.
   * @param string $install_profile
   *   The install profile used by the site.
   */
  public function __construct($root, $type, CacheBackendInterface $cache, InfoParserInterface $info_parser, ModuleHandlerInterface $module_handler, StateInterface $state, $install_profile) {
    $this->root = $root;
    $this->type = $type;
    $this->cache = $cache;
    $this->infoParser = $info_parser;
    $this->moduleHandler = $module_handler;
    $this->state = $state;
    $this->installProfile = $install_profile;
  }

  /**
   * Returns the extension discovery.
   *
   * @return \Drupal\Core\Extension\ExtensionDiscovery
   */
  protected function getExtensionDiscovery() {
    return new ExtensionDiscovery($this->root);
  }

  /**
   * Resets the stored extension list.
   *
   * We don't reset statically added filenames, as it is a static cache which
   * logically can't change. This is done for performance reasons of the
   * installer.
   *
   * @return $this
   */
  public function reset() {
    $this->extensions = NULL;
    $this->cache
      ->delete($this
      ->getListCacheId());
    $this->extensionInfo = NULL;
    $this->cache
      ->delete($this
      ->getInfoCacheId());
    $this->pathNames = NULL;
    try {
      $this->state
        ->delete($this
        ->getPathNamesCacheId());
    } catch (DatabaseExceptionWrapper $e) {

      // Ignore exceptions caused by a non existing {key_value} table in the
      // early installer.
    }

    // @todo In the long run it would be great to add the reset, but the early
    //   installer fails due to that. https://www.drupal.org/node/2719315 could
    //   help to resolve with that.
    return $this;
  }

  /**
   * Returns the extension list cache ID.
   *
   * @return string
   *   The list cache ID.
   */
  protected function getListCacheId() {
    return 'core.extension.list.' . $this->type;
  }

  /**
   * Returns the extension info cache ID.
   *
   * @return string
   *   The info cache ID.
   */
  protected function getInfoCacheId() {
    return "system.{$this->type}.info";
  }

  /**
   * Returns the extension filenames cache ID.
   *
   * @return string
   *   The filename cache ID.
   */
  protected function getPathNamesCacheId() {
    return "system.{$this->type}.files";
  }

  /**
   * Determines if an extension exists in the filesystem.
   *
   * @param string $extension_name
   *   The machine name of the extension.
   *
   * @return bool
   *   TRUE if the extension exists (regardless installed or not) and FALSE if
   *   not.
   */
  public function exists($extension_name) {
    $extensions = $this
      ->getList();
    return isset($extensions[$extension_name]);
  }

  /**
   * Returns the human-readable name of the extension.
   *
   * @param string $extension_name
   *   The machine name of the extension.
   *
   * @return string
   *   The human-readable name of the extension.
   *
   * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
   *   If there is no extension with the supplied machine name.
   */
  public function getName($extension_name) {
    return $this
      ->get($extension_name)->info['name'];
  }

  /**
   * Returns a single extension.
   *
   * @param string $extension_name
   *   The machine name of the extension.
   *
   * @return \Drupal\Core\Extension\Extension
   *   A processed extension object for the extension with the specified machine
   *   name.
   *
   * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
   *   If there is no extension with the supplied name.
   */
  public function get($extension_name) {
    $extensions = $this
      ->getList();
    if (isset($extensions[$extension_name])) {
      return $extensions[$extension_name];
    }
    throw new UnknownExtensionException("The {$this->type} {$extension_name} does not exist.");
  }

  /**
   * Returns all available extensions.
   *
   * @return \Drupal\Core\Extension\Extension[]
   *   Processed extension objects, keyed by machine name.
   */
  public function getList() {
    if ($this->extensions !== NULL) {
      return $this->extensions;
    }
    if ($cache = $this->cache
      ->get($this
      ->getListCacheId())) {
      $this->extensions = $cache->data;
      return $this->extensions;
    }
    $extensions = $this
      ->doList();
    $this->cache
      ->set($this
      ->getListCacheId(), $extensions);
    $this->extensions = $extensions;
    return $this->extensions;
  }

  /**
   * Scans the available extensions.
   *
   * Overriding this method gives other code the chance to add additional
   * extensions to this raw listing.
   *
   * @return \Drupal\Core\Extension\Extension[]
   *   Unprocessed extension objects, keyed by machine name.
   */
  protected function doScanExtensions() {
    return $this
      ->getExtensionDiscovery()
      ->scan($this->type);
  }

  /**
   * Builds the list of extensions.
   *
   * @return \Drupal\Core\Extension\Extension[]
   *   Processed extension objects, keyed by machine name.
   *
   * @throws \Drupal\Core\Extension\InfoParserException
   *   If one of the .info.yml files is incomplete, or causes a parsing error.
   */
  protected function doList() {

    // Find extensions.
    $extensions = $this
      ->doScanExtensions();

    // Read info files for each extension.
    foreach ($extensions as $extension) {
      $extension->info = $this
        ->createExtensionInfo($extension);

      // Invoke hook_system_info_alter() to give installed modules a chance to
      // modify the data in the .info.yml files if necessary.
      $this->moduleHandler
        ->alter('system_info', $extension->info, $extension, $this->type);
    }
    return $extensions;
  }

  /**
   * Returns information about a specified extension.
   *
   * This function returns the contents of the .info.yml file for the specified
   * extension.
   *
   * @param string $extension_name
   *   The name of an extension whose information shall be returned.
   *
   * @return mixed[]
   *   An associative array of extension information.
   *
   * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
   *   If there is no extension with the supplied name.
   */
  public function getExtensionInfo($extension_name) {
    $all_info = $this
      ->getAllInstalledInfo();
    if (isset($all_info[$extension_name])) {
      return $all_info[$extension_name];
    }
    throw new UnknownExtensionException("The {$this->type} {$extension_name} does not exist or is not installed.");
  }

  /**
   * Returns an array of info files information of available extensions.
   *
   * This function returns the processed contents (with added defaults) of the
   * .info.yml files.
   *
   * @return array[]
   *   An associative array of extension information arrays, keyed by extension
   *   name.
   */
  public function getAllAvailableInfo() {
    if ($this->extensionInfo === NULL) {
      $cache_id = $this
        ->getInfoCacheId();
      if ($cache = $this->cache
        ->get($cache_id)) {
        $info = $cache->data;
      }
      else {
        $info = $this
          ->recalculateInfo();
        $this->cache
          ->set($cache_id, $info);
      }
      $this->extensionInfo = $info;
    }
    return $this->extensionInfo;
  }

  /**
   * Returns a list of machine names of installed extensions.
   *
   * @return string[]
   *   The machine names of all installed extensions of this type.
   */
  protected abstract function getInstalledExtensionNames();

  /**
   * Returns an array of info files information of installed extensions.
   *
   * This function returns the processed contents (with added defaults) of the
   * .info.yml files.
   *
   * @return array[]
   *   An associative array of extension information arrays, keyed by extension
   *   name.
   */
  public function getAllInstalledInfo() {
    return array_intersect_key($this
      ->getAllAvailableInfo(), array_flip($this
      ->getInstalledExtensionNames()));
  }

  /**
   * Generates the information from .info.yml files for extensions of this type.
   *
   * @return array[]
   *   An array of arrays of .info.yml entries keyed by the machine name.
   */
  protected function recalculateInfo() {
    return array_map(function (Extension $extension) {
      return $extension->info;
    }, $this
      ->getList());
  }

  /**
   * Returns a list of extension file paths keyed by machine name.
   *
   * @return string[]
   */
  public function getPathNames() {
    if ($this->pathNames === NULL) {
      $cache_id = $this
        ->getPathNamesCacheId();
      $this->pathNames = $this->state
        ->get($cache_id);
      if ($this->pathNames === NULL) {
        $this->pathNames = $this
          ->recalculatePathNames();

        // Store filenames to allow static::getPathname() to retrieve them
        // without having to rebuild or scan the filesystem.
        $this->state
          ->set($cache_id, $this->pathNames);
      }
    }
    return $this->pathNames;
  }

  /**
   * Generates a sorted list of .info.yml file locations for all extensions.
   *
   * @return string[]
   *   An array of .info.yml file locations keyed by the extension machine name.
   */
  protected function recalculatePathNames() {
    $extensions = $this
      ->getList();
    ksort($extensions);
    return array_map(function (Extension $extension) {
      return $extension
        ->getPathname();
    }, $extensions);
  }

  /**
   * Sets the pathname for an extension.
   *
   * This method is used in the Drupal bootstrapping phase, when the extension
   * system is not fully initialized, to manually set locations of modules and
   * profiles needed to complete bootstrapping.
   *
   * It is not recommended to call this method except in those rare cases.
   *
   * @param string $extension_name
   *   The machine name of the extension.
   * @param string $pathname
   *   The pathname of the extension which is to be set explicitly rather
   *   than by consulting the dynamic extension listing.
   *
   * @internal
   *
   * @see ::getPathname
   */
  public function setPathname($extension_name, $pathname) {
    $this->addedPathNames[$extension_name] = $pathname;
  }

  /**
   * Gets the info file path for an extension.
   *
   * The info path, whether provided, cached, or retrieved from the database, is
   * only returned if the file exists.
   *
   * This function plays a key role in allowing Drupal's extensions (modules,
   * themes, profiles, theme_engines, etc.) to be located in different places
   * depending on a site's configuration. For example, a module 'foo' may
   * legally be located in any of these four places:
   *
   * - core/modules/foo/foo.info.yml
   * - modules/foo/foo.info.yml
   * - sites/all/modules/foo/foo.info.yml
   * - sites/example.com/modules/foo/foo.info.yml
   *
   * while a theme 'bar' may be located in any of the following four places:
   *
   * - core/themes/bar/bar.info.yml
   * - themes/bar/bar.info.yml
   * - sites/all/themes/bar/bar.info.yml
   * - sites/example.com/themes/bar/bar.info.yml
   *
   * An installation profile maybe be located in any of the following places:
   *
   * - core/profiles/baz/baz.info.yml
   * - profiles/baz/baz.info.yml
   *
   * Calling ExtensionList::getPathname('foo') will give you one of the above,
   * depending on where the extension is located and what type it is.
   *
   * @param string $extension_name
   *   The machine name of the extension for which the pathname is requested.
   *
   * @return string
   *   The drupal-root relative filename and path of the requested extension's
   *   .info.yml file.
   *
   * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
   *   If there is no extension with the supplied machine name.
   */
  public function getPathname($extension_name) {
    if (isset($this->addedPathNames[$extension_name])) {
      return $this->addedPathNames[$extension_name];
    }
    elseif (isset($this->pathNames[$extension_name])) {
      return $this->pathNames[$extension_name];
    }
    elseif (($path_names = $this
      ->getPathNames()) && isset($path_names[$extension_name])) {
      return $path_names[$extension_name];
    }
    throw new UnknownExtensionException("The {$this->type} {$extension_name} does not exist.");
  }

  /**
   * Gets the path to an extension of a specific type (module, theme, etc.).
   *
   * The path is the directory in which the .info file is located. This name is
   * coming from \SplFileInfo.
   *
   * @param string $extension_name
   *   The machine name of the extension for which the path is requested.
   *
   * @return string
   *   The Drupal-root-relative path to the specified extension.
   *
   * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
   *   If there is no extension with the supplied name.
   */
  public function getPath($extension_name) {
    return dirname($this
      ->getPathname($extension_name));
  }

  /**
   * Creates the info value for an extension object.
   *
   * @param \Drupal\Core\Extension\Extension $extension
   *   The extension whose info is to be altered.
   *
   * @return array
   *   The extension info array.
   */
  protected function createExtensionInfo(Extension $extension) {
    $info = $this->infoParser
      ->parse($extension
      ->getPathname());

    // Add the info file modification time, so it becomes available for
    // contributed extensions to use for ordering extension lists.
    $info['mtime'] = $extension
      ->getFileInfo()
      ->getMTime();

    // Merge extension type-specific defaults, making sure to replace NULL
    // values.
    foreach ($this->defaults as $key => $default_value) {
      if (!isset($info[$key])) {
        $info[$key] = $default_value;
      }
    }
    return $info;
  }

  /**
   * Tests the compatibility of an extension.
   *
   * @param string $name
   *   The extension name to check.
   *
   * @return bool
   *   TRUE if the extension is incompatible and FALSE if not.
   *
   * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
   *   If there is no extension with the supplied name.
   */
  public function checkIncompatibility($name) {
    $extension = $this
      ->get($name);
    return $extension->info['core_incompatible'] || isset($extension->info['php']) && version_compare(phpversion(), $extension->info['php']) < 0;
  }

  /**
   * Array sorting callback; sorts extensions by their name.
   *
   * @param \Drupal\Core\Extension\Extension $a
   *   The first extension to compare.
   * @param \Drupal\Core\Extension\Extension $b
   *   The second extension to compare.
   *
   * @return int
   *   Less than 0 if $a is less than $b, more than 0 if $a is greater than $b,
   *   and 0 if they are equal.
   */
  public static function sortByName(Extension $a, Extension $b) : int {
    return strcasecmp($a->info['name'], $b->info['name']);
  }

}