DOC: Documentation and upgrade notes for director middleware

docs/en/02_Developer_Guides/02_Controllers/05_Middlewares.md

@@ -0,0 +1,99 @@
+title: HTTP Middlewares
+summary: Create objects for modifying request and response objects across controllers.
+
+# HTTP Middlewares
+
+HTTP Middlewares allow you to put code that will run before or after. These might be used for
+authentication, logging, caching, request processing, and many other purposes. Note this interface
+replaces the SilverStripe 3 interface, [api:RequestFilter], which still works but is deprecated.
+
+To create a middleware class, implement `SilverStripe\Control\HTTPMiddleware` and define the
+`process($request, $delegate)` method. You can do anything you like in this method, but to continue
+normal execution, you should call `$response = $delegate($request)` at some point in this method.
+
+In addition, you should return an HTTPResponse object. In normal cases, this should be the
+$response object returned by `$delegate`, perhaps with some modification. However, sometimes you
+will deliberately return a different response, e.g. an error response or a redirection.
+
+**mysite/code/CustomMiddleware.php**
+
+	:::php
+	<?php
+
+    use SilverStripe\Control\HTTPMiddleware
+
+	class CustomMiddleware implements HTTPMiddleware {
+
+        public $Secret = 'SECRET';
+
+		public function process(HTTPRequest $request, callable $delegate) {
+
+            // You can break execution by not calling $delegate.
+            if ($request->getHeader('X-Special-Header') !== $this->Secret) {
+                return new HTTPResponse('You missed the special header', 400);
+            }
+    
+            // You can modify the request before 
+            // For example, this might force JSON responses
+            $request->addHeader('Accept', 'application/json');
+
+            // If you want normal behaviour to occur, make sure you call $delegate($request)
+            $response = $delegate($request);
+
+            // You can modify the response after it has been generated
+            $response->addHeader('X-Middleware-Applied', 'CustomMiddleware')
+
+            // Don't forget to the return the response!
+            return $response;
+		}
+	}
+
+Once you have created your middleware class, you must attach it to the Director config to make
+use of it.
+
+## Global middleware
+
+By adding the service or class name to the SilverStripe\Control\Director.middlewares array, a
+middleware will be executed on every request:
+
+**mysite/_config/app.yml**
+
+	:::yml
+    SilverStripe\Control\Director:
+      middlewares:
+       - %$CustomMiddleware
+
+Because these are service names, you can configure properties into a custom service if you would
+like:
+
+**mysite/_config/app.yml**
+
+    :::yml
+    SilverStripe\Control\Director:
+      middlewares:
+       - %$ConfiguredMiddleware
+    SilverStripe\Core\Injector\Injector:
+      ConfiguredMiddleware:
+       class: $CustomMiddleware
+       properties:
+         Secret: "DIFFERENT-ONE"
+
+## Route-specific middleware
+
+Alternatively, you can apply middlewares to a specific route. These will be processed after the
+global middlewares. You do this by specifying the "Middlewares" property of the route rule:
+
+**mysite/_config/app.yml**
+
+    :::yml
+    SilverStripe\Control\Director:
+      rules:
+        special\section:
+          Controller: SpecialSectionController
+          Middlewares:
+           - %$CustomMiddleware
+
+## API Documentation
+
+* [api:SilverStripe\Control\HTTPMiddleware]
+

docs/en/02_Developer_Guides/02_Controllers/05_RequestFilters.md

@@ -1,57 +0,0 @@
-title: Request Filters
-summary: Create objects for modifying request and response objects across controllers.
-
-# Request Filters
-
-[api:RequestFilter] is an interface that provides two key methods. `preRequest` and `postRequest`. These methods are 
-executed before and after a request occurs to give developers a hook to modify any global state, add request tracking or
-perform operations wrapped around responses and request objects. A `RequestFilter` is defined as:
-
-**mysite/code/CustomRequestFilter.php**
-
-	:::php
-	<?php
-
-	class CustomRequestFilter implements RequestFilter {
-
-		public function preRequest(HTTPRequest $request, Session $session, DataModel $model) {
-			
-			// if(!something) {
-			// 	By returning 'false' from the preRequest method, request execution will be stopped from continuing.
-			//	return false;
-			// }
-
-			// we can also set any properties onto the request that we need or add any tracking
-			// Foo::bar();
-
-			// return true to continue processing.
-			return true;
-		}
-
-		public function postRequest(HTTPRequest $request, HTTPResponse $response, DataModel $model) {
-			// response is about to be sent.
-			// any modifications or tracking to be done?
-			// Foo::unbar();
-
-			// return true to send the response.
-			return true;
-		}
-	}
-
-After defining the `RequestFilter`, add it as an allowed `filter` through the [Configuration API](../configuration)
-
-**mysite/_config/app.yml**
-
-	:::yml
-	Injector:
-	  RequestProcessor:
-	    properties:
-	      filters:
-	        - '%$CustomRequestFilter'
-
-## API Documentation
-
-* [api:RequestFilter]
-* [api:RequestProcessor]
-
-

docs/en/04_Changelogs/4.0.0.md

@@ -1378,7 +1378,9 @@ After (`mysite/_config/config.yml`):
   * `findAnAdministrator` use `DefaultAdminService::findOrCreateDefaultAdmin()` instead
 * `Member` methods deprecated:
   * `checkPassword`. Use Authenticator::checkPassword() instead
-* `RequestFilter` changed. $session and $dataModel variables removed from preRequest / postRequest
+* `RequestFilter` has been deprecated in favour of
+  [HTTPMiddleware](/developer_guides/controllers/middlewares). Also the legacy RequestFilter
+  API has changed: $session and $dataModel variables removed from preRequest / postRequest.
 
 #### <a name="overview-general-removed"></a>General and Core Removed API