abstract class ExtensionList in Drupal 9
Same name and namespace in other branches
- 8 core/lib/Drupal/Core/Extension/ExtensionList.php \Drupal\Core\Extension\ExtensionList
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
Hierarchy
- class \Drupal\Core\Extension\ExtensionList
Expanded class hierarchy of ExtensionList
2 files declare their use of ExtensionList
- CommonTestController.php in core/
modules/ system/ tests/ modules/ common_test/ src/ Controller/ CommonTestController.php - ExtensionListTest.php in core/
tests/ Drupal/ Tests/ Core/ Extension/ ExtensionListTest.php
File
- core/
lib/ Drupal/ Core/ Extension/ ExtensionList.php, line 21
Namespace
Drupal\Core\ExtensionView source
abstract class ExtensionList {
/**
* The type of the extension: "module", "theme" or "profile".
*
* @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
*/
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.
}
$this->cache
->delete($this
->getPathnamesCacheId());
// @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_name => $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();
if ($cache = $this->cache
->get($cache_id)) {
$path_names = $cache->data;
}
elseif (!($path_names = $this->state
->get($cache_id))) {
$path_names = $this
->recalculatePathnames();
// Store filenames to allow static::getPathname() to retrieve them
// without having to rebuild or scan the filesystem.
$this->state
->set($cache_id, $path_names);
$this->cache
->set($cache_id, $path_names);
}
$this->pathNames = $path_names;
}
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
->getMTime();
// Merge extension type-specific defaults.
$info += $this->defaults;
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']);
}
}Members
Name |
Modifiers | Type | Description | Overrides |
|---|---|---|---|---|
|
ExtensionList:: |
protected | property | A list of extension folder names directly added in code (not discovered). | |
|
ExtensionList:: |
protected | property | The cache. | |
|
ExtensionList:: |
protected | property | Default values to be merged into *.info.yml file arrays. | 4 |
|
ExtensionList:: |
protected | property | Static caching for extension info. | |
|
ExtensionList:: |
protected | property | The cached extensions. | |
|
ExtensionList:: |
protected | property | The info parser. | |
|
ExtensionList:: |
protected | property | The install profile used by the site. | |
|
ExtensionList:: |
protected | property | The module handler. | |
|
ExtensionList:: |
protected | property | A list of extension folder names keyed by extension name. | |
|
ExtensionList:: |
protected | property | The app root. | |
|
ExtensionList:: |
protected | property | The state store. | |
|
ExtensionList:: |
protected | property | The type of the extension: "module", "theme" or "profile". | |
|
ExtensionList:: |
public | function | Tests the compatibility of an extension. | |
|
ExtensionList:: |
protected | function | Creates the info value for an extension object. | 1 |
|
ExtensionList:: |
protected | function | Builds the list of extensions. | 2 |
|
ExtensionList:: |
protected | function | Scans the available extensions. | 1 |
|
ExtensionList:: |
public | function | Determines if an extension exists in the filesystem. | |
|
ExtensionList:: |
public | function | Returns a single extension. | |
|
ExtensionList:: |
public | function | Returns an array of info files information of available extensions. | |
|
ExtensionList:: |
public | function | Returns an array of info files information of installed extensions. | |
|
ExtensionList:: |
protected | function | Returns the extension discovery. | 3 |
|
ExtensionList:: |
public | function | Returns information about a specified extension. | |
|
ExtensionList:: |
protected | function | Returns the extension info cache ID. | |
|
ExtensionList:: |
abstract protected | function | Returns a list of machine names of installed extensions. | 5 |
|
ExtensionList:: |
public | function | Returns all available extensions. | |
|
ExtensionList:: |
protected | function | Returns the extension list cache ID. | |
|
ExtensionList:: |
public | function | Returns the human-readable name of the extension. | |
|
ExtensionList:: |
public | function | Gets the path to an extension of a specific type (module, theme, etc.). | |
|
ExtensionList:: |
public | function | Gets the info file path for an extension. | |
|
ExtensionList:: |
public | function | Returns a list of extension file paths keyed by machine name. | |
|
ExtensionList:: |
protected | function | Returns the extension filenames cache ID. | |
|
ExtensionList:: |
protected | function | Generates the information from .info.yml files for extensions of this type. | |
|
ExtensionList:: |
protected | function | Generates a sorted list of .info.yml file locations for all extensions. | |
|
ExtensionList:: |
public | function | Resets the stored extension list. | 1 |
|
ExtensionList:: |
public | function | Sets the pathname for an extension. | |
|
ExtensionList:: |
public static | function | Array sorting callback; sorts extensions by their name. | |
|
ExtensionList:: |
public | function | Constructs a new instance. | 2 |