RecursiveExtensionFilterIterator.php

<?php

namespace Drupal\Core\Extension\Discovery;


/**
 * Filters a RecursiveDirectoryIterator to discover extensions.
 *
 * To ensure the best possible performance for extension discovery, this
 * filter implementation hard-codes a range of assumptions about directories
 * in which Drupal extensions may appear and in which not. Every unnecessary
 * subdirectory tree recursion is avoided.
 *
 * The list of globally ignored directory names is defined in the
 * RecursiveExtensionFilterIterator::$skippedFolders property.
 *
 * In addition, all 'config' directories are skipped, unless the directory path
 * ends with 'modules/config', so as to still find the config module provided by
 * Drupal core and still allow that module to be overridden with a custom config
 * module.
 *
 * Lastly, ExtensionDiscovery instructs this filter to additionally skip all
 * 'tests' directories at regular runtime, since just with Drupal core only, the
 * discovery process yields 4x more extensions when tests are not ignored.
 *
 * @see ExtensionDiscovery::scan()
 * @see ExtensionDiscovery::scanDirectory()
 *
 * @deprecated in drupal:10.2.0 and is removed from drupal:11.0.0. Use
 *   \Drupal\Core\Extension\Discovery\RecursiveExtensionFilterCallback instead.
 *
 * @see https://www.drupal.org/node/3343023
 */
class RecursiveExtensionFilterIterator extends \RecursiveFilterIterator {
  
  /**
   * List of base extension type directory names to scan.
   *
   * Only these directory names are considered when starting a filesystem
   * recursion in a search path.
   *
   * @var array
   */
  protected $allowedExtensionTypes = [
    'profiles',
    'modules',
    'themes',
  ];
  
  /**
   * List of directory names to skip when recursing.
   *
   * These directories are globally ignored in the recursive filesystem scan;
   * i.e., extensions (of all types) are not able to use any of these names,
   * because their directory names will be skipped.
   *
   * @var array
   */
  protected $skippedFolders = [
    // Object-oriented code subdirectories.
'src',
    'lib',
    'vendor',
    // Front-end.
'assets',
    'css',
    'files',
    'images',
    'js',
    'misc',
    'templates',
    // Legacy subdirectories.
'includes',
    // Test subdirectories.
'fixtures',
    // @todo ./tests/Drupal should be ./tests/src/Drupal
'Drupal',
  ];
  
  /**
   * Whether to include test directories when recursing.
   *
   * @var bool
   */
  protected $acceptTests = FALSE;
  
  /**
   * Construct a RecursiveExtensionFilterIterator.
   *
   * @param \RecursiveIterator $iterator
   *   The iterator to filter.
   * @param string[] $skipped_folders
   *   (optional) Add to the list of directories that should be filtered out
   *   during the iteration.
   */
  public function __construct(\RecursiveIterator $iterator, array $skipped_folders = []) {
    @trigger_error('The ' . __NAMESPACE__ . '\\RecursiveExtensionFilterIterator is deprecated in drupal:10.2.0 and is removed from drupal:11.0.0. Use \\Drupal\\Core\\Extension\\Discovery\\RecursiveExtensionFilterCallback instead. See https://www.drupal.org/node/3343023', E_USER_DEPRECATED);
    parent::__construct($iterator);
    $this->skippedFolders = array_merge($this->skippedFolders, $skipped_folders);
  }
  
  /**
   * Controls whether test directories will be scanned.
   *
   * @param bool $flag
   *   Pass FALSE to skip all test directories in the discovery. If TRUE,
   *   extensions in test directories will be discovered and only the global
   *   directory skip list in RecursiveExtensionFilterIterator::$skippedFolders
   *   is applied.
   */
  public function acceptTests($flag = FALSE) {
    $this->acceptTests = $flag;
    if (!$this->acceptTests) {
      $this->skippedFolders[] = 'tests';
    }
  }
  
  /**
   * {@inheritdoc}
   */
  public function getChildren() {
    $filter = parent::getChildren();
    // Pass on the skipped folders list.
    $filter->skippedFolders = $this->skippedFolders;
    // Pass the $acceptTests flag forward to child iterators.
    $filter->acceptTests($this->acceptTests);
    return $filter;
  }
  
  /**
   * {@inheritdoc}
   */
  public function accept() {
    $name = $this->current()
      ->getFilename();
    // FilesystemIterator::SKIP_DOTS only skips '.' and '..', but not hidden
    // directories (like '.git').
    if ($name[0] == '.') {
      return FALSE;
    }
    if ($this->current()
      ->isDir()) {
      // If this is a subdirectory of a base search path, only recurse into the
      // fixed list of expected extension type directory names. Required for
      // scanning the top-level/root directory; without this condition, we would
      // recurse into the whole filesystem tree that possibly contains other
      // files aside from Drupal.
      if ($this->current()
        ->getSubPath() == '') {
        return in_array($name, $this->allowedExtensionTypes, TRUE);
      }
      // 'config' directories are special-cased here, because every extension
      // contains one. However, those default configuration directories cannot
      // contain extensions. The directory name cannot be globally skipped,
      // because core happens to have a directory of an actual module that is
      // named 'config'. By explicitly testing for that case, we can skip all
      // other config directories, and at the same time, still allow the core
      // config module to be overridden/replaced in a profile/site directory
      // (whereas it must be located directly in a modules directory).
      if ($name == 'config') {
        return str_ends_with($this->current()
          ->getPathname(), 'modules/config');
      }
      // Accept the directory unless the folder is skipped.
      return !in_array($name, $this->skippedFolders, TRUE);
    }
    else {
      // Only accept extension info files.
      return str_ends_with($name, '.info.yml');
    }
  }

}