From c482cd673ef121aa22180b9e4a647d031fcfa819 Mon Sep 17 00:00:00 2001 From: Sam Minnee Date: Fri, 23 Jun 2017 11:43:19 +1200 Subject: [PATCH] DOC: Documentation and upgrade notes for director middleware --- .../02_Controllers/05_Middlewares.md | 99 +++++++++++++++++++ .../02_Controllers/05_RequestFilters.md | 57 ----------- docs/en/04_Changelogs/4.0.0.md | 4 +- 3 files changed, 102 insertions(+), 58 deletions(-) create mode 100644 docs/en/02_Developer_Guides/02_Controllers/05_Middlewares.md delete mode 100644 docs/en/02_Developer_Guides/02_Controllers/05_RequestFilters.md diff --git a/docs/en/02_Developer_Guides/02_Controllers/05_Middlewares.md b/docs/en/02_Developer_Guides/02_Controllers/05_Middlewares.md new file mode 100644 index 000000000..a97a5d2f6 --- /dev/null +++ b/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 + 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] + diff --git a/docs/en/02_Developer_Guides/02_Controllers/05_RequestFilters.md b/docs/en/02_Developer_Guides/02_Controllers/05_RequestFilters.md deleted file mode 100644 index 4761064da..000000000 --- a/docs/en/02_Developer_Guides/02_Controllers/05_RequestFilters.md +++ /dev/null @@ -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 - General and Core Removed API