feature #30744 [Finder] Throw a dedicated exception for non-existing directory (xelan)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[Finder] Throw a dedicated exception for non-existing directory

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | yes [1]
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no [2]
| Tests pass?   | yes
| Fixed tickets | #30723
| License       | MIT
| Doc PR        | N/A [3]

Makes `Finder::in()` throw a `DirectoryNotFoundException` instead of an `InvalidArgumentException` if one of the directories is not found.
This behavior is more consistent with the `AccessDeniedException` for files which are unreadable due to insufficient permissions.
To keep backward compatibility, the new exception class inherits from `InvalidArgumentException`.

[1] A valid, but non-existent directory name is IMHO not an invalid argument
[2] However, it may be semantically better to extend from `RuntimeException`,  This would require a deprecation.
[3] Possible exceptions are currently not explained at https://symfony.com/doc/current/components/finder.html

Commits
-------

48d5f94cda Throw a dedicated exception for non-existing directory

src/Symfony/Component/Finder/Exception/DirectoryNotFoundException.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Finder\Exception;
+
+/**
+ * @author Andreas Erhard <andreas.erhard@i-med.ac.at>
+ */
+class DirectoryNotFoundException extends \InvalidArgumentException
+{
+}

src/Symfony/Component/Finder/Finder.php

@@ -13,6 +13,7 @@ namespace Symfony\Component\Finder;
 
 use Symfony\Component\Finder\Comparator\DateComparator;
 use Symfony\Component\Finder\Comparator\NumberComparator;
+use Symfony\Component\Finder\Exception\DirectoryNotFoundException;
 use Symfony\Component\Finder\Iterator\CustomFilterIterator;
 use Symfony\Component\Finder\Iterator\DateRangeFilterIterator;
 use Symfony\Component\Finder\Iterator\DepthRangeFilterIterator;
@@ -585,7 +586,7 @@ class Finder implements \IteratorAggregate, \Countable
      *
      * @return $this
      *
-     * @throws \InvalidArgumentException if one of the directories does not exist
+     * @throws DirectoryNotFoundException if one of the directories does not exist
      */
     public function in($dirs)
     {
@@ -597,7 +598,7 @@ class Finder implements \IteratorAggregate, \Countable
             } elseif ($glob = glob($dir, (\defined('GLOB_BRACE') ? GLOB_BRACE : 0) | GLOB_ONLYDIR)) {
                 $resolvedDirs = array_merge($resolvedDirs, array_map([$this, 'normalizeDir'], $glob));
             } else {
-                throw new \InvalidArgumentException(sprintf('The "%s" directory does not exist.', $dir));
+                throw new DirectoryNotFoundException(sprintf('The "%s" directory does not exist.', $dir));
             }
         }
 

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

@@ -888,7 +888,7 @@ class FinderTest extends Iterator\RealIteratorTestCase
     }
 
     /**
-     * @expectedException \InvalidArgumentException
+     * @expectedException \Symfony\Component\Finder\Exception\DirectoryNotFoundException
      */
     public function testInWithNonExistentDirectory()
     {
@@ -896,6 +896,15 @@ class FinderTest extends Iterator\RealIteratorTestCase
         $finder->in('foobar');
     }
 
+    /**
+     * @expectedException \InvalidArgumentException
+     */
+    public function testInWithNonExistentDirectoryLegacyException()
+    {
+        $finder = new Finder();
+        $finder->in('foobar');
+    }
+
     public function testInWithGlob()
     {
         $finder = $this->buildFinder();