feature #27024 [Finder] added "use natural sort" option (vyshkant)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[Finder] added "use natural sort" option

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

Added `$useNaturalSort` optional argument to `Finder::sortByName()` method. If it is specified and equals to `true`, ["natural sort order" algorithm](https://en.wikipedia.org/wiki/Natural_sort_order) will be applied, which means that `strnatcmp` function will be used instead of `strcmp` (see #26930 for details).

Commits
-------

e697c7d272 [Finder] added "use natural sort" option

Author: fabpot

CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+4.2.0
+-----
+
+ * added $useNaturalSort option to Finder::sortByName() method
+
 4.0.0
 -----
 

Finder.php

@@ -397,13 +397,17 @@ public function sort(\Closure $closure)
      *
      * This can be slow as all the matching files and directories must be retrieved for comparison.
      *
+     * @param bool $useNaturalSort Whether to use natural sort or not, disabled by default
+     *
      * @return $this
      *
      * @see SortableIterator
      */
-    public function sortByName()
+    public function sortByName(/* bool $useNaturalSort = false */)
     {
-        $this->sort = Iterator\SortableIterator::SORT_BY_NAME;
+        $useNaturalSort = 0 < func_num_args() && func_get_arg(0);
+
+        $this->sort = $useNaturalSort ? Iterator\SortableIterator::SORT_BY_NAME_NATURAL : Iterator\SortableIterator::SORT_BY_NAME;
 
         return $this;
     }

Iterator/SortableIterator.php

@@ -23,6 +23,7 @@ class SortableIterator implements \IteratorAggregate
     const SORT_BY_ACCESSED_TIME = 3;
     const SORT_BY_CHANGED_TIME = 4;
     const SORT_BY_MODIFIED_TIME = 5;
+    const SORT_BY_NAME_NATURAL = 6;
 
     private $iterator;
     private $sort;
@@ -41,6 +42,10 @@ public function __construct(\Traversable $iterator, $sort)
             $this->sort = function ($a, $b) {
                 return strcmp($a->getRealpath() ?: $a->getPathname(), $b->getRealpath() ?: $b->getPathname());
             };
+        } elseif (self::SORT_BY_NAME_NATURAL === $sort) {
+            $this->sort = function ($a, $b) {
+                return strnatcmp($a->getRealPath() ?: $a->getPathname(), $b->getRealPath() ?: $b->getPathname());
+            };
         } elseif (self::SORT_BY_TYPE === $sort) {
             $this->sort = function ($a, $b) {
                 if ($a->isDir() && $b->isFile()) {