mirror of
https://github.com/codeigniter4/CodeIgniter4.git
synced 2025-02-20 11:44:28 +08:00
409 lines
11 KiB
PHP
409 lines
11 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
/**
|
|
* This file is part of CodeIgniter 4 framework.
|
|
*
|
|
* (c) CodeIgniter Foundation <admin@codeigniter.com>
|
|
*
|
|
* For the full copyright and license information, please view
|
|
* the LICENSE file that was distributed with this source code.
|
|
*/
|
|
|
|
namespace CodeIgniter\Files;
|
|
|
|
use CodeIgniter\Exceptions\InvalidArgumentException;
|
|
use CodeIgniter\Files\Exceptions\FileException;
|
|
use CodeIgniter\Files\Exceptions\FileNotFoundException;
|
|
use Countable;
|
|
use Generator;
|
|
use IteratorAggregate;
|
|
|
|
/**
|
|
* File Collection Class
|
|
*
|
|
* Representation for a group of files, with utilities for locating,
|
|
* filtering, and ordering them.
|
|
*
|
|
* @template-implements IteratorAggregate<int, File>
|
|
* @see \CodeIgniter\Files\FileCollectionTest
|
|
*/
|
|
class FileCollection implements Countable, IteratorAggregate
|
|
{
|
|
/**
|
|
* The current list of file paths.
|
|
*
|
|
* @var list<string>
|
|
*/
|
|
protected $files = [];
|
|
|
|
// --------------------------------------------------------------------
|
|
// Support Methods
|
|
// --------------------------------------------------------------------
|
|
|
|
/**
|
|
* Resolves a full path and verifies it is an actual directory.
|
|
*
|
|
* @throws FileException
|
|
*/
|
|
final protected static function resolveDirectory(string $directory): string
|
|
{
|
|
if (! is_dir($directory = set_realpath($directory))) {
|
|
$caller = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1];
|
|
|
|
throw FileException::forExpectedDirectory($caller['function']);
|
|
}
|
|
|
|
return $directory;
|
|
}
|
|
|
|
/**
|
|
* Resolves a full path and verifies it is an actual file.
|
|
*
|
|
* @throws FileException
|
|
*/
|
|
final protected static function resolveFile(string $file): string
|
|
{
|
|
if (! is_file($file = set_realpath($file))) {
|
|
$caller = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1];
|
|
|
|
throw FileException::forExpectedFile($caller['function']);
|
|
}
|
|
|
|
return $file;
|
|
}
|
|
|
|
/**
|
|
* Removes files that are not part of the given directory (recursive).
|
|
*
|
|
* @param list<string> $files
|
|
*
|
|
* @return list<string>
|
|
*/
|
|
final protected static function filterFiles(array $files, string $directory): array
|
|
{
|
|
$directory = self::resolveDirectory($directory);
|
|
|
|
return array_filter($files, static fn (string $value): bool => str_starts_with($value, $directory));
|
|
}
|
|
|
|
/**
|
|
* Returns any files whose `basename` matches the given pattern.
|
|
*
|
|
* @param list<string> $files
|
|
* @param string $pattern Regex or pseudo-regex string
|
|
*
|
|
* @return list<string>
|
|
*/
|
|
final protected static function matchFiles(array $files, string $pattern): array
|
|
{
|
|
// Convert pseudo-regex into their true form
|
|
if (@preg_match($pattern, '') === false) {
|
|
$pattern = str_replace(
|
|
['#', '.', '*', '?'],
|
|
['\#', '\.', '.*', '.'],
|
|
$pattern,
|
|
);
|
|
$pattern = "#\\A{$pattern}\\z#";
|
|
}
|
|
|
|
return array_filter($files, static fn ($value): bool => (bool) preg_match($pattern, basename($value)));
|
|
}
|
|
|
|
// --------------------------------------------------------------------
|
|
// Class Core
|
|
// --------------------------------------------------------------------
|
|
|
|
/**
|
|
* Loads the Filesystem helper and adds any initial files.
|
|
*
|
|
* @param list<string> $files
|
|
*/
|
|
public function __construct(array $files = [])
|
|
{
|
|
helper(['filesystem']);
|
|
|
|
$this->add($files)->define();
|
|
}
|
|
|
|
/**
|
|
* Applies any initial inputs after the constructor.
|
|
* This method is a stub to be implemented by child classes.
|
|
*/
|
|
protected function define(): void
|
|
{
|
|
}
|
|
|
|
/**
|
|
* Optimizes and returns the current file list.
|
|
*
|
|
* @return list<string>
|
|
*/
|
|
public function get(): array
|
|
{
|
|
$this->files = array_unique($this->files);
|
|
sort($this->files, SORT_STRING);
|
|
|
|
return $this->files;
|
|
}
|
|
|
|
/**
|
|
* Sets the file list directly, files are still subject to verification.
|
|
* This works as a "reset" method with [].
|
|
*
|
|
* @param list<string> $files The new file list to use
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function set(array $files)
|
|
{
|
|
$this->files = [];
|
|
|
|
return $this->addFiles($files);
|
|
}
|
|
|
|
/**
|
|
* Adds an array/single file or directory to the list.
|
|
*
|
|
* @param list<string>|string $paths
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function add($paths, bool $recursive = true)
|
|
{
|
|
$paths = (array) $paths;
|
|
|
|
foreach ($paths as $path) {
|
|
if (! is_string($path)) {
|
|
throw new InvalidArgumentException('FileCollection paths must be strings.');
|
|
}
|
|
|
|
try {
|
|
// Test for a directory
|
|
self::resolveDirectory($path);
|
|
} catch (FileException) {
|
|
$this->addFile($path);
|
|
|
|
continue;
|
|
}
|
|
|
|
$this->addDirectory($path, $recursive);
|
|
}
|
|
|
|
return $this;
|
|
}
|
|
|
|
// --------------------------------------------------------------------
|
|
// File Handling
|
|
// --------------------------------------------------------------------
|
|
|
|
/**
|
|
* Verifies and adds files to the list.
|
|
*
|
|
* @param list<string> $files
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function addFiles(array $files)
|
|
{
|
|
foreach ($files as $file) {
|
|
$this->addFile($file);
|
|
}
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Verifies and adds a single file to the file list.
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function addFile(string $file)
|
|
{
|
|
$this->files[] = self::resolveFile($file);
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Removes files from the list.
|
|
*
|
|
* @param list<string> $files
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function removeFiles(array $files)
|
|
{
|
|
$this->files = array_diff($this->files, $files);
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Removes a single file from the list.
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function removeFile(string $file)
|
|
{
|
|
return $this->removeFiles([$file]);
|
|
}
|
|
|
|
// --------------------------------------------------------------------
|
|
// Directory Handling
|
|
// --------------------------------------------------------------------
|
|
|
|
/**
|
|
* Verifies and adds files from each
|
|
* directory to the list.
|
|
*
|
|
* @param list<string> $directories
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function addDirectories(array $directories, bool $recursive = false)
|
|
{
|
|
foreach ($directories as $directory) {
|
|
$this->addDirectory($directory, $recursive);
|
|
}
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Verifies and adds all files from a directory.
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function addDirectory(string $directory, bool $recursive = false)
|
|
{
|
|
$directory = self::resolveDirectory($directory);
|
|
|
|
// Map the directory to depth 2 to so directories become arrays
|
|
foreach (directory_map($directory, 2, true) as $key => $path) {
|
|
if (is_string($path)) {
|
|
$this->addFile($directory . $path);
|
|
} elseif ($recursive && is_array($path)) {
|
|
$this->addDirectory($directory . $key, true);
|
|
}
|
|
}
|
|
|
|
return $this;
|
|
}
|
|
|
|
// --------------------------------------------------------------------
|
|
// Filtering
|
|
// --------------------------------------------------------------------
|
|
|
|
/**
|
|
* Removes any files from the list that match the supplied pattern
|
|
* (within the optional scope).
|
|
*
|
|
* @param string $pattern Regex or pseudo-regex string
|
|
* @param string|null $scope The directory to limit the scope
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function removePattern(string $pattern, ?string $scope = null)
|
|
{
|
|
if ($pattern === '') {
|
|
return $this;
|
|
}
|
|
|
|
// Start with all files or those in scope
|
|
$files = $scope === null ? $this->files : self::filterFiles($this->files, $scope);
|
|
|
|
// Remove any files that match the pattern
|
|
return $this->removeFiles(self::matchFiles($files, $pattern));
|
|
}
|
|
|
|
/**
|
|
* Keeps only the files from the list that match
|
|
* (within the optional scope).
|
|
*
|
|
* @param string $pattern Regex or pseudo-regex string
|
|
* @param string|null $scope A directory to limit the scope
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function retainPattern(string $pattern, ?string $scope = null)
|
|
{
|
|
if ($pattern === '') {
|
|
return $this;
|
|
}
|
|
|
|
// Start with all files or those in scope
|
|
$files = $scope === null ? $this->files : self::filterFiles($this->files, $scope);
|
|
|
|
// Matches the pattern within the scoped files and remove their inverse.
|
|
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
|
|
// --------------------------------------------------------------------
|
|
|
|
/**
|
|
* Returns the current number of files in the collection.
|
|
* Fulfills Countable.
|
|
*/
|
|
public function count(): int
|
|
{
|
|
return count($this->files);
|
|
}
|
|
|
|
/**
|
|
* Yields as an Iterator for the current files.
|
|
* Fulfills IteratorAggregate.
|
|
*
|
|
* @return Generator<File>
|
|
*
|
|
* @throws FileNotFoundException
|
|
*/
|
|
public function getIterator(): Generator
|
|
{
|
|
foreach ($this->get() as $file) {
|
|
yield new File($file, true);
|
|
}
|
|
}
|
|
}
|