Allow File::find() to run over multiple directories

Author: lkrms

src/Facade/File.php

@@ -15,7 +15,7 @@
  * @method static bool isLoaded() True if an underlying Filesystem instance has been loaded
  * @method static void unload() Clear the underlying Filesystem instance
  * @method static string createTemporaryDirectory() Create a temporary directory
- * @method static FluentIteratorInterface<string,SplFileInfo> find(string $directory, string|null $exclude = null, string|null $include = null, array<string,callable(SplFileInfo): bool> $excludeCallbacks = null, array<string,callable(SplFileInfo): bool> $includeCallbacks = null, bool $recursive = true, bool $withDirectories = false, bool $withDirectoriesFirst = true) Iterate over files in a directory (see {@see Filesystem::find()})
+ * @method static FluentIteratorInterface<string,SplFileInfo> find(string|string[] $directory, string|null $exclude = null, string|null $include = null, array<string,callable(SplFileInfo): bool> $excludeCallbacks = null, array<string,callable(SplFileInfo): bool> $includeCallbacks = null, bool $recursive = true, bool $withDirectories = false, bool $withDirectoriesFirst = true) Iterate over files in a directory (see {@see Filesystem::find()})
  * @method static string|null getEol(string $filename) Get the end-of-line sequence used in a file (see {@see Filesystem::getEol()})
  * @method static string getStablePath(string $suffix = '', ?string $dir = null) Generate a filename unique to the current user and the path of the running script (see {@see Filesystem::getStablePath()})
  * @method static string|null getStreamUri(resource $stream) Get the URI or filename associated with a stream (see {@see Filesystem::getStreamUri()})

src/Utility/Filesystem.php

@@ -4,11 +4,11 @@
 
 use Lkrms\Facade\Compute;
 use Lkrms\Facade\Console;
-use Lkrms\Facade\File;
 use Lkrms\Facade\Sys;
 use Lkrms\Support\Iterator\Contract\FluentIteratorInterface;
 use Lkrms\Utility\Convert;
 use Lkrms\Utility\Test;
+use AppendIterator;
 use CallbackFilterIterator;
 use FilesystemIterator;
 use LogicException;
@@ -30,6 +30,8 @@ final class Filesystem
      *
      * Exclusions are applied before inclusions.
      *
+     * @param string|string[] $directory One or multiple directories to iterate
+     * over.
      * @param string|null $exclude A regular expression that specifies paths to
      * exclude. No files are excluded if `null`.
      *
@@ -54,7 +56,7 @@ final class Filesystem
      * @return FluentIteratorInterface<string,SplFileInfo>
      */
     public function find(
-        string $directory,
+        $directory,
         ?string $exclude = null,
         ?string $include = null,
         ?array $excludeCallbacks = null,
@@ -113,30 +115,37 @@ function (SplFileInfo $current, string $key) use (
                     return !$include && !$includeCallbacks;
                 };
         }
-
-        if ($recursive) {
-            $iterator = new RecursiveDirectoryIterator($directory, $flags);
-            if ($callback ?? null) {
-                $iterator = new RecursiveCallbackFilterIterator($iterator, $callback);
+        /** @var AppendIterator|null */
+        $appendIterator = null;
+        /** @var non-empty-array<string> */
+        $directories = (array) $directory;
+        foreach ($directories as $directory) {
+            if ($recursive) {
+                $iterator = new RecursiveDirectoryIterator($directory, $flags);
+                if ($callback ?? null) {
+                    $iterator = new RecursiveCallbackFilterIterator($iterator, $callback);
+                }
+                $iterator = new RecursiveIteratorIterator($iterator, $mode);
+            } else {
+                $iterator = new FilesystemIterator($directory, $flags);
+                if ($callback ?? null) {
+                    $iterator = new CallbackFilterIterator($iterator, $callback);
+                }
+                if (!$withDirectories) {
+                    $iterator = new CallbackFilterIterator($iterator, fn(SplFileInfo $current) => !$current->isDir());
+                }
             }
-            $iterator = new RecursiveIteratorIterator($iterator, $mode);
-            /** @var FluentIteratorInterface<string,SplFileInfo> */
-            $iterator = new \Lkrms\Support\Iterator\FluentIterator($iterator);
 
-            return $iterator;
-        }
-
-        $iterator = new FilesystemIterator($directory, $flags);
-        if ($callback ?? null) {
-            $iterator = new CallbackFilterIterator($iterator, $callback);
-        }
-        if (!$withDirectories) {
-            $iterator = new CallbackFilterIterator($iterator, fn(SplFileInfo $current) => !$current->isDir());
+            if (!$appendIterator) {
+                if (count($directories) === 1) {
+                    break;
+                }
+                $appendIterator = new AppendIterator();
+            }
+            $appendIterator->append($iterator);
         }
-        /** @var FluentIteratorInterface<string,SplFileInfo> */
-        $iterator = new \Lkrms\Support\Iterator\FluentIterator($iterator);
 
-        return $iterator;
+        return new \Lkrms\Support\Iterator\FluentIterator($appendIterator ?? $iterator);
     }
 
     /**