diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..722d5e7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..f888558 --- /dev/null +++ b/Configuration.md @@ -0,0 +1,113 @@ +At the [[previous|Host]] section we've learnt about the first input argument of the `app.Run`, here we will take a look of what the second one is. + +Let's start from basics. The `iris.New` function returns an `iris.Application`. This Application value can be configured through its `Configure(...iris.Configurator)` and `Run` methods. + +The second optional, varadiac argument of `app.Run` method accepts one or more `iris.Configurator`. An `iris.Configurator` is just a type of: `func(app *iris.Application)`. Custom `iris.Configurator` can be passed to modify yours `*iris.Application` as well. + +There are built-in`iris.Configurator`s for each of the core [Configuration](https://godoc.org/github.com/kataras/iris#Configuration), such as `iris.WithoutStartupLog`, `iris.WithCharset("UTF-8")`, `iris.WithOptimizations` and `iris.WithConfiguration(iris.Configuration)` functions. + +Each “module” like the iris view engine, websockets, sessions and each middleware has its own configurations and options, most of them, separately from the core configuration. + +## Using the [Configuration](https://godoc.org/github.com/kataras/iris#Configuration) + +The only one configuration structure is the `iris.Configuration`. Let's start by that one which can be passed on the `iris.WithConfiguration` function to make it an `iris.Configurator`. + +All of the `iris.Configuration` fields are defaulted to the most common use cases. Iris doesn’t need any configuration before its `app.Run` but if you want to make use of a custom `iris.Configurator` before the server runs then you can use the `app.Configure` method to pass the configurator(s) there. + +```go +config := iris.WithConfiguration(iris.Configuration { + DisableStartupLog: true, + Optimizations: true, + Charset: "UTF-8", +}) + +app.Run(iris.Addr(":8080"), config) +``` + +### Load from [YAML](https://yaml.org/) + +Using the `iris.YAML("path")`. + +File: **iris.yml** + +```yaml +FireMethodNotAllowed: true +DisableBodyConsumptionOnUnmarshal: true +TimeFormat: Mon, 01 Jan 2006 15:04:05 GMT +Charset: UTF-8 +``` + +File: **main.go** + +```go +config := iris.WithConfiguration(iris.YAML("./iris.yml")) +app.Run(iris.Addr(":8080"), config) +``` + +### Load from [TOML](https://github.com/toml-lang/toml) + +Using the `iris.TOML("path")`. + +File: **iris.tml** + +```toml +FireMethodNotAllowed = true +DisableBodyConsumptionOnUnmarshal = false +TimeFormat = "Mon, 01 Jan 2006 15:04:05 GMT" +Charset = "UTF-8" + +[Other] + ServerName = "my fancy iris server" + ServerOwner = "admin@example.com" +``` + +File: **main.go** + +```go +config := iris.WithConfiguration(iris.TOML("./iris.tml")) +app.Run(iris.Addr(":8080"), config) +``` + +## Using the functional way + +As we already mention, you can pass any number of `iris.Configurator` in the `app.Run`’s second argument. Iris provides an option for each of its `iris.Configuration`’s fields. + +```go +app.Run(iris.Addr(":8080"), iris.WithoutInterruptHandler, + iris.WithoutServerError(iris.ErrServerClosed), + iris.WithoutBodyConsumptionOnUnmarshal, + iris.WithoutAutoFireStatusCode, + iris.WithOptimizations, + iris.WithTimeFormat("Mon, 01 Jan 2006 15:04:05 GMT"), +) +``` + +Good when you want to change some of the configuration's field. +Prefix: "With" or "Without", code editors will help you navigate through all +configuration options without even a glitch to the documentation. + +## Custom values + +The `iris.Configuration` contains a field called `Other map[string]interface{}` which accepts any custom `key:value` option, therefore you can use that field to pass specific values that your app expects based on the custom requirements. + +```go +app.Run(iris.Addr(":8080"), + iris.WithOtherValue("ServerName", "my amazing iris server"), + iris.WithOtherValue("ServerOwner", "admin@example.com"), +) +``` + +You can access those fields via `app.ConfigurationReadOnly`. + +```go +serverName := app.ConfigurationReadOnly().Other["MyServerName"] +serverOwner := app.ConfigurationReadOnly().Other["ServerOwner"] +``` + +## Access Configuration from Context + +Inside a handler, retrieve those fields using the following: + +```go +ctx.Application().ConfigurationReadOnly() +``` diff --git a/Home.md b/Home.md index d4c3213..1057810 100644 --- a/Home.md +++ b/Home.md @@ -9,6 +9,7 @@ This wiki is the main source of documentation for **developers** working with (o * [[Installing Iris|Installation]] * [[Getting Started]] * [[Host]] +* [[Configuration]] * [[Routing]] * [[Path Parameter Types|Routing-path-parameter-types]] * [[Reverse Lookups|Routing-reverse-lookups]] diff --git a/Host.md b/Host.md index 5d7eb46..97babcd 100644 --- a/Host.md +++ b/Host.md @@ -247,3 +247,5 @@ func main() { app.Run(iris.Addr(":8080"), iris.WithoutInterruptHandler) } ``` + +Continue reading the [[Configuration]] section to learn about `app.Run`'s second variadic argument. \ No newline at end of file diff --git a/Routing.md b/Routing.md index 971e969..c9cb9f6 100644 --- a/Routing.md +++ b/Routing.md @@ -127,4 +127,56 @@ app.PartyFunc("/users", func(users iris.Party) { }) ``` -You may wonder what the `{id:uint64}` is. It's a (typed) dynamic path parameter, learn more by reading the [[Path Parameter Types|Routing-path-parameter-types]]. +Unlike other routers you'd seen, the Iris' one can handle various route paths without confliction between them. + +Matches all GET requests prefixed with `"/assets/**/*"`, it's a wildcard with `ctx.Params().Get("asset")` equals to any following path after the `/assets/`. + +```go +app.Get("/assets/{asset:path}", assetsWildcardHandler) +``` + +Matches only GET "/". + +```go +app.Get("/", indexHandler) +``` + +Matches all GET requests prefixed with `"/profile/"` +and followed by a single path part. + +```go +app.Get("/profile/{username:string}", userHandler) +``` + +Matches only GET `"/profile/me"` and +it does not conflict with `/profile/{username:string}` +or any root wildcard `/{root:path}`. + +```go +app.Get("/profile/me", userHandler) +``` + + +Matches all GET requests prefixed with `/users/` +and followed by a number which should be equal or higher than 1. + +```go +app.Get("/user/{userid:int min(1)}", getUserHandler) +``` + +Matches all requests DELETE prefixed with `/users/` +and following by a number which should be equal or higher than 1. + +```go +app.Delete("/user/{userid:int min(1)}", deleteUserHandler) +``` + + +Matches all GET requests except "/", "/about", anything starts with "/assets/" and the above we've already registered. +It does not conflict with the rest of the routes(!). + +```go +app.Get("{root:path}", rootWildcardHandler) +``` + +You may wonder what the `{id:uint64}` or `:path` , `min(1)` are. They are (typed) dynamic path parameters and functions can be registered on them. Learn more by reading the [[Path Parameter Types|Routing-path-parameter-types]]. diff --git a/_Sidebar.md b/_Sidebar.md index 3e3ec61..a15e7c5 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -4,6 +4,7 @@ * [[Installing Iris|Installation]] * [[Getting Started]] * [[Host]] +* [[Configuration]] * [[Routing]] * [[Path Parameter Types|Routing-path-parameter-types]] * [[Reverse Lookups|Routing-reverse-lookups]]