diff --git a/Converting-Add-ons-to-Plugins.md b/Converting-Add-ons-to-Plugins.md new file mode 100644 index 0000000..20c61bc --- /dev/null +++ b/Converting-Add-ons-to-Plugins.md @@ -0,0 +1,110 @@ +Caddy prior to version 0.9 had "add-ons" but Caddy 0.9+ has "plugins" which give more flexibility. Add-ons need to be converted to plugins if they are to be used in newer version of Caddy or made available on the Caddy website. + +(Remember, this guide is for _existing_ add-ons that are already recognized by Caddy. To create a new plugin from scratch, start with [Extending Caddy](https://github.com/mholt/caddy/wiki/Extending-Caddy).) + +The switch from add-on to plugin can usually be done in a few minutes, or almost always less than an hour. Your actual handler will not need to change much; most of the changes are with the setup function and its tests. + +The basic steps are: + +1. Search and replace +2. Change setup function +3. Update setup tests +4. Register plugin + + +## 1. Search and replace + +Search for the text on the left and replace with the text on the right (exact values, case-sensitive): + +- `middleware.` --> `httpserver.` +- `/caddy/middleware" --> `/caddy/caddyhttp/httpserver"` +- `setup.` --> `caddy.` + +**Delete:** + +- Any imports to `github.com/mholt/caddy/caddy/setup` that may remain +- Any imports to `github.com/mholt/caddy/middleware` that may remain + +**Add:** + +- Import `github.com/mholt/caddy` where needed +- Import `github.com/mholt/caddy/caddyhttp/httpserver` where needed + + +## 2. Change setup function + +If you had a setup function like this: + +```go +func Setup(c *setup.Controller) (middleware.Middleware, error) { + ... +} +``` + +Change it to this: + +```go +func setup(c *caddy.Controller) error { + ... +} +``` + +The setup function does not need to be exported, but you may capitalize it to export it if you wish. + +Instead of accessing site config values directly like `c.Root` or `c.Host`, get the config from the HTTP server using the key from the controller: + +```go +siteConfig := httpserver.GetConfig(c.Key) +``` + +Instead of adding startup callbacks by appending to `c.Startup` , call `c.OnStartup()` and pass in the function: + +```go +// or use OnRestart and OnShutdown +c.OnStartup(func() error { + ... +}) +``` + +Instead of returning a middleware, call `cfg.AddMiddleware()` (where cfg is the site config you got earlier) and pass in your middleware instance: + +```go +cfg.AddMiddleware(func(next httpserver.Handler) httpserver.Handler { + handler.Next = next + return handler +}) +``` + +## 3. Update setup tests + +Instead of calling `setup.NewTestController()` like you did before, call `caddy.NewTestController()`: + +```go +c := caddy.NewTestController(input) +``` + +To test that the middleware was set up properly, you'll need to get the config it was added to. The test controller uses an empty string key: + +```go +cfg := httpserver.GetConfig("") +mids := cfg.Middleware() // []Middleware +``` + +From there, you'll usually want the last middleware in the list, `mids[len(mids)-1]`. If you're not in a loop you can just assume `mids[0]`. Of course, if you didn't add any middleware, you can omit these checks. + +## 4. Register plugin + +In your plugin's package (usually by the setup function, if there's not already an `init()` function), create an `init()` function to register your plugin with Caddy: + +```go +func init() { + caddy.RegisterPlugin("directive", caddy.Plugin{ + ServerType: "http", + Action: setup, + }) +} +``` + +Replace `"directive"` with the name of your plugin's directive and `setup` with the name of your setup function. The setup function does not need to be exported anymore if you choose. + +Now give it a try to make sure everything works, and re-run your tests. Push your changes when everything looks good and we'll be updating the build server with the new 0.9 plugins soon. \ No newline at end of file