From c4a33cb37b2c6d8d04a1843d029cb52bea5609fc Mon Sep 17 00:00:00 2001
From: Fran Moreno <franmomu@gmail.com>
Date: Fri, 11 Dec 2020 19:57:25 +0100
Subject: [PATCH] Add RouteCollectionInterface

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                         |  38 ++++++++
 src/Route/RouteCollection.php          |   2 +-
 src/Route/RouteCollectionInterface.php | 130 +++++++++++++++++++++++++
 3 files changed, 169 insertions(+), 1 deletion(-)
 create mode 100644 src/Route/RouteCollectionInterface.php

diff --git a/UPGRADE-3.x.md b/UPGRADE-3.x.md
index 04fa786c6d..a29099fad8 100644
--- a/UPGRADE-3.x.md
+++ b/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.
+
 UPGRADE FROM 3.82 to 3.83
 =========================
 
diff --git a/src/Route/RouteCollection.php b/src/Route/RouteCollection.php
index a0456b8dcf..bca5139280 100644
--- a/src/Route/RouteCollection.php
+++ b/src/Route/RouteCollection.php
@@ -20,7 +20,7 @@
  *
  * @author Thomas Rabaix <thomas.rabaix@sonata-project.org>
  */
-class RouteCollection
+class RouteCollection implements RouteCollectionInterface
 {
     /**
      * @var array<string, Route|callable():Route>
diff --git a/src/Route/RouteCollectionInterface.php b/src/Route/RouteCollectionInterface.php
new file mode 100644
index 0000000000..4986b71be3
--- /dev/null
+++ b/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 <thomas.rabaix@sonata-project.org>
+ *
+ * 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 <jordism91@gmail.com>
+ */
+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();
+}