…r better fluent experience and code readability (jfredon)

This PR was squashed before being merged into the 4.2-dev branch (closes #27891).

Discussion
----------

[Finder] Allow arrays as parameters of some methods for better fluent experience and code readability

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | none
| License       | MIT
| Doc PR        | symfony/symfony-docs#10038

Makes the Finder library a little more convenient to use by allowing the use of arrays as parameters of methods that can be called multiple times.

This way of doing things was already present for the `Finder::in()` and `Finder::exclude()` methods, it has been extended to other methods that can be called several times to cumulate their effects.
This allows a better use of fluent methods by avoiding breaking the chaining to iterate on array variables (a little more complexity in the Finder library for less complexity in applications that uses it).

```php
// we could use
$finder = Finder::create()->in($fileRepository)->name($fileList);

// instead of
$finder = Finder::create()->in($fileRepository);
foreach ($fileList as $file) {
    $finder->name($file);
}
```

In `.php_cs` files, this would make the code more readable by separating the configuration of the execution code:

```php
<?php
const RULES = [
    '@symfony' => true,
    '@symfony:risky' => true,
];
const EXCLUDED_DIRS = [
    // directories containing files with content that is autogenerated by `var_export`, which breaks CS in output code
    'Symfony/Component/Cache/Tests/Marshaller/Fixtures',
    'Symfony/Component/DependencyInjection/Tests/Fixtures',
    // ...
];
const EXCLUDED_FILES = [
    // file content autogenerated by `var_export`
    'Symfony/Component/Translation/Tests/fixtures/resources.php',
    // test template
    'Symfony/Bundle/FrameworkBundle/Tests/Templating/Helper/Resources/Custom/_name_entry_label.html.php',
    // ...
];

return PhpCsFixer\Config::create()
    ->setRules(RULES)
    ->setRiskyAllowed(true)
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__.'/src')
            ->append(array(__FILE__))
            ->exclude(EXCLUDED_DIRS)
            ->notPath(EXCLUDED_FILES)
    )
;
```

TODO
- [x] complete the tests to validate the new syntax on all modified methods
- [x] submit changes to the Finder documentation

Commits
-------

ad97cd7 [Finder] Allow arrays as parameters of some methods for better fluent experience and code readability

…arameter (jfredon)

This PR was merged into the master branch.

Discussion
----------

[Finder] Add documentation and code on array as method parameter

Documents symfony/symfony#27891

Commits
-------

361dde5 [Finder] Add documentation and code on array as method parameter

…r better fluent experience and code readability (jfredon)

This PR was squashed before being merged into the 4.2-dev branch (closes #27891).

Discussion
----------

[Finder] Allow arrays as parameters of some methods for better fluent experience and code readability

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | none
| License       | MIT
| Doc PR        | symfony/symfony-docs#10038

Makes the Finder library a little more convenient to use by allowing the use of arrays as parameters of methods that can be called multiple times.

This way of doing things was already present for the `Finder::in()` and `Finder::exclude()` methods, it has been extended to other methods that can be called several times to cumulate their effects.
This allows a better use of fluent methods by avoiding breaking the chaining to iterate on array variables (a little more complexity in the Finder library for less complexity in applications that uses it).

```php
// we could use
$finder = Finder::create()->in($fileRepository)->name($fileList);

// instead of
$finder = Finder::create()->in($fileRepository);
foreach ($fileList as $file) {
    $finder->name($file);
}
```

In `.php_cs` files, this would make the code more readable by separating the configuration of the execution code:

```php
<?php
const RULES = [
    '@symfony' => true,
    '@symfony:risky' => true,
];
const EXCLUDED_DIRS = [
    // directories containing files with content that is autogenerated by `var_export`, which breaks CS in output code
    'Symfony/Component/Cache/Tests/Marshaller/Fixtures',
    'Symfony/Component/DependencyInjection/Tests/Fixtures',
    // ...
];
const EXCLUDED_FILES = [
    // file content autogenerated by `var_export`
    'Symfony/Component/Translation/Tests/fixtures/resources.php',
    // test template
    'Symfony/Bundle/FrameworkBundle/Tests/Templating/Helper/Resources/Custom/_name_entry_label.html.php',
    // ...
];

return PhpCsFixer\Config::create()
    ->setRules(RULES)
    ->setRiskyAllowed(true)
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__.'/src')
            ->append(array(__FILE__))
            ->exclude(EXCLUDED_DIRS)
            ->notPath(EXCLUDED_FILES)
    )
;
```

TODO
- [x] complete the tests to validate the new syntax on all modified methods
- [x] submit changes to the Finder documentation

Commits
-------

6006300 [Finder] Allow arrays as parameters of some methods for better fluent experience and code readability