Fix natural case insensitive sort for files

File need to be ordered by location on the file system.

Author: jaapio

packages/guides/src/Files.php

@@ -22,6 +22,9 @@
 use function in_array;
 use function sort;
 
+use const SORT_FLAG_CASE;
+use const SORT_NATURAL;
+
 /** @implements IteratorAggregate<string> */
 final class Files implements IteratorAggregate, Countable
 {
@@ -35,7 +38,7 @@ public function add(string $filename): void
         }
 
         $this->files[] = $filename;
-        sort($this->files);
+        sort($this->files, SORT_NATURAL | SORT_FLAG_CASE);
     }
 
     /** @return Iterator<string> */

packages/guides/tests/unit/FilesTest.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides;
+
+use PHPUnit\Framework\TestCase;
+
+use function iterator_to_array;
+
+class FilesTest extends TestCase
+{
+    public function testFilesAreSorted(): void
+    {
+        $files = new Files();
+        $files->add('page');
+        $files->add('Subpage');
+        $files->add('index');
+
+        $result = iterator_to_array($files->getIterator());
+
+        self::assertSame(
+            [
+                'index',
+                'page',
+                'Subpage',
+            ],
+            $result,
+        );
+    }
+}