Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Extension;
Chris@0: 
Chris@0: use Drupal\Component\FileCache\FileCacheFactory;
Chris@0: use Drupal\Core\DrupalKernel;
Chris@0: use Drupal\Core\Extension\Discovery\RecursiveExtensionFilterIterator;
Chris@0: use Drupal\Core\Site\Settings;
Chris@0: use Symfony\Component\HttpFoundation\Request;
Chris@0: 
Chris@0: /**
Chris@0:  * Discovers available extensions in the filesystem.
Chris@0:  *
Chris@0:  * To also discover test modules, add
Chris@0:  * @code
Chris@0:  * $settings['extension_discovery_scan_tests'] = TRUE;
Chris@0:  * @endcode
Chris@0:  * to your settings.php.
Chris@0:  */
Chris@0: class ExtensionDiscovery {
Chris@0: 
Chris@0:   /**
Chris@0:    * Origin directory weight: Core.
Chris@0:    */
Chris@0:   const ORIGIN_CORE = 0;
Chris@0: 
Chris@0:   /**
Chris@0:    * Origin directory weight: Installation profile.
Chris@0:    */
Chris@0:   const ORIGIN_PROFILE = 1;
Chris@0: 
Chris@0:   /**
Chris@0:    * Origin directory weight: sites/all.
Chris@0:    */
Chris@0:   const ORIGIN_SITES_ALL = 2;
Chris@0: 
Chris@0:   /**
Chris@0:    * Origin directory weight: Site-wide directory.
Chris@0:    */
Chris@0:   const ORIGIN_ROOT = 3;
Chris@0: 
Chris@0:   /**
Chris@0:    * Origin directory weight: Parent site directory of a test site environment.
Chris@0:    */
Chris@0:   const ORIGIN_PARENT_SITE = 4;
Chris@0: 
Chris@0:   /**
Chris@0:    * Origin directory weight: Site-specific directory.
Chris@0:    */
Chris@0:   const ORIGIN_SITE = 5;
Chris@0: 
Chris@0:   /**
Chris@0:    * Regular expression to match PHP function names.
Chris@0:    *
Chris@0:    * @see http://php.net/manual/functions.user-defined.php
Chris@0:    */
Chris@0:   const PHP_FUNCTION_PATTERN = '/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/';
Chris@0: 
Chris@0:   /**
Chris@0:    * Previously discovered files keyed by origin directory and extension type.
Chris@0:    *
Chris@0:    * @var array
Chris@0:    */
Chris@0:   protected static $files = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * List of installation profile directories to additionally scan.
Chris@0:    *
Chris@0:    * @var array
Chris@0:    */
Chris@0:   protected $profileDirectories;
Chris@0: 
Chris@0:   /**
Chris@0:    * The app root for the current operation.
Chris@0:    *
Chris@0:    * @var string
Chris@0:    */
Chris@0:   protected $root;
Chris@0: 
Chris@0:   /**
Chris@0:    * The file cache object.
Chris@0:    *
Chris@0:    * @var \Drupal\Component\FileCache\FileCacheInterface
Chris@0:    */
Chris@0:   protected $fileCache;
Chris@0: 
Chris@0:   /**
Chris@0:    * The site path.
Chris@0:    *
Chris@0:    * @var string
Chris@0:    */
Chris@0:   protected $sitePath;
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs a new ExtensionDiscovery object.
Chris@0:    *
Chris@0:    * @param string $root
Chris@0:    *   The app root.
Chris@0:    * @param bool $use_file_cache
Chris@0:    *   Whether file cache should be used.
Chris@0:    * @param string[] $profile_directories
Chris@0:    *   The available profile directories
Chris@0:    * @param string $site_path
Chris@0:    *   The path to the site.
Chris@0:    */
Chris@0:   public function __construct($root, $use_file_cache = TRUE, $profile_directories = NULL, $site_path = NULL) {
Chris@0:     $this->root = $root;
Chris@0:     $this->fileCache = $use_file_cache ? FileCacheFactory::get('extension_discovery') : NULL;
Chris@0:     $this->profileDirectories = $profile_directories;
Chris@0:     $this->sitePath = $site_path;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Discovers available extensions of a given type.
Chris@0:    *
Chris@0:    * Finds all extensions (modules, themes, etc) that exist on the site. It
Chris@0:    * searches in several locations. For instance, to discover all available
Chris@0:    * modules:
Chris@0:    * @code
Chris@0:    * $listing = new ExtensionDiscovery(\Drupal::root());
Chris@0:    * $modules = $listing->scan('module');
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * The following directories will be searched (in the order stated):
Chris@0:    * - the core directory; i.e., /core
Chris@0:    * - the installation profile directory; e.g., /core/profiles/standard
Chris@0:    * - the legacy site-wide directory; i.e., /sites/all
Chris@0:    * - the site-wide directory; i.e., /
Chris@0:    * - the site-specific directory; e.g., /sites/example.com
Chris@0:    *
Chris@0:    * To also find test modules, add
Chris@0:    * @code
Chris@0:    * $settings['extension_discovery_scan_tests'] = TRUE;
Chris@0:    * @endcode
Chris@0:    * to your settings.php.
Chris@0:    *
Chris@0:    * The information is returned in an associative array, keyed by the extension
Chris@0:    * name (without .info.yml extension). Extensions found later in the search
Chris@0:    * will take precedence over extensions found earlier - unless they are not
Chris@0:    * compatible with the current version of Drupal core.
Chris@0:    *
Chris@0:    * @param string $type
Chris@0:    *   The extension type to search for. One of 'profile', 'module', 'theme', or
Chris@0:    *   'theme_engine'.
Chris@0:    * @param bool $include_tests
Chris@0:    *   (optional) Whether to explicitly include or exclude test extensions. By
Chris@0:    *   default, test extensions are only discovered when in a test environment.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Extension\Extension[]
Chris@0:    *   An associative array of Extension objects, keyed by extension name.
Chris@0:    */
Chris@0:   public function scan($type, $include_tests = NULL) {
Chris@0:     // Determine the installation profile directories to scan for extensions,
Chris@0:     // unless explicit profile directories have been set. Exclude profiles as we
Chris@0:     // cannot have profiles within profiles.
Chris@0:     if (!isset($this->profileDirectories) && $type != 'profile') {
Chris@0:       $this->setProfileDirectoriesFromSettings();
Chris@0:     }
Chris@0: 
Chris@0:     // Search the core directory.
Chris@0:     $searchdirs[static::ORIGIN_CORE] = 'core';
Chris@0: 
Chris@0:     // Search the legacy sites/all directory.
Chris@0:     $searchdirs[static::ORIGIN_SITES_ALL] = 'sites/all';
Chris@0: 
Chris@0:     // Search for contributed and custom extensions in top-level directories.
Chris@0:     // The scan uses a whitelist to limit recursion to the expected extension
Chris@0:     // type specific directory names only.
Chris@0:     $searchdirs[static::ORIGIN_ROOT] = '';
Chris@0: 
Chris@0:     // Simpletest uses the regular built-in multi-site functionality of Drupal
Chris@0:     // for running web tests. As a consequence, extensions of the parent site
Chris@0:     // located in a different site-specific directory are not discovered in a
Chris@0:     // test site environment, because the site directories are not the same.
Chris@0:     // Therefore, add the site directory of the parent site to the search paths,
Chris@0:     // so that contained extensions are still discovered.
Chris@0:     // @see \Drupal\simpletest\WebTestBase::setUp()
Chris@0:     if ($parent_site = Settings::get('test_parent_site')) {
Chris@0:       $searchdirs[static::ORIGIN_PARENT_SITE] = $parent_site;
Chris@0:     }
Chris@0: 
Chris@0:     // Find the site-specific directory to search. Since we are using this
Chris@0:     // method to discover extensions including profiles, we might be doing this
Chris@0:     // at install time. Therefore Kernel service is not always available, but is
Chris@0:     // preferred.
Chris@0:     if (\Drupal::hasService('kernel')) {
Chris@0:       $searchdirs[static::ORIGIN_SITE] = \Drupal::service('site.path');
Chris@0:     }
Chris@0:     else {
Chris@0:       $searchdirs[static::ORIGIN_SITE] = $this->sitePath ?: DrupalKernel::findSitePath(Request::createFromGlobals());
Chris@0:     }
Chris@0: 
Chris@0:     // Unless an explicit value has been passed, manually check whether we are
Chris@0:     // in a test environment, in which case test extensions must be included.
Chris@0:     // Test extensions can also be included for debugging purposes by setting a
Chris@0:     // variable in settings.php.
Chris@0:     if (!isset($include_tests)) {
Chris@0:       $include_tests = Settings::get('extension_discovery_scan_tests') || drupal_valid_test_ua();
Chris@0:     }
Chris@0: 
Chris@0:     $files = [];
Chris@0:     foreach ($searchdirs as $dir) {
Chris@0:       // Discover all extensions in the directory, unless we did already.
Chris@0:       if (!isset(static::$files[$this->root][$dir][$include_tests])) {
Chris@0:         static::$files[$this->root][$dir][$include_tests] = $this->scanDirectory($dir, $include_tests);
Chris@0:       }
Chris@0:       // Only return extensions of the requested type.
Chris@0:       if (isset(static::$files[$this->root][$dir][$include_tests][$type])) {
Chris@0:         $files += static::$files[$this->root][$dir][$include_tests][$type];
Chris@0:       }
Chris@0:     }
Chris@0: 
Chris@0:     // If applicable, filter out extensions that do not belong to the current
Chris@0:     // installation profiles.
Chris@0:     $files = $this->filterByProfileDirectories($files);
Chris@0:     // Sort the discovered extensions by their originating directories.
Chris@0:     $origin_weights = array_flip($searchdirs);
Chris@0:     $files = $this->sort($files, $origin_weights);
Chris@0: 
Chris@0:     // Process and return the list of extensions keyed by extension name.
Chris@0:     return $this->process($files);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets installation profile directories based on current site settings.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setProfileDirectoriesFromSettings() {
Chris@0:     $this->profileDirectories = [];
Chris@0:     $profile = drupal_get_profile();
Chris@0:     // For SimpleTest to be able to test modules packaged together with a
Chris@0:     // distribution we need to include the profile of the parent site (in
Chris@0:     // which test runs are triggered).
Chris@0:     if (drupal_valid_test_ua() && !drupal_installation_attempted()) {
Chris@0:       $testing_profile = \Drupal::config('simpletest.settings')->get('parent_profile');
Chris@0:       if ($testing_profile && $testing_profile != $profile) {
Chris@0:         $this->profileDirectories[] = drupal_get_path('profile', $testing_profile);
Chris@0:       }
Chris@0:     }
Chris@0:     // In case both profile directories contain the same extension, the actual
Chris@0:     // profile always has precedence.
Chris@0:     if ($profile) {
Chris@0:       $this->profileDirectories[] = drupal_get_path('profile', $profile);
Chris@0:     }
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the installation profile directories to be scanned.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   A list of installation profile directory paths relative to the system
Chris@0:    *   root directory.
Chris@0:    */
Chris@0:   public function getProfileDirectories() {
Chris@0:     return $this->profileDirectories;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets explicit profile directories to scan.
Chris@0:    *
Chris@0:    * @param array $paths
Chris@0:    *   A list of installation profile directory paths relative to the system
Chris@0:    *   root directory (without trailing slash) to search for extensions.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setProfileDirectories(array $paths = NULL) {
Chris@0:     $this->profileDirectories = $paths;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Filters out extensions not belonging to the scanned installation profiles.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Extension\Extension[] $all_files
Chris@0:    *   The list of all extensions.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Extension\Extension[]
Chris@0:    *   The filtered list of extensions.
Chris@0:    */
Chris@0:   protected function filterByProfileDirectories(array $all_files) {
Chris@0:     if (empty($this->profileDirectories)) {
Chris@0:       return $all_files;
Chris@0:     }
Chris@0: 
Chris@0:     $all_files = array_filter($all_files, function ($file) {
Chris@0:       if (strpos($file->subpath, 'profiles') !== 0) {
Chris@0:         // This extension doesn't belong to a profile, ignore it.
Chris@0:         return TRUE;
Chris@0:       }
Chris@0: 
Chris@0:       foreach ($this->profileDirectories as $weight => $profile_path) {
Chris@0:         if (strpos($file->getPath(), $profile_path) === 0) {
Chris@0:           // Parent profile found.
Chris@0:           return TRUE;
Chris@0:         }
Chris@0:       }
Chris@0: 
Chris@0:       return FALSE;
Chris@0:     });
Chris@0: 
Chris@0:     return $all_files;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sorts the discovered extensions.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Extension\Extension[] $all_files
Chris@0:    *   The list of all extensions.
Chris@0:    * @param array $weights
Chris@0:    *   An array of weights, keyed by originating directory.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Extension\Extension[]
Chris@0:    *   The sorted list of extensions.
Chris@0:    */
Chris@0:   protected function sort(array $all_files, array $weights) {
Chris@0:     $origins = [];
Chris@0:     $profiles = [];
Chris@0:     foreach ($all_files as $key => $file) {
Chris@0:       // If the extension does not belong to a profile, just apply the weight
Chris@0:       // of the originating directory.
Chris@0:       if (strpos($file->subpath, 'profiles') !== 0) {
Chris@0:         $origins[$key] = $weights[$file->origin];
Chris@0:         $profiles[$key] = NULL;
Chris@0:       }
Chris@0:       // If the extension belongs to a profile but no profile directories are
Chris@0:       // defined, then we are scanning for installation profiles themselves.
Chris@0:       // In this case, profiles are sorted by origin only.
Chris@0:       elseif (empty($this->profileDirectories)) {
Chris@0:         $origins[$key] = static::ORIGIN_PROFILE;
Chris@0:         $profiles[$key] = NULL;
Chris@0:       }
Chris@0:       else {
Chris@0:         // Apply the weight of the originating profile directory.
Chris@0:         foreach ($this->profileDirectories as $weight => $profile_path) {
Chris@0:           if (strpos($file->getPath(), $profile_path) === 0) {
Chris@0:             $origins[$key] = static::ORIGIN_PROFILE;
Chris@0:             $profiles[$key] = $weight;
Chris@0:             continue 2;
Chris@0:           }
Chris@0:         }
Chris@0:       }
Chris@0:     }
Chris@0:     // Now sort the extensions by origin and installation profile(s).
Chris@0:     // The result of this multisort can be depicted like the following matrix,
Chris@0:     // whereas the first integer is the weight of the originating directory and
Chris@0:     // the second is the weight of the originating installation profile:
Chris@0:     // 0   core/modules/node/node.module
Chris@0:     // 1 0 profiles/parent_profile/modules/parent_module/parent_module.module
Chris@0:     // 1 1 core/profiles/testing/modules/compatible_test/compatible_test.module
Chris@0:     // 2   sites/all/modules/common/common.module
Chris@0:     // 3   modules/devel/devel.module
Chris@0:     // 4   sites/default/modules/custom/custom.module
Chris@0:     array_multisort($origins, SORT_ASC, $profiles, SORT_ASC, $all_files);
Chris@0: 
Chris@0:     return $all_files;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Processes the filtered and sorted list of extensions.
Chris@0:    *
Chris@0:    * Extensions discovered in later search paths override earlier, unless they
Chris@0:    * are not compatible with the current version of Drupal core.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Extension\Extension[] $all_files
Chris@0:    *   The sorted list of all extensions that were found.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Extension\Extension[]
Chris@0:    *   The filtered list of extensions, keyed by extension name.
Chris@0:    */
Chris@0:   protected function process(array $all_files) {
Chris@0:     $files = [];
Chris@0:     // Duplicate files found in later search directories take precedence over
Chris@0:     // earlier ones; they replace the extension in the existing $files array.
Chris@0:     foreach ($all_files as $file) {
Chris@0:       $files[$file->getName()] = $file;
Chris@0:     }
Chris@0:     return $files;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@14:    * Recursively scans a base directory for the extensions it contains.
Chris@0:    *
Chris@0:    * @param string $dir
Chris@0:    *   A relative base directory path to scan, without trailing slash.
Chris@0:    * @param bool $include_tests
Chris@0:    *   Whether to include test extensions. If FALSE, all 'tests' directories are
Chris@0:    *   excluded in the search.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An associative array whose keys are extension type names and whose values
Chris@0:    *   are associative arrays of \Drupal\Core\Extension\Extension objects, keyed
Chris@0:    *   by absolute path name.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Extension\Discovery\RecursiveExtensionFilterIterator
Chris@0:    */
Chris@0:   protected function scanDirectory($dir, $include_tests) {
Chris@0:     $files = [];
Chris@0: 
Chris@0:     // In order to scan top-level directories, absolute directory paths have to
Chris@0:     // be used (which also improves performance, since any configured PHP
Chris@0:     // include_paths will not be consulted). Retain the relative originating
Chris@0:     // directory being scanned, so relative paths can be reconstructed below
Chris@0:     // (all paths are expected to be relative to $this->root).
Chris@0:     $dir_prefix = ($dir == '' ? '' : "$dir/");
Chris@0:     $absolute_dir = ($dir == '' ? $this->root : $this->root . "/$dir");
Chris@0: 
Chris@0:     if (!is_dir($absolute_dir)) {
Chris@0:       return $files;
Chris@0:     }
Chris@0:     // Use Unix paths regardless of platform, skip dot directories, follow
Chris@0:     // symlinks (to allow extensions to be linked from elsewhere), and return
Chris@0:     // the RecursiveDirectoryIterator instance to have access to getSubPath(),
Chris@0:     // since SplFileInfo does not support relative paths.
Chris@0:     $flags = \FilesystemIterator::UNIX_PATHS;
Chris@0:     $flags |= \FilesystemIterator::SKIP_DOTS;
Chris@0:     $flags |= \FilesystemIterator::FOLLOW_SYMLINKS;
Chris@0:     $flags |= \FilesystemIterator::CURRENT_AS_SELF;
Chris@0:     $directory_iterator = new \RecursiveDirectoryIterator($absolute_dir, $flags);
Chris@0: 
Chris@0:     // Allow directories specified in settings.php to be ignored. You can use
Chris@0:     // this to not check for files in common special-purpose directories. For
Chris@0:     // example, node_modules and bower_components. Ignoring irrelevant
Chris@0:     // directories is a performance boost.
Chris@0:     $ignore_directories = Settings::get('file_scan_ignore_directories', []);
Chris@0: 
Chris@0:     // Filter the recursive scan to discover extensions only.
Chris@0:     // Important: Without a RecursiveFilterIterator, RecursiveDirectoryIterator
Chris@0:     // would recurse into the entire filesystem directory tree without any kind
Chris@0:     // of limitations.
Chris@0:     $filter = new RecursiveExtensionFilterIterator($directory_iterator, $ignore_directories);
Chris@0:     $filter->acceptTests($include_tests);
Chris@0: 
Chris@0:     // The actual recursive filesystem scan is only invoked by instantiating the
Chris@0:     // RecursiveIteratorIterator.
Chris@0:     $iterator = new \RecursiveIteratorIterator($filter,
Chris@0:       \RecursiveIteratorIterator::LEAVES_ONLY,
Chris@0:       // Suppress filesystem errors in case a directory cannot be accessed.
Chris@0:       \RecursiveIteratorIterator::CATCH_GET_CHILD
Chris@0:     );
Chris@0: 
Chris@0:     foreach ($iterator as $key => $fileinfo) {
Chris@0:       // All extension names in Drupal have to be valid PHP function names due
Chris@0:       // to the module hook architecture.
Chris@0:       if (!preg_match(static::PHP_FUNCTION_PATTERN, $fileinfo->getBasename('.info.yml'))) {
Chris@0:         continue;
Chris@0:       }
Chris@0: 
Chris@0:       if ($this->fileCache && $cached_extension = $this->fileCache->get($fileinfo->getPathName())) {
Chris@0:         $files[$cached_extension->getType()][$key] = $cached_extension;
Chris@0:         continue;
Chris@0:       }
Chris@0: 
Chris@0:       // Determine extension type from info file.
Chris@0:       $type = FALSE;
Chris@0:       $file = $fileinfo->openFile('r');
Chris@0:       while (!$type && !$file->eof()) {
Chris@0:         preg_match('@^type:\s*(\'|")?(\w+)\1?\s*$@', $file->fgets(), $matches);
Chris@0:         if (isset($matches[2])) {
Chris@0:           $type = $matches[2];
Chris@0:         }
Chris@0:       }
Chris@0:       if (empty($type)) {
Chris@0:         continue;
Chris@0:       }
Chris@0:       $name = $fileinfo->getBasename('.info.yml');
Chris@0:       $pathname = $dir_prefix . $fileinfo->getSubPathname();
Chris@0: 
Chris@0:       // Determine whether the extension has a main extension file.
Chris@0:       // For theme engines, the file extension is .engine.
Chris@0:       if ($type == 'theme_engine') {
Chris@0:         $filename = $name . '.engine';
Chris@0:       }
Chris@0:       // For profiles/modules/themes, it is the extension type.
Chris@0:       else {
Chris@0:         $filename = $name . '.' . $type;
Chris@0:       }
Chris@0:       if (!file_exists($this->root . '/' . dirname($pathname) . '/' . $filename)) {
Chris@0:         $filename = NULL;
Chris@0:       }
Chris@0: 
Chris@0:       $extension = new Extension($this->root, $type, $pathname, $filename);
Chris@0: 
Chris@0:       // Track the originating directory for sorting purposes.
Chris@0:       $extension->subpath = $fileinfo->getSubPath();
Chris@0:       $extension->origin = $dir;
Chris@0: 
Chris@0:       $files[$type][$key] = $extension;
Chris@0: 
Chris@0:       if ($this->fileCache) {
Chris@0:         $this->fileCache->set($fileinfo->getPathName(), $extension);
Chris@0:       }
Chris@0:     }
Chris@0:     return $files;
Chris@0:   }
Chris@0: 
Chris@0: }