3 namespace Drupal\Core\Extension;
5 use Drupal\Component\FileCache\FileCacheFactory;
6 use Drupal\Core\DrupalKernel;
7 use Drupal\Core\Extension\Discovery\RecursiveExtensionFilterIterator;
8 use Drupal\Core\Site\Settings;
9 use Symfony\Component\HttpFoundation\Request;
12 * Discovers available extensions in the filesystem.
14 * To also discover test modules, add
16 * $settings['extension_discovery_scan_tests'] = TRUE;
18 * to your settings.php.
20 class ExtensionDiscovery {
23 * Origin directory weight: Core.
25 const ORIGIN_CORE = 0;
28 * Origin directory weight: Installation profile.
30 const ORIGIN_PROFILE = 1;
33 * Origin directory weight: sites/all.
35 const ORIGIN_SITES_ALL = 2;
38 * Origin directory weight: Site-wide directory.
40 const ORIGIN_ROOT = 3;
43 * Origin directory weight: Parent site directory of a test site environment.
45 const ORIGIN_PARENT_SITE = 4;
48 * Origin directory weight: Site-specific directory.
50 const ORIGIN_SITE = 5;
53 * Regular expression to match PHP function names.
55 * @see http://php.net/manual/functions.user-defined.php
57 const PHP_FUNCTION_PATTERN = '/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/';
60 * Previously discovered files keyed by origin directory and extension type.
64 protected static $files = [];
67 * List of installation profile directories to additionally scan.
71 protected $profileDirectories;
74 * The app root for the current operation.
81 * The file cache object.
83 * @var \Drupal\Component\FileCache\FileCacheInterface
95 * Constructs a new ExtensionDiscovery object.
99 * @param bool $use_file_cache
100 * Whether file cache should be used.
101 * @param string[] $profile_directories
102 * The available profile directories
103 * @param string $site_path
104 * The path to the site.
106 public function __construct($root, $use_file_cache = TRUE, $profile_directories = NULL, $site_path = NULL) {
108 $this->fileCache = $use_file_cache ? FileCacheFactory::get('extension_discovery') : NULL;
109 $this->profileDirectories = $profile_directories;
110 $this->sitePath = $site_path;
114 * Discovers available extensions of a given type.
116 * Finds all extensions (modules, themes, etc) that exist on the site. It
117 * searches in several locations. For instance, to discover all available
120 * $listing = new ExtensionDiscovery(\Drupal::root());
121 * $modules = $listing->scan('module');
124 * The following directories will be searched (in the order stated):
125 * - the core directory; i.e., /core
126 * - the installation profile directory; e.g., /core/profiles/standard
127 * - the legacy site-wide directory; i.e., /sites/all
128 * - the site-wide directory; i.e., /
129 * - the site-specific directory; e.g., /sites/example.com
131 * To also find test modules, add
133 * $settings['extension_discovery_scan_tests'] = TRUE;
135 * to your settings.php.
137 * The information is returned in an associative array, keyed by the extension
138 * name (without .info.yml extension). Extensions found later in the search
139 * will take precedence over extensions found earlier - unless they are not
140 * compatible with the current version of Drupal core.
142 * @param string $type
143 * The extension type to search for. One of 'profile', 'module', 'theme', or
145 * @param bool $include_tests
146 * (optional) Whether to explicitly include or exclude test extensions. By
147 * default, test extensions are only discovered when in a test environment.
149 * @return \Drupal\Core\Extension\Extension[]
150 * An associative array of Extension objects, keyed by extension name.
152 public function scan($type, $include_tests = NULL) {
153 // Determine the installation profile directories to scan for extensions,
154 // unless explicit profile directories have been set. Exclude profiles as we
155 // cannot have profiles within profiles.
156 if (!isset($this->profileDirectories) && $type != 'profile') {
157 $this->setProfileDirectoriesFromSettings();
160 // Search the core directory.
161 $searchdirs[static::ORIGIN_CORE] = 'core';
163 // Search the legacy sites/all directory.
164 $searchdirs[static::ORIGIN_SITES_ALL] = 'sites/all';
166 // Search for contributed and custom extensions in top-level directories.
167 // The scan uses a whitelist to limit recursion to the expected extension
168 // type specific directory names only.
169 $searchdirs[static::ORIGIN_ROOT] = '';
171 // Simpletest uses the regular built-in multi-site functionality of Drupal
172 // for running web tests. As a consequence, extensions of the parent site
173 // located in a different site-specific directory are not discovered in a
174 // test site environment, because the site directories are not the same.
175 // Therefore, add the site directory of the parent site to the search paths,
176 // so that contained extensions are still discovered.
177 // @see \Drupal\simpletest\WebTestBase::setUp()
178 if ($parent_site = Settings::get('test_parent_site')) {
179 $searchdirs[static::ORIGIN_PARENT_SITE] = $parent_site;
182 // Find the site-specific directory to search. Since we are using this
183 // method to discover extensions including profiles, we might be doing this
184 // at install time. Therefore Kernel service is not always available, but is
186 if (\Drupal::hasService('kernel')) {
187 $searchdirs[static::ORIGIN_SITE] = \Drupal::service('site.path');
190 $searchdirs[static::ORIGIN_SITE] = $this->sitePath ?: DrupalKernel::findSitePath(Request::createFromGlobals());
193 // Unless an explicit value has been passed, manually check whether we are
194 // in a test environment, in which case test extensions must be included.
195 // Test extensions can also be included for debugging purposes by setting a
196 // variable in settings.php.
197 if (!isset($include_tests)) {
198 $include_tests = Settings::get('extension_discovery_scan_tests') || drupal_valid_test_ua();
202 foreach ($searchdirs as $dir) {
203 // Discover all extensions in the directory, unless we did already.
204 if (!isset(static::$files[$this->root][$dir][$include_tests])) {
205 static::$files[$this->root][$dir][$include_tests] = $this->scanDirectory($dir, $include_tests);
207 // Only return extensions of the requested type.
208 if (isset(static::$files[$this->root][$dir][$include_tests][$type])) {
209 $files += static::$files[$this->root][$dir][$include_tests][$type];
213 // If applicable, filter out extensions that do not belong to the current
214 // installation profiles.
215 $files = $this->filterByProfileDirectories($files);
216 // Sort the discovered extensions by their originating directories.
217 $origin_weights = array_flip($searchdirs);
218 $files = $this->sort($files, $origin_weights);
220 // Process and return the list of extensions keyed by extension name.
221 return $this->process($files);
225 * Sets installation profile directories based on current site settings.
229 public function setProfileDirectoriesFromSettings() {
230 $this->profileDirectories = [];
231 $profile = drupal_get_profile();
232 // For SimpleTest to be able to test modules packaged together with a
233 // distribution we need to include the profile of the parent site (in
234 // which test runs are triggered).
235 if (drupal_valid_test_ua() && !drupal_installation_attempted()) {
236 $testing_profile = \Drupal::config('simpletest.settings')->get('parent_profile');
237 if ($testing_profile && $testing_profile != $profile) {
238 $this->profileDirectories[] = drupal_get_path('profile', $testing_profile);
241 // In case both profile directories contain the same extension, the actual
242 // profile always has precedence.
244 $this->profileDirectories[] = drupal_get_path('profile', $profile);
250 * Gets the installation profile directories to be scanned.
253 * A list of installation profile directory paths relative to the system
256 public function getProfileDirectories() {
257 return $this->profileDirectories;
261 * Sets explicit profile directories to scan.
263 * @param array $paths
264 * A list of installation profile directory paths relative to the system
265 * root directory (without trailing slash) to search for extensions.
269 public function setProfileDirectories(array $paths = NULL) {
270 $this->profileDirectories = $paths;
275 * Filters out extensions not belonging to the scanned installation profiles.
277 * @param \Drupal\Core\Extension\Extension[] $all_files
278 * The list of all extensions.
280 * @return \Drupal\Core\Extension\Extension[]
281 * The filtered list of extensions.
283 protected function filterByProfileDirectories(array $all_files) {
284 if (empty($this->profileDirectories)) {
288 $all_files = array_filter($all_files, function ($file) {
289 if (strpos($file->subpath, 'profiles') !== 0) {
290 // This extension doesn't belong to a profile, ignore it.
294 foreach ($this->profileDirectories as $weight => $profile_path) {
295 if (strpos($file->getPath(), $profile_path) === 0) {
296 // Parent profile found.
308 * Sorts the discovered extensions.
310 * @param \Drupal\Core\Extension\Extension[] $all_files
311 * The list of all extensions.
312 * @param array $weights
313 * An array of weights, keyed by originating directory.
315 * @return \Drupal\Core\Extension\Extension[]
316 * The sorted list of extensions.
318 protected function sort(array $all_files, array $weights) {
321 foreach ($all_files as $key => $file) {
322 // If the extension does not belong to a profile, just apply the weight
323 // of the originating directory.
324 if (strpos($file->subpath, 'profiles') !== 0) {
325 $origins[$key] = $weights[$file->origin];
326 $profiles[$key] = NULL;
328 // If the extension belongs to a profile but no profile directories are
329 // defined, then we are scanning for installation profiles themselves.
330 // In this case, profiles are sorted by origin only.
331 elseif (empty($this->profileDirectories)) {
332 $origins[$key] = static::ORIGIN_PROFILE;
333 $profiles[$key] = NULL;
336 // Apply the weight of the originating profile directory.
337 foreach ($this->profileDirectories as $weight => $profile_path) {
338 if (strpos($file->getPath(), $profile_path) === 0) {
339 $origins[$key] = static::ORIGIN_PROFILE;
340 $profiles[$key] = $weight;
346 // Now sort the extensions by origin and installation profile(s).
347 // The result of this multisort can be depicted like the following matrix,
348 // whereas the first integer is the weight of the originating directory and
349 // the second is the weight of the originating installation profile:
350 // 0 core/modules/node/node.module
351 // 1 0 profiles/parent_profile/modules/parent_module/parent_module.module
352 // 1 1 core/profiles/testing/modules/compatible_test/compatible_test.module
353 // 2 sites/all/modules/common/common.module
354 // 3 modules/devel/devel.module
355 // 4 sites/default/modules/custom/custom.module
356 array_multisort($origins, SORT_ASC, $profiles, SORT_ASC, $all_files);
362 * Processes the filtered and sorted list of extensions.
364 * Extensions discovered in later search paths override earlier, unless they
365 * are not compatible with the current version of Drupal core.
367 * @param \Drupal\Core\Extension\Extension[] $all_files
368 * The sorted list of all extensions that were found.
370 * @return \Drupal\Core\Extension\Extension[]
371 * The filtered list of extensions, keyed by extension name.
373 protected function process(array $all_files) {
375 // Duplicate files found in later search directories take precedence over
376 // earlier ones; they replace the extension in the existing $files array.
377 foreach ($all_files as $file) {
378 $files[$file->getName()] = $file;
384 * Recursively scans a base directory for the requested extension type.
387 * A relative base directory path to scan, without trailing slash.
388 * @param bool $include_tests
389 * Whether to include test extensions. If FALSE, all 'tests' directories are
390 * excluded in the search.
393 * An associative array whose keys are extension type names and whose values
394 * are associative arrays of \Drupal\Core\Extension\Extension objects, keyed
395 * by absolute path name.
397 * @see \Drupal\Core\Extension\Discovery\RecursiveExtensionFilterIterator
399 protected function scanDirectory($dir, $include_tests) {
402 // In order to scan top-level directories, absolute directory paths have to
403 // be used (which also improves performance, since any configured PHP
404 // include_paths will not be consulted). Retain the relative originating
405 // directory being scanned, so relative paths can be reconstructed below
406 // (all paths are expected to be relative to $this->root).
407 $dir_prefix = ($dir == '' ? '' : "$dir/");
408 $absolute_dir = ($dir == '' ? $this->root : $this->root . "/$dir");
410 if (!is_dir($absolute_dir)) {
413 // Use Unix paths regardless of platform, skip dot directories, follow
414 // symlinks (to allow extensions to be linked from elsewhere), and return
415 // the RecursiveDirectoryIterator instance to have access to getSubPath(),
416 // since SplFileInfo does not support relative paths.
417 $flags = \FilesystemIterator::UNIX_PATHS;
418 $flags |= \FilesystemIterator::SKIP_DOTS;
419 $flags |= \FilesystemIterator::FOLLOW_SYMLINKS;
420 $flags |= \FilesystemIterator::CURRENT_AS_SELF;
421 $directory_iterator = new \RecursiveDirectoryIterator($absolute_dir, $flags);
423 // Allow directories specified in settings.php to be ignored. You can use
424 // this to not check for files in common special-purpose directories. For
425 // example, node_modules and bower_components. Ignoring irrelevant
426 // directories is a performance boost.
427 $ignore_directories = Settings::get('file_scan_ignore_directories', []);
429 // Filter the recursive scan to discover extensions only.
430 // Important: Without a RecursiveFilterIterator, RecursiveDirectoryIterator
431 // would recurse into the entire filesystem directory tree without any kind
433 $filter = new RecursiveExtensionFilterIterator($directory_iterator, $ignore_directories);
434 $filter->acceptTests($include_tests);
436 // The actual recursive filesystem scan is only invoked by instantiating the
437 // RecursiveIteratorIterator.
438 $iterator = new \RecursiveIteratorIterator($filter,
439 \RecursiveIteratorIterator::LEAVES_ONLY,
440 // Suppress filesystem errors in case a directory cannot be accessed.
441 \RecursiveIteratorIterator::CATCH_GET_CHILD
444 foreach ($iterator as $key => $fileinfo) {
445 // All extension names in Drupal have to be valid PHP function names due
446 // to the module hook architecture.
447 if (!preg_match(static::PHP_FUNCTION_PATTERN, $fileinfo->getBasename('.info.yml'))) {
451 if ($this->fileCache && $cached_extension = $this->fileCache->get($fileinfo->getPathName())) {
452 $files[$cached_extension->getType()][$key] = $cached_extension;
456 // Determine extension type from info file.
458 $file = $fileinfo->openFile('r');
459 while (!$type && !$file->eof()) {
460 preg_match('@^type:\s*(\'|")?(\w+)\1?\s*$@', $file->fgets(), $matches);
461 if (isset($matches[2])) {
468 $name = $fileinfo->getBasename('.info.yml');
469 $pathname = $dir_prefix . $fileinfo->getSubPathname();
471 // Determine whether the extension has a main extension file.
472 // For theme engines, the file extension is .engine.
473 if ($type == 'theme_engine') {
474 $filename = $name . '.engine';
476 // For profiles/modules/themes, it is the extension type.
478 $filename = $name . '.' . $type;
480 if (!file_exists($this->root . '/' . dirname($pathname) . '/' . $filename)) {
484 $extension = new Extension($this->root, $type, $pathname, $filename);
486 // Track the originating directory for sorting purposes.
487 $extension->subpath = $fileinfo->getSubPath();
488 $extension->origin = $dir;
490 $files[$type][$key] = $extension;
492 if ($this->fileCache) {
493 $this->fileCache->set($fileinfo->getPathName(), $extension);