<?php


/**
 * 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.
 *
 * @param $dir
 *   The base directory for the scan, without trailing slash.
 * @param &$allfiles
 *   The array of files that were found.
 *   We don't pass this as a return value, to avoid too much array copying
 * @param &$hints
 *   array of directories to be excluded except for specified subdirectories
 * @param $mask
 *   The regular expression of the files to find.
 * @param $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.
 * @param $min_depth
 *   Minimum depth of directories to return files from.
 * @param $depth
 *   Current depth of recursion. This parameter is only used internally and should not be passed.
 *
 * @return
 *   An associative array (keyed on the provided key) of objects with
 *   "path", "basename", and "name" members corresponding to the
 *   matching files.
 */
function file_scan_system_directory($dir, &$allfiles, &$hints, $mask, $key = 'filename', $min_depth = 0, $depth = 0) {
  $key = (in_array($key, array('filename', 'basename', 'name')) ? $key : 'filename');
  $localfiles = array();
  
  // look for a hint file..
  if (is_file("$dir/scandir.ini")) {
    // file_parse_scandir_ini has yet to be defined..
    $local_hints = file_parse_scandir_ini("$dir/scandir.ini");
    foreach ($local_hints as $hint_base => $hint_elements) {
      $hints["$dir/$hint_base"] = $hint_elements;
    }
  }
  
  if (isset($hints[$dir])) {
    foreach ($hints[$dir] as $hint) {
      $fragments = explode('/', $hint);
      $file = array_pop($fragments);
      $subdir = (!count($fragments)) ? $dir : ($dir . '/' . implode('/', $fragments));
      _file_scan_system_directory($subdir, $element, $allfiles, $localfiles, $hints, $exclude, $mask, $key, $min_depth, $depth + count($fragments));
    }
  } else if (is_dir($dir) && $handle = opendir($dir)) {
    while (FALSE !== ($file = readdir($handle))) {
      _file_scan_system_directory($dir, $element, $allfiles, $localfiles, $hints, $mask, $key, $min_depth, $depth);
    }
    closedir($handle);
  }

  // make sure that local files come after the subdir files
  foreach ($localfiles as $k  => $v) {
    $allfiles[$k] = $v;
  }
}


/**
 * Params are like above, except
 * 
 * @param &$localfiles
 *   array to collect local files
 */
function _file_scan_system_directory_element($dir, $file, &$allfiles, &$localfiles, $hints, $mask, $key = 'filename', $min_depth = 0, $depth = 0) {
  if ($file != 'CVS' && $file[0] != '.') {
    if (is_dir("$dir/$element") && $recurse) {
      // scan the subdirectory.
      // found items are collected in $allfiles.
      file_scan_system_directory($subdir, $element, $allfiles, $hints, $mask, $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, '.'));
      $localfiles[$$key] = new stdClass();
      $localfiles[$$key]->filename = $filename;
      $localfiles[$$key]->basename = $basename;
      $localfiles[$$key]->name = $name;
    }
  }
}