github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs_src/src/guide/advanced/status-handlers.md (about)

     1  ---
     2  meta:
     3    - name: "og:title"
     4      content: "Status Handlers - Goyave"
     5    - name: "twitter:title"
     6      content: "Status Handlers - Goyave"
     7    - name: "title"
     8      content: "Status Handlers - Goyave"
     9  ---
    10  
    11  # Status Handlers <Badge text="Since v2.4.0"/>
    12  
    13  [[toc]]
    14  
    15  ## Introduction
    16  
    17  Status handlers are regular handlers executed during the **finalization** step of the [request's lifecycle](../architecture-concepts.html#requests) if the response body is empty but a status code has been set. Status handler are mainly used to implement a custom behavior for user or server errors (400 and 500 status codes).
    18  
    19  Goyave comes with a default error status handler. When a panic occurs or the [`Response.Error()`](../basics/responses.html#response-error) method is called, the request's status is set to `500 Internal Server Error` and the request error is set. The latter can be accessed using [`Response.GetError()`](../basics/responses.html#response-geterror). The error is printed in the console. If debugging is enabled in the config, the error is also written in the response using the JSON format, and the stacktrace is printed in the console. If debugging is not enabled, the following is returned:
    20  
    21  ``` json
    22  {
    23      "error": "Internal Server Error"
    24  }
    25  ```
    26  
    27  The status handler covering all the other errors in the `400` and `500` status codes ranges has a similar behavior but doesn't print anything to the console. For example, if the user requests a route that doesn't exist, the following is returned:
    28  
    29  ``` json
    30  {
    31      "error": "Not Found"
    32  }
    33  ```
    34  
    35  ## Writing status handlers
    36  
    37  As said earlier, status handlers are regular handlers. The only difference is that they are executed at the very end of the request's lifecycle. Ideally, create a new controller for your status handlers.
    38  
    39  `http/controller/status/status.go`:
    40  ``` go
    41  package status
    42  
    43  import "github.com/System-Glitch/goyave/v2"
    44  
    45  func NotFound(response *goyave.Response, request *goyave.Request) {
    46      if err := response.RenderHTML(response.GetStatus(), "errors/404.html", nil); err != nil {
    47          response.Error(err)
    48      }
    49  }
    50  ```
    51  
    52  ## Registering status handlers
    53  
    54  Status handlers are registered in the **router**.
    55  
    56  #### Router.StatusHandler
    57  
    58  Set a handler for responses with an empty body. The handler will be automatically executed if the request's life-cycle reaches its end and nothing has been written in the response body.
    59  
    60  Multiple status codes can be given. The handler will be executed if one of them matches.
    61  
    62  Status handlers are **inherited** as a copy in sub-routers. Modifying a child's status handler will not modify its parent's. That means that you can define different status handlers for certain route groupes if you so desire.
    63  
    64  | Parameters                  | Return |
    65  |-----------------------------|--------|
    66  | `handler Handler`           | `void` |
    67  | `status int`                |        |
    68  | `additionalStatuses ...int` |        |
    69  
    70  **Example:**
    71  ``` go
    72  func errorStatusHandler(response *Response, request *Request) {
    73  	message := map[string]string{
    74  		"error": http.StatusText(response.GetStatus()),
    75  	}
    76  	response.JSON(response.GetStatus(), message)
    77  }
    78  
    79  // Use "errorStatusHandler" for empty responses having status 404 or 405.
    80  router.StatusHandler(errorStatusHandler, 404, 405)
    81  ```