function SystemListing::scan

Returns information about system object files (modules, themes, etc.).

This function is used to find all or some system object files (module files, theme files, etc.) that exist on the site. It searches in several locations, depending on what type of object you are looking for. For instance, if you are looking for modules and call:

$scanner = new SystemListing();
$all_profiles = $profiles_scanner
  ->scan('/^' . DRUPAL_PHP_FUNCTION_PATTERN . '\\.profile$/', 'profiles');

this function will search:

  • the core modules directory; i.e., /core/modules
  • the profiles directories as defined by the profiles() method.
  • the site-wide modules directory; i.e., /modules
  • the all-sites directory; i.e., /sites/all/modules
  • the site-specific directory; i.e., /sites/example.com/modules

in that order, and return information about all of the files ending in .module in those directories.

The information is returned in an associative array, which can be keyed on the file name ($key = 'filename'), the file name without the extension ($key = 'name'), or the full file stream URI ($key = 'uri'). If you use a key of 'filename' or 'name', files found later in the search will take precedence over files found earlier (unless they belong to a module or theme not compatible with Drupal core); if you choose a key of 'uri', you will get all files found.

Parameters

string $mask: The preg_match() regular expression for the files to find. The expression must be anchored and use DRUPAL_PHP_FUNCTION_PATTERN for the file name part before the extension, since the results could contain matches that do not present valid Drupal extensions otherwise.

string $directory: The subdirectory name in which the files are found. For example, 'modules' will search all 'modules' directories and their sub-directories as explained above.

string $key: (optional) The key to be used for the associative array returned. Possible values are:

  • 'uri' for the file's URI.
  • 'filename' for the basename of the file.
  • 'name' for the name of the file without the extension.

For 'name' and 'filename' only the highest-precedence file is returned. Defaults to 'name'.

Return value

array An associative array of file objects, keyed on the chosen key. Each element in the array is an object containing file information, with properties:

  • 'uri': Full URI of the file.
  • 'filename': File name.
  • 'name': Name of file without the extension.

File

drupal/core/lib/Drupal/Core/SystemListing.php, line 84
Definition of Drupal\Core\SystemListing.

Class

SystemListing
Returns information about system object files (modules, themes, etc.).

Namespace

Drupal\Core

Code

function scan($mask, $directory, $key = 'name') {
  if (!in_array($key, array(
    'uri',
    'filename',
    'name',
  ))) {
    $key = 'uri';
  }
  $config = conf_path();
  $files = array();

  // Search for the directory in core.
  $searchdir = array(
    'core/' . $directory,
  );
  foreach ($this
    ->profiles($directory) as $profile) {
    $searchdir[] = $profile;
  }

  // Always search for contributed and custom extensions in top-level
  // directories as well as sites/all/* directories. If the same extension is
  // located in both directories, then the latter wins for legacy/historical
  // reasons.
  $searchdir[] = $directory;
  $searchdir[] = 'sites/all/' . $directory;
  if (file_exists("{$config}/{$directory}")) {
    $searchdir[] = "{$config}/{$directory}";
  }

  // @todo Find a way to skip ./config directories (but not modules/config).
  $nomask = '/^(CVS|lib|templates|css|js)$/';
  $files = array();

  // Get current list of items.
  foreach ($searchdir as $dir) {
    $files = array_merge($files, $this
      ->process($files, $this
      ->scanDirectory($dir, $key, $mask, $nomask)));
  }
  return $files;
}