Skip to content

[Finder] Fix SplFileInfo PHPDoc #45725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 18, 2022
Merged

[Finder] Fix SplFileInfo PHPDoc #45725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions src/Symfony/Component/Finder/Iterator/ExcludeDirectoryFilterIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,24 +11,27 @@

namespace Symfony\Component\Finder\Iterator;

use Symfony\Component\Finder\SplFileInfo;

/**
* ExcludeDirectoryFilterIterator filters out directories.
*
* @author Fabien Potencier <fabien@symfony.com>
*
* @extends \FilterIterator<string, \SplFileInfo>
* @implements \RecursiveIterator<string, \SplFileInfo>
* @extends \FilterIterator<string, SplFileInfo>
* @implements \RecursiveIterator<string, SplFileInfo>
*/
class ExcludeDirectoryFilterIterator extends \FilterIterator implements \RecursiveIterator
{
/** @var \Iterator<string, SplFileInfo> */
private \Iterator $iterator;
private bool $isRecursive;
private array $excludedDirs = [];
private ?string $excludedPattern = null;

/**
* @param \Iterator $iterator The Iterator to filter
* @param string[] $directories An array of directories to exclude
* @param \Iterator<string, SplFileInfo> $iterator The Iterator to filter
* @param string[] $directories An array of directories to exclude
*/
public function __construct(\Iterator $iterator, array $directories)
{
Expand Down
4 changes: 2 additions & 2 deletions src/Symfony/Component/Finder/Iterator/FileTypeFilterIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ class FileTypeFilterIterator extends \FilterIterator
private int $mode;

/**
* @param \Iterator $iterator The Iterator to filter
* @param int $mode The mode (self::ONLY_FILES or self::ONLY_DIRECTORIES)
* @param \Iterator<string, \SplFileInfo> $iterator The Iterator to filter
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also require our SplFileInfo implementation here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well the question is what we want to achieve here. We have no real control over who is using these iterators besides the Finder implementation itself. Any changes we make here could be perceived as introducing new "bugs" by people who use the iterators in a legitimate/compatible way. Personally, I'm clearly aiming at bug fixes without such potentially controversial side-effects here.

More detailed explanation:

  • RecursiveDirectoryIterator::current returns Symfony SplFileInfo, so that's its Iterator value type.
  • RecursiveDirectoryIterator is the starting point base iterator in Finder::searchInDirectory, hence the whole Finder iterator chain iterates over Symfony SplFileInfo, too.

So from a strictly internal point of view, all of the iterators use the Symfony SplFileInfo.

To determine which type of SplFileInfo class each iterator can use we need to look at the current() method and its calls/usages. Basically there are three cases here:

  1. If the current() method is implemented explicitly and returns the Symfony SplFileInfo, that's the Iterator value type. Example: RecursiveDirectoryIterator
  2. Usages that access one of the relative path methods require a Symfony SplFileInfo so the corresponding iterator needs to provide that. Example: PathFilterIterator
  3. Usages that only access methods of \SplFileInfo can work with any iterator that provides \SplFileInfo or any subclass of it. Example: FileTypeFilterIterator

* @param int $mode The mode (self::ONLY_FILES or self::ONLY_DIRECTORIES)
*/
public function __construct(\Iterator $iterator, int $mode)
{
Expand Down
4 changes: 3 additions & 1 deletion src/Symfony/Component/Finder/Iterator/FilecontentFilterIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,15 @@

namespace Symfony\Component\Finder\Iterator;

use Symfony\Component\Finder\SplFileInfo;

/**
* FilecontentFilterIterator filters files by their contents using patterns (regexps or strings).
*
* @author Fabien Potencier <fabien@symfony.com>
* @author Włodzimierz Gajda <gajdaw@gajdaw.pl>
*
* @extends MultiplePcreFilterIterator<string, \SplFileInfo>
* @extends MultiplePcreFilterIterator<string, SplFileInfo>
*/
class FilecontentFilterIterator extends MultiplePcreFilterIterator
{
Expand Down
6 changes: 3 additions & 3 deletions src/Symfony/Component/Finder/Iterator/MultiplePcreFilterIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ abstract class MultiplePcreFilterIterator extends \FilterIterator
protected $noMatchRegexps = [];

/**
* @param \Iterator $iterator The Iterator to filter
* @param string[] $matchPatterns An array of patterns that need to match
* @param string[] $noMatchPatterns An array of patterns that need to not match
* @param \Iterator<TKey, TValue> $iterator The Iterator to filter
* @param string[] $matchPatterns An array of patterns that need to match
* @param string[] $noMatchPatterns An array of patterns that need to not match
*/
public function __construct(\Iterator $iterator, array $matchPatterns, array $noMatchPatterns)
{
Expand Down
4 changes: 3 additions & 1 deletion src/Symfony/Component/Finder/Iterator/PathFilterIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,15 @@

namespace Symfony\Component\Finder\Iterator;

use Symfony\Component\Finder\SplFileInfo;

/**
* PathFilterIterator filters files by path patterns (e.g. some/special/dir).
*
* @author Fabien Potencier <fabien@symfony.com>
* @author Włodzimierz Gajda <gajdaw@gajdaw.pl>
*
* @extends MultiplePcreFilterIterator<string, \SplFileInfo>
* @extends MultiplePcreFilterIterator<string, SplFileInfo>
*/
class PathFilterIterator extends MultiplePcreFilterIterator
{
Expand Down
1 change: 1 addition & 0 deletions src/Symfony/Component/Finder/Iterator/RecursiveDirectoryIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
* Extends the \RecursiveDirectoryIterator to support relative paths.
*
* @author Victor Berchet <victor@suumit.com>
* @extends \RecursiveDirectoryIterator<string, SplFileInfo>
*/
class RecursiveDirectoryIterator extends \RecursiveDirectoryIterator
{
Expand Down
1 change: 1 addition & 0 deletions src/Symfony/Component/Finder/Iterator/SortableIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ class SortableIterator implements \IteratorAggregate
public const SORT_BY_MODIFIED_TIME = 5;
public const SORT_BY_NAME_NATURAL = 6;

/** @var \Traversable<string, \SplFileInfo> $iterator */
private \Traversable $iterator;
private \Closure|int $sort;

Expand Down
6 changes: 6 additions & 0 deletions src/Symfony/Component/Finder/Iterator/VcsIgnoredFilterIterator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@

use Symfony\Component\Finder\Gitignore;

/**
* @extends \FilterIterator<string, \SplFileInfo>
*/
final class VcsIgnoredFilterIterator extends \FilterIterator
{
/**
Expand All @@ -30,6 +33,9 @@ final class VcsIgnoredFilterIterator extends \FilterIterator
*/
private $ignoredPathsCache = [];

/**
* @param \Iterator<string, \SplFileInfo> $iterator
*/
public function __construct(\Iterator $iterator, string $baseDir)
{
$this->baseDir = $this->normalizePath($baseDir);
Expand Down