feature #15805 [Finder] Deprecate adapters and related classes (nicol…

…as-grekas)

This PR was merged into the 2.8 branch.

Discussion
----------

[Finder] Deprecate adapters and related classes

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Commits
-------

c08cf4b [Finder] Deprecate adapters and related classes

src/Symfony/Component/Finder/Adapter/AbstractAdapter.php

@@ -11,10 +11,14 @@
 
 namespace Symfony\Component\Finder\Adapter;
 
+@trigger_error('The '.__NAMESPACE__.'\AbstractAdapter class is deprecated since version 2.8 and will be removed in 3.0. Use directly the Finder class instead.', E_USER_DEPRECATED);
+
 /**
  * Interface for finder engine implementations.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0. Use Finder instead.
  */
 abstract class AbstractAdapter implements AdapterInterface
 {

src/Symfony/Component/Finder/Adapter/AbstractFindAdapter.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Finder\Adapter;
 
+@trigger_error('The '.__NAMESPACE__.'\AbstractFindAdapter class is deprecated since version 2.8 and will be removed in 3.0. Use directly the Finder class instead.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\Exception\AccessDeniedException;
 use Symfony\Component\Finder\Iterator;
 use Symfony\Component\Finder\Shell\Shell;
@@ -23,6 +25,8 @@
  * Shell engine implementation using GNU find command.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0. Use Finder instead.
  */
 abstract class AbstractFindAdapter extends AbstractAdapter
 {

src/Symfony/Component/Finder/Adapter/AdapterInterface.php

@@ -13,6 +13,8 @@
 
 /**
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0.
  */
 interface AdapterInterface
 {

src/Symfony/Component/Finder/Adapter/BsdFindAdapter.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Finder\Adapter;
 
+@trigger_error('The '.__NAMESPACE__.'\BsdFindAdapter class is deprecated since version 2.8 and will be removed in 3.0. Use directly the Finder class instead.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\Shell\Shell;
 use Symfony\Component\Finder\Shell\Command;
 use Symfony\Component\Finder\Iterator\SortableIterator;
@@ -20,6 +22,8 @@
  * Shell engine implementation using BSD find command.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0. Use Finder instead.
  */
 class BsdFindAdapter extends AbstractFindAdapter
 {

src/Symfony/Component/Finder/Adapter/GnuFindAdapter.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Finder\Adapter;
 
+@trigger_error('The '.__NAMESPACE__.'\GnuFindAdapter class is deprecated since version 2.8 and will be removed in 3.0. Use directly the Finder class instead.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\Shell\Shell;
 use Symfony\Component\Finder\Shell\Command;
 use Symfony\Component\Finder\Iterator\SortableIterator;
@@ -20,6 +22,8 @@
  * Shell engine implementation using GNU find command.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0. Use Finder instead.
  */
 class GnuFindAdapter extends AbstractFindAdapter
 {

src/Symfony/Component/Finder/Adapter/PhpAdapter.php

@@ -11,12 +11,16 @@
 
 namespace Symfony\Component\Finder\Adapter;
 
+@trigger_error('The '.__NAMESPACE__.'\PhpAdapter class is deprecated since version 2.8 and will be removed in 3.0. Use directly the Finder class instead.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\Iterator;
 
 /**
  * PHP finder engine implementation.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0. Use Finder instead.
  */
 class PhpAdapter extends AbstractAdapter
 {

src/Symfony/Component/Finder/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+2.8.0
+-----
+
+ * deprecated adapters and related classes
+
 2.5.0
 -----
  * added support for GLOB_BRACE in the paths passed to Finder::in()

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

@@ -11,12 +11,16 @@
 
 namespace Symfony\Component\Finder\Exception;
 
+@trigger_error('The '.__NAMESPACE__.'\AdapterFailureException class is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\Adapter\AdapterInterface;
 
 /**
  * Base exception for all adapter failures.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0.
  */
 class AdapterFailureException extends \RuntimeException implements ExceptionInterface
 {

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

@@ -11,8 +11,12 @@
 
 namespace Symfony\Component\Finder\Exception;
 
+@trigger_error('The '.__NAMESPACE__.'\OperationNotPermitedException class is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
 /**
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0.
  */
 class OperationNotPermitedException extends AdapterFailureException
 {

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

@@ -11,11 +11,15 @@
 
 namespace Symfony\Component\Finder\Exception;
 
+@trigger_error('The '.__NAMESPACE__.'\ShellCommandFailureException class is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\Adapter\AdapterInterface;
 use Symfony\Component\Finder\Shell\Command;
 
 /**
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0.
  */
 class ShellCommandFailureException extends AdapterFailureException
 {

src/Symfony/Component/Finder/Finder.php

@@ -62,7 +62,7 @@ class Finder implements \IteratorAggregate, \Countable
     private $iterators = array();
     private $contains = array();
     private $notContains = array();
-    private $adapters = array();
+    private $adapters = null;
     private $paths = array();
     private $notPaths = array();
     private $ignoreUnreadableDirs = false;
@@ -75,13 +75,6 @@ class Finder implements \IteratorAggregate, \Countable
     public function __construct()
     {
         $this->ignore = static::IGNORE_VCS_FILES | static::IGNORE_DOT_FILES;
-
-        $this
-            ->addAdapter(new GnuFindAdapter())
-            ->addAdapter(new BsdFindAdapter())
-            ->addAdapter(new PhpAdapter(), -50)
-            ->setAdapter('php')
-        ;
     }
 
     /**
@@ -103,9 +96,15 @@ public static function create()
      * @param int              $priority Highest is selected first
      *
      * @return Finder The current Finder instance
+     *
+     * @deprecated since 2.8, to be removed in 3.0.
      */
     public function addAdapter(AdapterInterface $adapter, $priority = 0)
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
+        $this->initDefaultAdapters();
+
         $this->adapters[$adapter->getName()] = array(
             'adapter' => $adapter,
             'priority' => $priority,
@@ -119,9 +118,15 @@ public function addAdapter(AdapterInterface $adapter, $priority = 0)
      * Sets the selected adapter to the best one according to the current platform the code is run on.
      *
      * @return Finder The current Finder instance
+     *
+     * @deprecated since 2.8, to be removed in 3.0.
      */
     public function useBestAdapter()
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
+        $this->initDefaultAdapters();
+
         $this->resetAdapterSelection();
 
         return $this->sortAdapters();
@@ -135,9 +140,15 @@ public function useBestAdapter()
      * @throws \InvalidArgumentException
      *
      * @return Finder The current Finder instance
+     *
+     * @deprecated since 2.8, to be removed in 3.0.
      */
     public function setAdapter($name)
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
+        $this->initDefaultAdapters();
+
         if (!isset($this->adapters[$name])) {
             throw new \InvalidArgumentException(sprintf('Adapter "%s" does not exist.', $name));
         }
@@ -152,9 +163,13 @@ public function setAdapter($name)
      * Removes all adapters registered in the finder.
      *
      * @return Finder The current Finder instance
+     *
+     * @deprecated since 2.8, to be removed in 3.0.
      */
     public function removeAdapters()
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
         $this->adapters = array();
 
         return $this;
@@ -164,9 +179,15 @@ public function removeAdapters()
      * Returns registered adapters ordered by priority without extra information.
      *
      * @return AdapterInterface[]
+     *
+     * @deprecated since 2.8, to be removed in 3.0.
      */
     public function getAdapters()
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
+        $this->initDefaultAdapters();
+
         return array_values(array_map(function (array $adapter) {
             return $adapter['adapter'];
         }, $this->adapters));
@@ -774,8 +795,6 @@ private function sortAdapters()
      * @param $dir
      *
      * @return \Iterator
-     *
-     * @throws \RuntimeException When none of the adapters are supported
      */
     private function searchInDirectory($dir)
     {
@@ -787,18 +806,93 @@ private function searchInDirectory($dir)
             $this->notPaths[] = '#(^|/)\..+(/|$)#';
         }
 
-        foreach ($this->adapters as $adapter) {
-            if ($adapter['adapter']->isSupported()) {
-                try {
-                    return $this
-                        ->buildAdapter($adapter['adapter'])
-                        ->searchInDirectory($dir);
-                } catch (ExceptionInterface $e) {
+        if ($this->adapters) {
+            foreach ($this->adapters as $adapter) {
+                if ($adapter['adapter']->isSupported()) {
+                    try {
+                        return $this
+                            ->buildAdapter($adapter['adapter'])
+                            ->searchInDirectory($dir);
+                    } catch (ExceptionInterface $e) {
+                    }
                 }
             }
         }
 
-        throw new \RuntimeException('No supported adapter found.');
+        $minDepth = 0;
+        $maxDepth = PHP_INT_MAX;
+
+        foreach ($this->depths as $comparator) {
+            switch ($comparator->getOperator()) {
+                case '>':
+                    $minDepth = $comparator->getTarget() + 1;
+                    break;
+                case '>=':
+                    $minDepth = $comparator->getTarget();
+                    break;
+                case '<':
+                    $maxDepth = $comparator->getTarget() - 1;
+                    break;
+                case '<=':
+                    $maxDepth = $comparator->getTarget();
+                    break;
+                default:
+                    $minDepth = $maxDepth = $comparator->getTarget();
+            }
+        }
+
+        $flags = \RecursiveDirectoryIterator::SKIP_DOTS;
+
+        if ($this->followLinks) {
+            $flags |= \RecursiveDirectoryIterator::FOLLOW_SYMLINKS;
+        }
+
+        $iterator = new Iterator\RecursiveDirectoryIterator($dir, $flags, $this->ignoreUnreadableDirs);
+
+        if ($this->exclude) {
+            $iterator = new Iterator\ExcludeDirectoryFilterIterator($iterator, $this->exclude);
+        }
+
+        $iterator = new \RecursiveIteratorIterator($iterator, \RecursiveIteratorIterator::SELF_FIRST);
+
+        if ($minDepth > 0 || $maxDepth < PHP_INT_MAX) {
+            $iterator = new Iterator\DepthRangeFilterIterator($iterator, $minDepth, $maxDepth);
+        }
+
+        if ($this->mode) {
+            $iterator = new Iterator\FileTypeFilterIterator($iterator, $this->mode);
+        }
+
+        if ($this->names || $this->notNames) {
+            $iterator = new Iterator\FilenameFilterIterator($iterator, $this->names, $this->notNames);
+        }
+
+        if ($this->contains || $this->notContains) {
+            $iterator = new Iterator\FilecontentFilterIterator($iterator, $this->contains, $this->notContains);
+        }
+
+        if ($this->sizes) {
+            $iterator = new Iterator\SizeRangeFilterIterator($iterator, $this->sizes);
+        }
+
+        if ($this->dates) {
+            $iterator = new Iterator\DateRangeFilterIterator($iterator, $this->dates);
+        }
+
+        if ($this->filters) {
+            $iterator = new Iterator\CustomFilterIterator($iterator, $this->filters);
+        }
+
+        if ($this->paths || $this->notPaths) {
+            $iterator = new Iterator\PathFilterIterator($iterator, $this->paths, $this->notPaths);
+        }
+
+        if ($this->sort) {
+            $iteratorAggregate = new Iterator\SortableIterator($iterator, $this->sort);
+            $iterator = $iteratorAggregate->getIterator();
+        }
+
+        return $iterator;
     }
 
     /**
@@ -837,4 +931,17 @@ private function resetAdapterSelection()
             return $properties;
         }, $this->adapters);
     }
+
+    private function initDefaultAdapters()
+    {
+        if (null === $this->adapters) {
+            $this->adapters = array();
+            $this
+                ->addAdapter(new GnuFindAdapter())
+                ->addAdapter(new BsdFindAdapter())
+                ->addAdapter(new PhpAdapter(), -50)
+                ->setAdapter('php')
+            ;
+        }
+    }
 }

src/Symfony/Component/Finder/Iterator/FilePathsIterator.php

@@ -11,12 +11,16 @@
 
 namespace Symfony\Component\Finder\Iterator;
 
+@trigger_error('The '.__NAMESPACE__.'\FilePathsIterator class is deprecated since version 2.8 and will be removed in 3.0.', E_USER_DEPRECATED);
+
 use Symfony\Component\Finder\SplFileInfo;
 
 /**
  * Iterate over shell command result.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since 2.8, to be removed in 3.0.
  */
 class FilePathsIterator extends \ArrayIterator
 {