mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-06-14 18:25:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

noot

Browse source
This commit is contained in:
a 2024-07-25 15:48:03 -05:00
parent 2419a71643
commit 32f48b51ec
No known key found for this signature in database
GPG key ID: 374BC539FE795AF0
1 changed files with 19 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

29
src/docs/markdown/extending-caddy/placeholders.md
View file

@ -2,13 +2,21 @@
title: "Placeholder Support"
---
# Placeholder Parsing Rules
# Placeholders
Support for placeholders which do not start with a dollar sign (e.g. `{env.HOST}`) must be handled by the individual plugin, and will not be handled by the Caddyfile parser.
In Caddy, placeholders are a feature of the individual plugins, that is, they are not parsed at config time, but instead preserved, and replaced at runtime.
This means that if you wish for your plugin to support placeholders, you must explicitly add support for it.
## Placeholder Parsing Rules & Gotchas
Support for any placeholders which do not start with a dollar sign (e.g. `{env.HOST}`) must be handled by the individual plugin, and will not be handled by the Caddyfile parser.
If you wish to use placeholders in your Caddy plugin, you must accept such placeholders as valid configuration values, and parse them at runtime
Placeholders which do start with a dollar sign (`{$HOST}`), are evaulated at Caddyfile parse time, and do not need to be dealt with by your plugin
Placeholders which do start with a dollar sign (`{$HOST}`), are evaulated at Caddyfile parse time, and do not need to be dealt with by your plugin. These are technically not placeholders, but config-time env var substitution, they just happen to share the `{}` syntax. our
It is therefore important to understand that `{env.HOST}` is inherently different from something like `{$HOST}`
As an example, see the following caddyfile:
```
@ -71,13 +79,14 @@ Since `srv0` used `{$ENV}`, the special environmental variable placeholder with
Since `srv1` used `{env.HOST}`, a standard placeholder, it was parsed as a normal string value for "body" field of the respond directive's config.
This means that down the line, the handler plugins will receive both `example` and `{env.Host}` respectively in their configurations.
## Using Placeholders in your Plugin
#### Parsing Placeholders in your Unmarshaler
#### How to parse Placeholders in your Unmarshaler
Placeholders should be parsed as their raw values when parsing caddyfiles, just like any other string value
```go
func (g *Gizmo) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
d.Next()
@ -85,12 +94,12 @@ func (g *Gizmo) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
// not enough args
return d.ArgErr()
}
}
```
#### How to resolve Placeholders during Serve or Match
#### Resolving Placeholders at Match/Serve time
In order to correctly read our `g.Name` placeholder, in a plugin matcher or middleware, we must extract the replacer from the context, and use that replacer on our saved placeholder string.
In order to now correctly read our `g.Name` placeholder, in a plugin matcher or middleware, we must extract the replacer from the context, and use that replacer on our saved placeholder string.
```go
func (g *Gizmo) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
@ -103,9 +112,9 @@ func (g *Gizmo) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp
}
```
#### Resolving Placeholers at Provision time
#### How to resolve Placeholders at Provision time
If you only use global placeholders, like `env`, then you may also use the replacer at provision time
If you only use global placeholders, like `env`, then you may initialize a global replacer at provision time, and use it to replace such values.
```go
func (g *Gizmo) Provision(ctx caddy.Context) error {