Merge pull request #6564 from cakephp/redirect-docs

Add RedirectException docs

Author: dereuromark

en/appendices/4-1-migration-guide.rst

@@ -42,6 +42,12 @@ ORM
 * ``QueryExpression::or_()`` and ``QueryExpression::and_()`` have been
   deprecated. Use ``or()`` and ``and()`` instead.
 
+Routing
+-------
+
+* ``Cake\Routing\Exception\RedirectException`` is deprecated. Use
+  ``Cake\Http\Exception\RedirectException`` instead.
+
 View
 ----
 
@@ -70,7 +76,7 @@ ORM
 
 * BelongsToMany associations now respect the bindingKey set in the junction table's BelongsTo association.
   Previously, the target table's primary key was always used instead.
-  
+
 TestSuite
 ---------
 
@@ -113,6 +119,17 @@ Error
   respectively.
 * The ``Debugger.editor`` configure value has been added. This value is used as
   the preferred editor link format.
+* ``ErrorHandlerMiddleware`` now handles
+  ``Http\Exception\RedirectException`` and converts those exceptions into HTTP
+  redirect responses.
+
+Http
+----
+
+* ``Cake\Http\Exception\RedirectException`` was added. This exception replaces
+  the ``RedirectException`` in the Routing package and can be raised anywhere in
+  your application to signal to the error handling middleware to create
+  a redirect response.
 
 Log
 ---

en/controllers/components.rst

@@ -321,7 +321,26 @@ To redirect from within a component callback method you can use the following::
 
 By stopping the event you let CakePHP know that you don't want any other
 component callbacks to run, and that the controller should not handle the action
-any further.
+any further. As of 4.1.0 you can raise a ``RedirectException`` to signal
+a redirect::
+
+    use Cake\Http\Exception\RedirectException;
+    use Cake\Routing\Router;
+
+    public function beforeFilter(EventInterface $event)
+    {
+        throw new RedirectException(Router::url('/'))
+    }
+
+Raising an exception will halt all other event listeners and create a new
+response that doesn't retain or inherit any of the current response's headers.
+When raising a ``RedirectException`` you can include additional headers::
+
+    throw new RedirectException(Router::url('/'), 302, [
+        'Header-Key' => 'value',
+    ]);
+
+.. versionadded:: 4.1.0
 
 .. meta::
     :title lang=en: Components