Add RouteCollectionInterface (#6699)

This interface was added in 4.x branch, this commit imports it
removing type and return declarations to make it compatible with
RouteCollection which implements this interface.

In sonata 4 AbstractAdmin::configureRoutes() method receives a
RouteCollectionInterface, importing this interface in 3.x would
allow users to update their code and define this method as in 4
easing the upgrading process.

UPGRADE-3.x.md

@@ -1,6 +1,44 @@
 UPGRADE 3.x
 ===========
 
+UPGRADE FROM 3.xx to 3.xx
+=========================
+
+### `RouteCollection` now implements `RouteCollectionInterface`
+
+In 4.0, `AbstractAdmin::configureRoutes` and `AdminExtensionInterface::configureRoutes` will receive a
+`RouteCollectionInterface` instance instead of a `RouteCollection` instance, you can update your code before ugprading
+to 4.0.
+
+Before:
+```php
+use Sonata\AdminBundle\Admin\AbstractAdmin;
+use Sonata\AdminBundle\Route\RouteCollection;
+
+final class MyAdmin extends AbstractAdmin
+{
+    protected function configureRoutes(RouteCollection $collection): void
+    {
+        $collection->add('my_route');
+    }
+}
+```
+
+After:
+```php
+use Sonata\AdminBundle\Admin\AbstractAdmin;
+use Sonata\AdminBundle\Route\RouteCollectionInterface;
+
+final class MyAdmin extends AbstractAdmin
+{
+    protected function configureRoutes(RouteCollectionInterface $collection): void
+    {
+        $collection->add('my_route');
+    }
+}
+```
+This only will work with PHP >= 7.4, where fully support to contravariance was added.
+
 ### Sonata\AdminBundle\Admin\BaseFieldDescription
 
 Method `__construct()` has been updated to receive the field name as argument 6:

src/Route/RouteCollection.php

@@ -20,7 +20,7 @@
  *
  * @author Thomas Rabaix <[email protected]>
  */
-class RouteCollection
+class RouteCollection implements RouteCollectionInterface
 {
     /**
      * @var array<string, Route|callable():Route>

src/Route/RouteCollectionInterface.php

@@ -0,0 +1,130 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Sonata Project package.
+ *
+ * (c) Thomas Rabaix <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Sonata\AdminBundle\Route;
+
+use Symfony\Component\Routing\Route;
+
+/**
+ * @author Jordi Sala <[email protected]>
+ */
+interface RouteCollectionInterface
+{
+    /**
+     * @param string $name
+     * @param string $pattern   Pattern (will be automatically combined with @see $this->baseRoutePattern and $name
+     * @param string $host
+     * @param string $condition
+     *
+     * @return RouteCollection
+     */
+    public function add(
+        $name,
+        $pattern = null,
+        array $defaults = [],
+        array $requirements = [],
+        array $options = [],
+        $host = '',
+        array $schemes = [],
+        array $methods = [],
+        $condition = ''
+    );
+
+    /**
+     * @return string
+     */
+    public function getCode(string $name);
+
+    /**
+     * @return $this
+     */
+    public function addCollection(RouteCollection $collection);
+
+    /**
+     * @return Route[]
+     */
+    public function getElements();
+
+    /**
+     * @param string $name
+     *
+     * @return bool
+     */
+    public function has($name);
+
+    public function hasCached(string $name): bool;
+
+    /**
+     * @param string $name
+     *
+     * @throws \InvalidArgumentException
+     *
+     * @return Route
+     */
+    public function get($name);
+
+    /**
+     * @return $this
+     */
+    public function remove(string $name);
+
+    /**
+     * @throws \InvalidArgumentException
+     *
+     * @return $this
+     */
+    public function restore(string $name);
+
+    /**
+     * Remove all routes except routes in $routeList.
+     *
+     * @param string[]|string $routeList
+     *
+     * @return $this
+     */
+    public function clearExcept($routeList);
+
+    /**
+     * @return $this
+     */
+    public function clear();
+
+    /**
+     * Converts a word into the format required for a controller action. By instance,
+     * the argument "list_something" returns "listSomething" if the associated controller is not an action itself,
+     * otherwise, it will return "listSomethingAction".
+     *
+     * @return string
+     */
+    public function actionify(string $action);
+
+    /**
+     * @return string
+     */
+    public function getBaseCodeRoute();
+
+    /**
+     * @return string
+     */
+    public function getBaseControllerName();
+
+    /**
+     * @return string
+     */
+    public function getBaseRouteName();
+
+    /**
+     * @return string
+     */
+    public function getBaseRoutePattern();
+}