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

jfredon · 2018-07-07T17:16:40Z

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).

// 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
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

complete the tests to validate the new syntax on all modified methods
submit changes to the Finder documentation

jfredon · 2018-07-09T11:14:49Z

@nicolas-grekas I'm not very familiar with the travis-ci build system yet.
Does it happen that the build fails because of other reasons than the code?

ro0NL · 2018-07-09T11:36:37Z

src/Symfony/Component/Finder/Finder.php

-        $this->depths[] = new Comparator\NumberComparator($level);
+        $this->depths = \array_merge(
+            $this->depths,
+            ComparatorFactory::createBatch(NumberComparator::class, (array) $levels)


IMHO you can inline the array_map call per case, no need for ComparatorFactory

or just wrap $this->depths[] = new Comparator\NumberComparator($level); in a foreach

You are right, the Factory did not please me either (it was on my PR TODO list).
I opt for the simplicity of the foreach loop.

ro0NL · 2018-07-09T11:36:54Z

AFAIK the classical KO src/Symfony/Bundle/SecurityBundle failure is unrelated yes :)

stof · 2018-07-10T13:47:35Z

src/Symfony/Component/Finder/Tests/FinderTest.php

    }

    public function testDate()
    {
        $finder = $this->buildFinder();
        $this->assertSame($finder, $finder->files()->date('until last month'));
        $this->assertIterator($this->toAbsolute(array('foo/bar.tmp', 'test.php')), $finder->in(self::$tmpDir)->getIterator());
+
+        $finder = $this->buildFinder();


should be a separate test instead of making 2 independent tests in the same PHPUnit test. This makes things much better, as it means they will both run all the time (if the first logic fails, it does not prevent the second from running if they are in separate tests) and it also makes the test more readable (as each test stays self-contained)

this is true for your other changes too.

And yes, I know that many Finder tests are still mixed in the same method. That's something we were doing a lot in the very early days of Symfony 2 development (i.e. in the early days of using PHPUnit in the Symfony community), and we haven't rewritten all existing tests to improve them.

Thanks a lot for your explanations.

I extracted my tests in their own methods but I might lack some inspiration to name them ... What do you think about it ?

When I run php-cs-fix on tests, it throws an error
1) src/Symfony/Component/Finder/Tests/FinderTest.php (native_constant_invocation)

I understand that this is a new way of writing native constant for more performance in Symfony. Is this something that I have to correct now?

I will be able to rewrite the old tests to update them by following the new practices in a dedicated PR.

@jfredon currently, the automated CI checks are running v2.11 of php-cs-fixer. v2.12 has some new rules (see #27852 for the WIP about using them)

fabpot

small change in one example

fabpot · 2018-07-13T12:37:20Z

src/Symfony/Component/Finder/Finder.php

@@ -131,18 +134,21 @@ public function depth($level)
     *   $finder->date('until 2 days ago');
     *   $finder->date('> now - 2 hours');
     *   $finder->date('>= 2005-10-15');
+     *   $finder->date(['>= 2005-10-15', '>= 2005-05-27']);


I suppose the first one should probably be <= for the range to make sense.

Yes, it’s fixed.
I checked that i did not make the mistake in the tests and documentation.

… experience and code readability

fabpot · 2018-07-16T12:57:15Z

Thank you @jfredon.

…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

carsonbot added Status: Needs Review Finder Feature labels Jul 7, 2018

jfredon force-pushed the finder-allow-array-as-method-parameters branch 10 times, most recently from 70dab9f to daec10f Compare July 8, 2018 18:49

nicolas-grekas added this to the next milestone Jul 8, 2018

jfredon force-pushed the finder-allow-array-as-method-parameters branch from daec10f to 93a35eb Compare July 8, 2018 19:38

ro0NL reviewed Jul 9, 2018

View reviewed changes

jfredon force-pushed the finder-allow-array-as-method-parameters branch 2 times, most recently from f88f9d8 to a2dbbd1 Compare July 9, 2018 13:03

ro0NL approved these changes Jul 9, 2018

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Jul 9, 2018

jfredon mentioned this pull request Jul 9, 2018

[Finder] Add documentation and code on array as method parameter symfony/symfony-docs#10038

Merged

jfredon force-pushed the finder-allow-array-as-method-parameters branch from a2dbbd1 to 72812ed Compare July 10, 2018 00:00

jfredon changed the title ~~[WIP] [Finder] Allow arrays as parameters of some methods for better fluent experience and code readability~~ [Finder] Allow arrays as parameters of some methods for better fluent experience and code readability Jul 10, 2018

azjezz approved these changes Jul 10, 2018

View reviewed changes

vudaltsov approved these changes Jul 10, 2018

View reviewed changes

stof reviewed Jul 10, 2018

View reviewed changes

jfredon force-pushed the finder-allow-array-as-method-parameters branch from 72812ed to 3dd230a Compare July 10, 2018 15:47

fabpot approved these changes Jul 13, 2018

View reviewed changes

jfredon force-pushed the finder-allow-array-as-method-parameters branch 3 times, most recently from fe41694 to 4dacad4 Compare July 13, 2018 20:51

fabpot approved these changes Jul 15, 2018

View reviewed changes

[Finder] Allow arrays as parameters of some methods for better fluent…

ad97cd7

… experience and code readability

fabpot force-pushed the finder-allow-array-as-method-parameters branch from 3296753 to ad97cd7 Compare July 16, 2018 12:56

fabpot merged commit ad97cd7 into symfony:master Jul 16, 2018

nicolas-grekas modified the milestones: next, 4.2 Nov 1, 2018

This was referenced Nov 3, 2018

Release v4.2.0-BETA1 #29072

Closed

Release v4.2.0-BETA1 #29073

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jfredon commented Jul 7, 2018 •

edited

Loading

jfredon commented Jul 9, 2018

ro0NL Jul 9, 2018 •

edited

Loading

jfredon Jul 9, 2018

ro0NL commented Jul 9, 2018

stof Jul 10, 2018

stof Jul 10, 2018

jfredon Jul 10, 2018 •

edited

Loading

stof Jul 10, 2018

fabpot left a comment

fabpot Jul 13, 2018

jfredon Jul 14, 2018

fabpot commented Jul 16, 2018

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

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

Conversation

jfredon commented Jul 7, 2018 • edited Loading

jfredon commented Jul 9, 2018

ro0NL Jul 9, 2018 • edited Loading

Choose a reason for hiding this comment

jfredon Jul 9, 2018

Choose a reason for hiding this comment

ro0NL commented Jul 9, 2018

stof Jul 10, 2018

Choose a reason for hiding this comment

stof Jul 10, 2018

Choose a reason for hiding this comment

jfredon Jul 10, 2018 • edited Loading

Choose a reason for hiding this comment

stof Jul 10, 2018

Choose a reason for hiding this comment

fabpot left a comment

Choose a reason for hiding this comment

fabpot Jul 13, 2018

Choose a reason for hiding this comment

jfredon Jul 14, 2018

Choose a reason for hiding this comment

fabpot commented Jul 16, 2018

jfredon commented Jul 7, 2018 •

edited

Loading

ro0NL Jul 9, 2018 •

edited

Loading

jfredon Jul 10, 2018 •

edited

Loading