function public function Theme::fileScan

8.x-3.x Theme.php public Theme::fileScan($mask, $subdir = NULL, array $options = [])

Wrapper for the core file_scan_directory() function.

Finds all files that match a given mask in the given directories and then caches the results. A general site cache clear will force new scans to be initiated for already cached directories.

Parameters

string $mask: The preg_match() regular expression of the files to find.

string $subdir: Sub-directory in the theme to start the scan, without trailing slash. If not set, the base path of the current theme will be used.

array $options: Options to pass, see file_scan_directory() for addition options:

  • ignore_flags: (int|FALSE) A bitmask to indicate which directories (if any) should be skipped during the scan. Must also not contain a "nomask" property in $options. Value can be any of the following:
    • \Drupal\bootstrap::IGNORE_CORE
    • \Drupal\bootstrap::IGNORE_ASSETS
    • \Drupal\bootstrap::IGNORE_DOCS
    • \Drupal\bootstrap::IGNORE_DEV
    • \Drupal\bootstrap::IGNORE_THEME
    Pass FALSE to iterate over all directories in $dir.

Return value

array An associative array (keyed on the chosen key) of objects with 'uri', 'filename', and 'name' members corresponding to the matching files.

Class

Theme
Defines a theme object.

Namespace

Drupal\bootstrap

Source src/Theme.php (line 301)

public function fileScan($mask, $subdir = NULL, array $options = []) {
  $path = $this->getPath();

  // Append addition sub-directories to the path if they were provided.
  if (isset($subdir)) {
    $path .= '/' . $subdir;
  }

  // Default ignore flags.
  $options += [
    'ignore_flags' => self::IGNORE_DEFAULT,
  ];
  $flags = $options['ignore_flags'];
  if ($flags === self::IGNORE_DEFAULT) {
    $flags = self::IGNORE_CORE | self::IGNORE_ASSETS | self::IGNORE_DOCS | self::IGNORE_DEV;
  }

  // Save effort by skipping directories that are flagged.
  if (!isset($options['nomask']) && $flags) {
    $ignore_directories = [];
    if ($flags & self::IGNORE_ASSETS) {
      $ignore_directories += ['assets', 'css', 'images', 'js'];
    }
    if ($flags & self::IGNORE_CORE) {
      $ignore_directories += ['config', 'lib', 'src'];
    }
    if ($flags & self::IGNORE_DOCS) {
      $ignore_directories += ['docs', 'documentation'];
    }
    if ($flags & self::IGNORE_DEV) {
      $ignore_directories += [
        'bower_components',
        'grunt',
        'node_modules',
        'starterkits',
      ];
    }
    if ($flags & self::IGNORE_TEMPLATES) {
      $ignore_directories += ['templates', 'theme'];
    }
    if (!empty($ignore_directories)) {
      $options['nomask'] = '/^' . implode('|', $ignore_directories) . '$/';
    }
  }

  // Retrieve cache.
  $files = $this->getCache('files');

  // Generate a unique hash for all parameters passed as a change in any of
  // them could potentially return different results.
  $hash = Crypt::generateBase64HashIdentifier($options, [$mask, $path]);

  if (!$files->has($hash)) {
    $files->set($hash, file_scan_directory($path, $mask, $options));
  }
  return $files->get($hash, []);
}