feat: [FileCollection] add function to reatain multiple patterns

system/Files/FileCollection.php

@@ -340,6 +340,44 @@ public function retainPattern(string $pattern, ?string $scope = null)
         return $this->removeFiles(array_diff($files, self::matchFiles($files, $pattern)));
     }
 
+    /**
+     * Keeps only the files from the list that match multiple patterns
+     * (within the optional scope).
+     *
+     * @param list<string> $patterns Array of regex or pseudo-regex strings
+     * @param string|null  $scope    A directory to limit the scope
+     *
+     * @return $this
+     */
+    public function retainMultiplePatterns(array $patterns, ?string $scope = null)
+    {
+        if ($patterns === []) {
+            return $this;
+        }
+
+        if (count($patterns) === 1 && $patterns[0] === '') {
+            return $this;
+        }
+
+        // Start with all files or those in scope
+        $files = $scope === null ? $this->files : self::filterFiles($this->files, $scope);
+
+        // Add files to retain to array
+        $filesToRetain = [];
+
+        foreach ($patterns as $pattern) {
+            if ($pattern === '') {
+                continue;
+            }
+
+            // Matches the pattern within the scoped files
+            $filesToRetain = array_merge($filesToRetain, self::matchFiles($files, $pattern));
+        }
+
+        // Remove the inverse of files to retain
+        return $this->removeFiles(array_diff($files, $filesToRetain));
+    }
+
     // --------------------------------------------------------------------
     // Interface Methods
     // --------------------------------------------------------------------

tests/system/Files/FileCollectionTest.php

@@ -557,6 +557,76 @@ public function testRetainPatternScope(): void
         $this->assertSame($expected, $collection->get());
     }
 
+    public function testRetainMultiplePatternsEmptyArray(): void
+    {
+        $collection = new FileCollection();
+        $collection->addDirectory(SUPPORTPATH . 'Files', true);
+
+        $files = $collection->get();
+
+        $collection->retainMultiplePatterns([]);
+
+        $this->assertSame($files, $collection->get());
+    }
+
+    public function testRetainMultiplePatternsEmptyString(): void
+    {
+        $collection = new FileCollection();
+        $collection->addDirectory(SUPPORTPATH . 'Files', true);
+
+        $files = $collection->get();
+
+        $collection->retainMultiplePatterns(['']);
+
+        $this->assertSame($files, $collection->get());
+    }
+
+    public function testRetainMultiplePatternsRegex(): void
+    {
+        $collection = new FileCollection();
+        $collection->addDirectory(SUPPORTPATH . 'Files', true);
+
+        $expected = [
+            SUPPORTPATH . 'Files/able/apple.php',
+            SUPPORTPATH . 'Files/baker/banana.php',
+        ];
+
+        $collection->retainMultiplePatterns(['#(apple).*#', '#(banana).*#']);
+
+        $this->assertSame($expected, $collection->get());
+    }
+
+    public function testRetainMultiplePatternsPseudo(): void
+    {
+        $collection = new FileCollection();
+        $collection->addDirectory(SUPPORTPATH . 'Files', true);
+
+        $expected = [
+            SUPPORTPATH . 'Files/able/apple.php',
+            SUPPORTPATH . 'Files/baker/banana.php',
+        ];
+
+        $collection->retainMultiplePatterns(['apple*', 'banana*']);
+
+        $this->assertSame($expected, $collection->get());
+    }
+
+    public function testRetainMultiplePatternsScope(): void
+    {
+        $collection = new FileCollection();
+        $collection->addDirectory(SUPPORTPATH . 'Files', true);
+
+        $expected = [
+            $this->directory . 'fig_3.php',
+            SUPPORTPATH . 'Files/baker/banana.php',
+            SUPPORTPATH . 'Files/baker/fig_3.php.txt',
+        ];
+
+        $collection->retainMultiplePatterns(['*_?.php'], $this->directory);
+
+        $this->assertSame($expected, $collection->get());
+    }
+
     public function testCount(): void
     {
         $collection = new FileCollection();

user_guide_src/source/changelogs/v4.6.0.rst

@@ -108,6 +108,8 @@ Model
 Libraries
 =========
 
+- Added `retainMultiplePatterns()` to `FileCollection` class. See :ref:`FileCollection::retainMultiplePatterns() <file-collections-retain-multiple-patterns>`.
+
 Helpers and Functions
 =====================
 

user_guide_src/source/libraries/file_collections.rst

@@ -118,6 +118,18 @@ Examples:
 
 .. literalinclude:: files/015.php
 
+
+.. _file-collections-retain-multiple-patterns:
+
+retainMultiplePatterns(array $pattern, string $scope = null)
+============================================================
+
+Provides the same functionality as ``retainPattern()`` but accepts an array of patterns to retain files from all patterns.
+
+Example:
+
+.. literalinclude:: files/016.php
+
 ****************
 Retrieving Files
 ****************

user_guide_src/source/libraries/files/016.php

@@ -0,0 +1,3 @@
+<?php
+
+$files->retainMultiplePatterns(['*.css', '*.js']); // Would keep only *.css and *.js files