8.5.x file.inc file_scan_directory($dir, $mask, $options = [], $depth = 0)
8.0.x file.inc file_scan_directory($dir, $mask, $options = array(), $depth = 0)
8.1.x file.inc file_scan_directory($dir, $mask, $options = array(), $depth = 0)
8.2.x file.inc file_scan_directory($dir, $mask, $options = array(), $depth = 0)
8.3.x file.inc file_scan_directory($dir, $mask, $options = [], $depth = 0)
8.4.x file.inc file_scan_directory($dir, $mask, $options = [], $depth = 0)
8.6.x file.inc file_scan_directory($dir, $mask, $options = [], $depth = 0)
4.6.x file.inc file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0)
4.7.x file.inc file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0)
5.x file.inc file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0)
6.x file.inc file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0)
7.x file.inc file_scan_directory($dir, $mask, $options = array(), $depth = 0)

Finds all files that match a given mask in a given directory. Directories and files beginning with a period are excluded; this prevents hidden files and directories (such as SVN working directories) from being scanned.

Parameters

$dir: The base directory for the scan.

$mask: The regular expression of the files to find.

$nomask: An array of files/directories to ignore.

$callback: The callback function to call for each match.

$recurse: When TRUE, the directory scan will recurse the entire tree starting at the provided directory.

$key: The key to be used for the returned array of files. Possible values are "filename", for the path starting with $dir, "basename", for the basename of the file, and "name" for the name of the file without an extension.

$min_depth: Minimum depth of directories to return files from.

$depth: Current depth of recursion. This parameter is only used internally and should not be passed.

Return value

An associative array (keyed on the provided key) of objects with "path", "basename", and "name" members corresponding to the matching files.

Related topics

5 calls to file_scan_directory()
drupal_clear_css_cache in includes/common.inc
Delete all cached CSS files.
drupal_system_listing in includes/common.inc
Returns an array of files objects of the given type from the site-wide directory (i.e. modules/), the all-sites directory (i.e. sites/all/modules/), the profiles directory, and site-specific directory (i.e. sites/somesite/modules/). The returned array…
image_get_available_toolkits in includes/image.inc
Return a list of available toolkits.
install_select_locale in ./install.php
Find all .po files for the current profile and allow admin to select which to use.
install_select_profile in ./install.php
Find all .profile files and allow admin to select which to install.

File

includes/file.inc, line 635
API for handling file uploads and server file management.

Code

function file_scan_directory($dir, $mask, $nomask = array(
  '.',
  '..',
  'CVS',
), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0) {
  $key = in_array($key, array(
    'filename',
    'basename',
    'name',
  )) ? $key : 'filename';
  $files = array();
  if (is_dir($dir) && ($handle = opendir($dir))) {
    while (FALSE !== ($file = readdir($handle))) {
      if (!in_array($file, $nomask) && $file[0] != '.') {
        if (is_dir("{$dir}/{$file}") && $recurse) {
          $files = array_merge($files, file_scan_directory("{$dir}/{$file}", $mask, $nomask, $callback, $recurse, $key, $min_depth, $depth + 1));
        }
        elseif ($depth >= $min_depth && ereg($mask, $file)) {
          $filename = "{$dir}/{$file}";
          $basename = basename($file);
          $name = substr($basename, 0, strrpos($basename, '.'));
          $files[${$key}] = new stdClass();
          $files[${$key}]->filename = $filename;
          $files[${$key}]->basename = $basename;
          $files[${$key}]->name = $name;
          if ($callback) {
            $callback($filename);
          }
        }
      }
    }
    closedir($handle);
  }
  return $files;
}

Comments

xenophyle’s picture

Given a directory '/usr/me/stuff' containing
pictures (a directory)
resume.doc
notes.txt
theme.mp3

file_scan_directory('/usr/me/stuff', '.*', ('.', '..', 'CVS'), 0, FALSE);

will create an array containing the all contents of the directory except for '.' (this directory), '..' (the parent directory), and directories created by cvs. Contents of child directories will not be included.

Array (
/usr/me/stuff/pictures =>stdClass Object ( [filename] => /usr/me/stuff/pictures [basename] => pictures [name] => )
/usr/me/stuff/resume.doc=>stdClass Object ( [filename] => /usr/me/stuff/resume.doc [basename] => resume.doc [name] => resume)
/usr/me/stuff/notes.txt =>stdClass Object ( [filename] => /usr/me/stuff/notes.txt [basename] => notes.txt [name] => notes)
/usr/me/stuff/theme.mp3=>stdClass Object ( [filename] => /usr/me/stuff/theme.mp3 [basename] => theme.mp3 [name] => theme)
)

Hopefully this makes it clear what is meant by having the choice of filename, basename or name as the keys.

xetrokis’s picture

Hello,

file_scan_directory('/usr/me/stuff', '.*', ('.', '..', 'CVS'), 0, FALSE);
do not work for me, I use :
file_scan_directory('/usr/me/stuff', '.$', ('.', '..', 'CVS'), 0, FALSE);