From 2a434091878143ef30b26c8ead1b91f0dfc44817 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Wed, 1 Nov 2017 00:02:16 -0400
Subject: [PATCH] Add deprecation warnings to Routing features.

Make documented deprecations into runtime errors.
---
 src/Routing/RequestActionTrait.php |  4 ++++
 src/Routing/Route/Route.php        |  7 ++++++-
 src/Routing/RouteBuilder.php       |  8 ++++++++
 src/Routing/RouteCollection.php    |  4 ++++
 src/Routing/Router.php             | 16 ++++++++++++++++
 5 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/Routing/RequestActionTrait.php b/src/Routing/RequestActionTrait.php
index 99721cee11a..b9b89fea83d 100644
--- a/src/Routing/RequestActionTrait.php
+++ b/src/Routing/RequestActionTrait.php
@@ -101,6 +101,10 @@ trait RequestActionTrait
      */
     public function requestAction($url, array $extra = [])
     {
+        deprecationWarning(
+            'RequestActionTrait::requestAction() is deprecated. ' .
+            'You should refactor to use View Cells or Components instead.'
+        );
         if (empty($url)) {
             return false;
         }
diff --git a/src/Routing/Route/Route.php b/src/Routing/Route/Route.php
index 395605b3b9a..e8a20f76d6b 100644
--- a/src/Routing/Route/Route.php
+++ b/src/Routing/Route/Route.php
@@ -120,8 +120,8 @@ class Route
     public function __construct($template, $defaults = [], array $options = [])
     {
         $this->template = $template;
-        // @deprecated The `[method]` format should be removed in 4.0.0
         if (isset($defaults['[method]'])) {
+            deprecationWarning('The `[method]` option is deprecated. Use `_method` instead.');
             $defaults['_method'] = $defaults['[method]'];
             unset($defaults['[method]']);
         }
@@ -141,6 +141,10 @@ public function __construct($template, $defaults = [], array $options = [])
      */
     public function extensions($extensions = null)
     {
+        deprecationWarning(
+            'Route::extensions() is deprecated. ' .
+            'Use Route::setExtensions()/getExtensions() instead.'
+        );
         if ($extensions === null) {
             return $this->_extensions;
         }
@@ -736,6 +740,7 @@ protected function _matchMethod($url)
         }
         // @deprecated The `[method]` support should be removed in 4.0.0
         if (isset($url['[method]'])) {
+            deprecationWarning('The `[method]` key is deprecated. Use `_method` instead.');
             $url['_method'] = $url['[method]'];
         }
         if (empty($url['_method'])) {
diff --git a/src/Routing/RouteBuilder.php b/src/Routing/RouteBuilder.php
index 84795780629..50ca9161aa6 100644
--- a/src/Routing/RouteBuilder.php
+++ b/src/Routing/RouteBuilder.php
@@ -152,6 +152,10 @@ public function __construct(RouteCollection $collection, $path, array $params =
      */
     public function routeClass($routeClass = null)
     {
+        deprecationWarning(
+            'RouteBuilder::routeClass() is deprecated. ' .
+            'Use RouteBuilder::setRouteClass()/getRouteClass() instead.'
+        );
         if ($routeClass === null) {
             return $this->getRouteClass();
         }
@@ -193,6 +197,10 @@ public function getRouteClass()
      */
     public function extensions($extensions = null)
     {
+        deprecationWarning(
+            'RouteBuilder::extensions() is deprecated. ' .
+            'Use RouteBuilder::setExtensions()/getExtensions() instead.'
+        );
         if ($extensions === null) {
             return $this->getExtensions();
         }
diff --git a/src/Routing/RouteCollection.php b/src/Routing/RouteCollection.php
index 93c23f92444..31b58dac458 100644
--- a/src/Routing/RouteCollection.php
+++ b/src/Routing/RouteCollection.php
@@ -373,6 +373,10 @@ public function named()
      */
     public function extensions($extensions = null, $merge = true)
     {
+        deprecationWarning(
+            'RouteCollection::extensions() is deprecated. ' .
+            'Use RouteCollection::setExtensions()/getExtensions() instead.'
+        );
         if ($extensions !== null) {
             $this->setExtensions((array)$extensions, $merge);
         }
diff --git a/src/Routing/Router.php b/src/Routing/Router.php
index 0474586d933..a1bde55cf98 100644
--- a/src/Routing/Router.php
+++ b/src/Routing/Router.php
@@ -225,6 +225,10 @@ public static function connect($route, $defaults = [], $options = [])
      */
     public static function redirect($route, $url, $options = [])
     {
+        deprecationWarning(
+            'Router::redirect() is deprecated. ' .
+            'Use Router::scope() and RouteBuilder::redirect() instead.'
+        );
         if (is_string($url)) {
             $url = ['redirect' => $url];
         }
@@ -291,6 +295,10 @@ public static function redirect($route, $url, $options = [])
      */
     public static function mapResources($controller, $options = [])
     {
+        deprecationWarning(
+            'Router::mapResources() is deprecated. ' .
+            'Use Router::scope() and RouteBuilder::resources() instead.'
+        );
         foreach ((array)$controller as $name) {
             list($plugin, $name) = pluginSplit($name);
 
@@ -344,6 +352,10 @@ public static function mapResources($controller, $options = [])
      */
     public static function parse($url, $method = '')
     {
+        deprecationWarning(
+            'Router::parse() is deprecated. ' .
+            'Use Router::parseRequest() instead. This will require adopting the Http\Server library.'
+        );
         if (!static::$initialized) {
             static::_loadRoutes();
         }
@@ -872,6 +884,10 @@ public static function extensions($extensions = null, $merge = true)
      */
     public static function parseNamedParams(ServerRequest $request, array $options = [])
     {
+        deprecationWarning(
+            'Router::parseNamedParams() is deprecated. ' .
+            '2.x backwards compatible named parameter support will be removed in 4.0'
+        );
         $options += ['separator' => ':'];
         if (empty($request->params['pass'])) {
             $request->params['named'] = [];