Finder.php

Go to the documentation of this file.

<?php

declare(strict_types=1);

namespace ILIAS\Filesystem\Finder;

use ILIAS\Filesystem\Finder\Iterator\FileTypeFilterIterator;
use ILIAS\Filesystem\Finder\Comparator\NumberComparator;
use ILIAS\Filesystem\Finder\Comparator\DateComparator;
use ILIAS\Filesystem\Finder\Iterator\RecursiveDirectoryIterator;
use ILIAS\Filesystem\Finder\Iterator\ExcludeDirectoryFilterIterator;
use ILIAS\Filesystem\Finder\Iterator\DepthRangeFilterIterator;
use ILIAS\Filesystem\Finder\Iterator\DateRangeFilterIterator;
use ILIAS\Filesystem\Finder\Iterator\SizeRangeFilterIterator;
use AppendIterator;
use ArrayIterator;
use Closure;
use Countable;
use ILIAS\Filesystem\DTO\Metadata;
use ILIAS\Filesystem\Filesystem;
use ILIAS\Filesystem\MetadataType;
use InvalidArgumentException;
use Iterator as PhpIterator;
use IteratorAggregate;
use LogicException;
use RecursiveIteratorIterator;
use ILIAS\Filesystem\Finder\Iterator\SortableIterator;

final class Finder implements IteratorAggregate, Countable
{
    private const IGNORE_VCS_FILES = 1;
    private const IGNORE_DOT_FILES = 2;
    private array $vcsPatterns = ['.svn', '_svn', 'CVS', '_darcs', '.arch-params', '.monotone', '.bzr', '.git', '.hg'];
    private array $iterators = [];
    protected array $dirs = [];
    private array $exclude = [];
    private int $ignore = 0;
    private int $mode = FileTypeFilterIterator::ALL;
    private bool $reverseSorting = false;
    private array $dates = [];
    private array $sizes = [];
    private array $depths = [];
    private $sort = SortableIterator::SORT_BY_NONE;

    public function __construct(private Filesystem $filesystem)
    {
        $this->ignore = self::IGNORE_VCS_FILES | self::IGNORE_DOT_FILES;
    }

    public function files(): self
    {
        $clone = clone $this;
        $clone->mode = FileTypeFilterIterator::ONLY_FILES;

        return $clone;
    }

    public function directories(): self
    {
        $clone = clone $this;
        $clone->mode = FileTypeFilterIterator::ONLY_DIRECTORIES;

        return $clone;
    }

    public function allTypes(): self
    {
        $clone = clone $this;
        $clone->mode = FileTypeFilterIterator::ALL;

        return $clone;
    }

    public function exclude(array $directories): self
    {
        array_walk($directories, static function ($directory): void {
            if (!is_string($directory)) {
                throw new InvalidArgumentException(sprintf('Invalid directory given: %s', $directory::class));
            }
        });

        $clone = clone $this;
        $clone->exclude = array_merge($clone->exclude, $directories);

        return $clone;
    }

    public function in(array $directories): self
    {
        array_walk($directories, static function ($directory): void {
            if (!is_string($directory)) {
                throw new InvalidArgumentException(sprintf('Invalid directory given: %s', $directory::class));
            }
        });

        $clone = clone $this;
        $clone->dirs = array_unique(array_merge($clone->dirs, $directories));

        return $clone;
    }

    public function depth(string|int $level): self
    {
        $clone = clone $this;
        $clone->depths[] = new NumberComparator((string) $level);

        return $clone;
    }

    public function date(string $date): self
    {
        $clone = clone $this;
        $clone->dates[] = new DateComparator($date);

        return $clone;
    }

    public function size(string|int|array $sizes): self
    {
        $sizes = is_array($sizes) ? $sizes : [$sizes];

        $clone = clone $this;

        foreach ($sizes as $size) {
            $clone->sizes[] = new NumberComparator((string) $size);
        }

        return $clone;
    }

    public function reverseSorting(): self
    {
        $clone = clone $this;
        $clone->reverseSorting = true;

        return $clone;
    }

    public function ignoreVCS(bool $ignoreVCS): self
    {
        $clone = clone $this;
        if ($ignoreVCS) {
            $clone->ignore |= self::IGNORE_VCS_FILES;
        } else {
            $clone->ignore &= ~self::IGNORE_VCS_FILES;
        }

        return $clone;
    }

    public function addVCSPattern(array $pattern): self
    {
        array_walk($pattern, static function ($p): void {
            if (!is_string($p)) {
                throw new InvalidArgumentException(sprintf('Invalid pattern given: %s', $p::class));
            }
        });

        $clone = clone $this;
        foreach ($pattern as $p) {
            $clone->vcsPatterns[] = $p;
        }

        $clone->vcsPatterns = array_unique($clone->vcsPatterns);

        return $clone;
    }

    public function sort(Closure $closure): self
    {
        $clone = clone $this;
        $clone->sort = $closure;

        return $clone;
    }

    public function sortByName(bool $useNaturalSort = false): self
    {
        $clone = clone $this;
        $clone->sort = SortableIterator::SORT_BY_NAME;
        if ($useNaturalSort) {
            $clone->sort = SortableIterator::SORT_BY_NAME_NATURAL;
        }

        return $clone;
    }

    public function sortByType(): self
    {
        $clone = clone $this;
        $clone->sort = SortableIterator::SORT_BY_TYPE;

        return $clone;
    }

    public function sortByTime(): self
    {
        $clone = clone $this;
        $clone->sort = SortableIterator::SORT_BY_TIME;

        return $clone;
    }

    public function append(iterable $iterator): self
    {
        $clone = clone $this;

        if ($iterator instanceof IteratorAggregate) {
            $clone->iterators[] = $iterator->getIterator();
        } elseif ($iterator instanceof PhpIterator) {
            $clone->iterators[] = $iterator;
        } elseif (is_iterable($iterator)) {
            $it = new ArrayIterator();
            foreach ($iterator as $file) {
                if ($file instanceof MetadataType) {
                    $it->append($file);
                } else {
                    throw new InvalidArgumentException(
                        'Finder::append() method wrong argument type in passed iterator.'
                    );
                }
            }
            $clone->iterators[] = $it;
        } else {
            throw new InvalidArgumentException('Finder::append() method wrong argument type.');
        }

        return $clone;
    }

    private function searchInDirectory(string $dir): \Traversable
    {
        if (self::IGNORE_VCS_FILES === (self::IGNORE_VCS_FILES & $this->ignore)) {
            $this->exclude = array_merge($this->exclude, $this->vcsPatterns);
        }

        $iterator = new RecursiveDirectoryIterator($this->filesystem, $dir);

        if ($this->exclude) {
            $iterator = new ExcludeDirectoryFilterIterator($iterator, $this->exclude);
        }

        $iterator = new RecursiveIteratorIterator($iterator, \RecursiveIteratorIterator::SELF_FIRST);

        if ($this->depths) {
            $iterator = new DepthRangeFilterIterator($iterator, $this->depths);
        }

        if ($this->mode !== 0) {
            $iterator = new FileTypeFilterIterator($iterator, $this->mode);
        }

        if ($this->dates) {
            $iterator = new DateRangeFilterIterator($this->filesystem, $iterator, $this->dates);
        }

        if ($this->sizes) {
            $iterator = new SizeRangeFilterIterator($this->filesystem, $iterator, $this->sizes);
        }

        if ($this->sort || $this->reverseSorting) {
            $iteratorAggregate = new SortableIterator(
                $this->filesystem,
                $iterator,
                $this->sort,
                $this->reverseSorting
            );
            $iterator = $iteratorAggregate->getIterator();
        }

        return $iterator;
    }

    #[\ReturnTypeWillChange]
    public function getIterator(): \Iterator
    {
        if ([] === $this->dirs && [] === $this->iterators) {
            throw new LogicException('You must call one of in() or append() methods before iterating over a Finder.');
        }

        if (1 === count($this->dirs) && [] === $this->iterators) {
            return $this->searchInDirectory($this->dirs[0]);
        }

        $iterator = new AppendIterator();
        foreach ($this->dirs as $dir) {
            $iterator->append($this->searchInDirectory($dir));
        }

        foreach ($this->iterators as $it) {
            $iterator->append($it);
        }

        return $iterator;
    }

    public function count(): int
    {
        return iterator_count($this->getIterator());
    }
}