# Requests
# Introduction
Handlers receive a goyave.Response and a goyave.Request as parameters. This section is a technical reference of the Request object. This object can give you a lot of information about the incoming request, such as its headers, cookies, or body.
All functions below require the goyave package to be imported.
import "goyave.dev/goyave/v4"
# Methods
Request Method Protocol URI Header ContentLength RemoteAddress Cookies Referrer UserAgent CORSOptions ToStruct BasicAuth BearerToken
# Request.Request
Return the raw http request. Prefer using the "goyave.Request" accessors.
| Parameters | Return |
|---|---|
*http.Request |
# Request.Method
The HTTP method (GET, POST, PUT, etc.).
| Parameters | Return |
|---|---|
string |
Example:
fmt.Println(request.Method()) // "GET"
# Request.Protocol
The protocol used by this request, "HTTP/1.1" for example.
| Parameters | Return |
|---|---|
string |
Example:
fmt.Println(request.Protocol()) // "HTTP/1.1"
# Request.URI
URI specifies the URI being requested. Use this if you absolutely need the raw query params, url, etc. Otherwise use the provided methods and fields of the goyave.Request.
| Parameters | Return |
|---|---|
*url.URL |
Example:
fmt.Println(request.URI().Path) // "/foo/bar"
# Request.Header
Header contains the request header fields either received by the server or to be sent by the client. Header names are case-insensitive.
If the raw request has the following header lines,
Host: example.com
accept-encoding: gzip, deflate
Accept-Language: en-us
fOO: Bar
foo: two
then the header map will look like this:
Header = map[string][]string{
"Accept-Encoding": {"gzip, deflate"},
"Accept-Language": {"en-us"},
"Foo": {"Bar", "two"},
}
| Parameters | Return |
|---|---|
http.Header |
Example:
fmt.Println(request.Header().Get("Content-Type")) // "application/json"
# Request.ContentLength
ContentLength records the length (in bytes) of the associated content. The value -1 indicates that the length is unknown.
| Parameters | Return |
|---|---|
int64 |
Example:
fmt.Println(request.ContentLength()) // 758
# Request.RemoteAddress
RemoteAddress allows to record the network address that sent the request, usually for logging.
| Parameters | Return |
|---|---|
string |
Example:
fmt.Println(request.RemoteAddress()) // 192.168.0.10:1234
# Request.Cookies
Cookies returns the HTTP cookies sent with the request.
| Parameters | Return |
|---|---|
[]*http.Cookie |
Example:
cookies := request.Cookies()
fmt.Println(cookies[0].value)
WARNING
Protect yourself from CSRF attacks (opens new window) when using cookies!
# Request.Referrer
Referrer returns the referring URL, if sent in the request.
| Parameters | Return |
|---|---|
string |
Example:
fmt.Println(request.Referrer()) // "https://github.com/go-goyave/goyave/"
# Request.UserAgent
UserAgent returns the client's User-Agent, if sent in the request.
| Parameters | Return |
|---|---|
string |
Example:
fmt.Println(request.UserAgent()) // "Mozilla/5.0 ..."
# Request.CORSOptions
Since v2.3.0
Returns the CORS options applied to this request, or nil. Learn more about CORS here.
The returned object is a copy of the options applied to the router. Therefore, altering the returned object will not alter the router's options.
| Parameters | Return |
|---|---|
*cors.Options |
Example:
fmt.Println(request.CORSOptions().AllowedMethods) // "[HEAD GET POST PUT PATCH DELETE]"
# Request.ToStruct
ToStruct map the request data to a struct. The given "dst" parameter should be a struct pointer.
| Parameters | Return |
|---|---|
dst interface{} | error |
Example:
type UserInsertRequest struct {
Username string
Email string
}
userInsertRequest := UserInsertRequest{}
if err := request.ToStruct(&userInsertRequest); err != nil {
panic(err)
}
fmt.Println(userInsertRequest) // {johndoe johndoe@example.org}
# Request.BasicAuth
Returns the username and password provided in the request's Authorization header, if the request uses HTTP Basic Authentication.
| Parameters | Return |
|---|---|
username string | |
password string | |
ok bool |
Example:
username, password, ok := request.BasicAuth()
fmt.Println(username) // "admin"
fmt.Println(password) // "secret"
fmt.Println(ok) // true
# Request.BearerToken
Since v2.5.0
Extract the auth token from the "Authorization" header. Only takes tokens of type "Bearer".
Returns empty string if no token found or the header is invalid.
| Parameters | Return |
|---|---|
token string | |
ok bool |
Example:
token, ok := request.BearerToken()
fmt.Println(token) // "ey..."
fmt.Println(ok) // true
# Accessors
Since v2.0.0
Accessors are helper functions to retrieve request data without having to write the type assertion. This is helpful to make your controllers cleaner. You shouldn't use these accessors in middleware because they assume the data has been converted by the validation already. Data can still be accessed through the Data attribute. There is currently no accessor for slices.
# Request.Has
Check if the given field exists in the request data.
| Parameters | Return |
|---|---|
field string | bool |
Example:
fmt.Println(request.Has("name")) // true
# Request.String
Get a string field from the request data. Panics if the field is not a string or doesn't exist.
| Parameters | Return |
|---|---|
field string | string |
Example:
fmt.Println(request.String("name")) // "JohnDoe"
# Request.Numeric
Get a numeric field from the request data. Panics if the field is not numeric or doesn't exist.
| Parameters | Return |
|---|---|
field string | float64 |
Example:
fmt.Println(request.Numeric("price")) // 42.3
# Request.Integer
Get an integer field from the request data. Panics if the field is not an integer or doesn't exist.
| Parameters | Return |
|---|---|
field string | int |
Example:
fmt.Println(request.Integer("age")) // 32
# Request.Bool
Get a bool field from the request data. Panics if the field is not a bool or doesn't exist.
| Parameters | Return |
|---|---|
field string | bool |
Example:
fmt.Println(request.Bool("EULA")) // true
# Request.File
Get a file field from the request data. Panics if the field is not a file or doesn't exist.
| Parameters | Return |
|---|---|
field string | []fsutil.File |
Example:
for _, f := range request.File("images") {
fmt.Println(f.Header.Filename)
}
# Request.Timezone
Get a timezone field from the request data. Panics if the field is not a timezone or doesn't exist.
| Parameters | Return |
|---|---|
field string | *time.Location |
Example:
fmt.Println(request.Timezone("tz").String()) // "America/New_York"
# Request.IP
Get an IP field from the request data. Panics if the field is not an IP or doesn't exist.
| Parameters | Return |
|---|---|
field string | net.IP |
Example:
fmt.Println(request.IP("host").String()) // "127.0.0.1"
# Request.URL
Get a URL field from the request data. Panics if the field is not a URL or doesn't exist.
| Parameters | Return |
|---|---|
field string | *url.URL |
Example:
fmt.Println(request.URL("link").String()) // "https://google.com"
# Request.UUID
Get a UUID field from the request data. Panics if the field is not a UUID or doesn't exist.
| Parameters | Return |
|---|---|
field string | uuid.UUID |
Example:
fmt.Println(request.UUID("id").String()) // "3bbcee75-cecc-5b56-8031-b6641c1ed1f1"
# Request.Date
Get a date field from the request data. Panics if the field is not a date or doesn't exist.
| Parameters | Return |
|---|---|
field string | time.Time |
Example:
fmt.Println(request.Date("birthdate").String()) // "2019-11-21 00:00:00 +0000 UTC"
# Request.Object
Get an object field from the request data. Panics if the field is not an object or doesn't exist.
| Parameters | Return |
|---|---|
field string | map[string]interface{} |
Example:
fmt.Println(request.Object("object")) // map[hello:world]
# Attributes
# Request.Rules
The validation rule set associated with this request. See the validation section for more information.
# Request.Data
A map[string]interface{} containing the request's data. The key is the name of the field. This map contains the data from the request's body and the URL query string values. The request's body parameters takes precedence over the URL query string values.
For the given JSON request:
{
"name": "John Doe",
"tags": ["tag1", "tag2"]
}
fmt.Println(request.Data["name"]) // "John Doe"
fmt.Println(request.Data["tags"]) // "[tag1 tag2]" ([]string)
You would obtain the same result for the following url-encoded request:
name=John%20Doe&tags=tag1&tags=tag2
Because the Data attribute can hold any type of data, you will likely need type assertion. If you validated your request, checking for type assertion errors is not necessary.
tags, _ := request.Data["tags"].([]string)
# Request.Params
Params is a map[string]string of the route parameters.
For the given route definition and request:
/categories/{category}/{product_id}
/categories/3/5
fmt.Println(request.Params["category"]) // "3"
fmt.Println(request.Params["product_id"]) // "5"
# Request.Lang
Lang indicates the language desired by the user. This attribute is automatically set by a core middleware, based on the Accept-Language header, if present. If the desired language is not available, the default language is used.
Learn more in the localization section.
fmt.Println(request.Lang) // "en-US"
fmt.Println(lang.Get(request.Lang, "validation.rules.required")) // "The :field is required."
# Request.Extra
Since v3.3.0
Extra is a map[string]interface{} meant to contain extra data, which is not part of the request body (request.Data). This allows middleware to process some data and pass it to other handlers.
Example:
func MyCustomMiddleware(next goyave.Handler) goyave.Handler {
return func(response *goyave.Response, request *goyave.Request) {
request.Extra["custom"] = "extra data"
next(response, request) // Pass to the next handler with the extra data
}
}
# Request.User
Since v2.5.0
User is an interface{} containing the authenticated user if the route is protected, nil otherwise.
Learn more in the authentication section.
Example:
fmt.Println(request.User.(*model.User).Name) // "John Doe"